Altering Breakpoints?

[ReessKennedy]

Loving MKDocs Material but having a terrible time trying to alter breakpoints so the main left sidebar isn't triggered so soon! ...

Things tried:

1. Plain CSS overrides - This proved very tricky given it does not seem like a simple "display: block" or "display: none" sitution and a bunch of other experiments here failed.
2. Setting new SCSS vars and recompiling - I downloaded the main material repo the live compiler plugin for VS Code and then tried to open up "main.scss" and got an error "27 │ @import "material-color";" ... saying it does not exist ... which is true. Looks like first two SCSS fils aren't in this directory. I was hoping I could just edit the config.scss with new widths and be on my way. Content of config are included below ... and I have search around but having a tough time seeing anyone who has success in doing this. Any help is greatly appreciated!!! Maybe I overlooked a source.

I should note that I am looking for the simplest solution. I will do whatever it takes but would like to not have to recompile the SCSS in favor of just a CSS override since it's easier to just write this into an overrides folder, it seems.

// Device-specific breakpoints
$break-devices: (
  mobile: (
    portrait:  px2em(220px)  px2em(479.75px),
    landscape: px2em(480px)  px2em(719.75px)
  ),
  tablet: (
    portrait:  px2em(720px)  px2em(959.75px),
    landscape: px2em(960px)  px2em(1219.75px)
  ),
  screen: (
    small:     px2em(1220px) px2em(1599.75px),
    medium:    px2em(1600px) px2em(1999.75px),
    large:     px2em(2000px)
  )
);

[squidfunk]

Thanks for asking. I've talked about this a few times – it's unfortunately not that simple. As soon as @custom-media arrives, it's easy, but until then, customizing breakpoints requires you to go through recompilation:

• Is there an option to show the hamburger left menu by default? #3210

I'm not sure what "live compiler" you're using, but if you stick to our theme development process, you should be good to go.

Closing as duplicate of #3210.

[ReessKennedy]

I successfully set up MKDocs locally and I have successfully set the custom_dir to a folder where I can place overrides but I still don't seem to be able to alter the break points with SCSS vars.

I know the overrides folder path is right because it works to alter HTML when I place in a replacement but SCSS remains stubborn. I believe I have followed the proper directory structure. See below.

I am just placing large values in mobile and tablet in an effort disable completely for testing and I placed it in main.scss with the thought that it would at least alter the look of the page but no difference, leading me to believe I am missing something!

[kamilkrzyskow]

Hello @ReessKennedy,
you cannot use the overrides approach with SCSS files, as those need to be recompiled. You can only use the overrides approach with files inside the material/templates directory: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates

Currently the best approach is to follow the theme development guide and recompile it, as squidfunk said above.

^{Also your overrides directory seems to be inside the docs directory, which isn't ideal, best to put it outside it, next to mkdocs.yml.}

[kamilkrzyskow]

Another approach would be to use CSS, similarly to this:

• Problems styling the page header the way I want it #6639 (reply in thread)

However, as pointed out by Alex here:

• How to keep navigation pane with narrower windows? #6785 (comment)

this could be fragile. As because of the lovely floating point imprecision, the value I used in the answer (max-width: 76.2344em) is currently (max-width: 76.234375em), so basically the same, but "more precise". I don't know if the value is simply imprecise because of floating point imprecision or maybe some dependency in SCSS-px2em-land has changed and the calculated value with it.
Even though it varies only slightly it could still create a "flashing" break point where the state of the site quickly snapshots between them, but perhaps this is sufficient.

[kamilkrzyskow]

To avoid the possible imprecision of CSS overrides, and avoid SCSS recompilation, you could go even further into the depths of hacky solutions and create a hook to modify the compiled CSS and modify all of the @media queries with a width value within it.
Similar to the approach here with hacky JavaScript replacement:

• Disabling media pause when switching content tabs. #6844 (reply in thread)

  Note that the solution for JavaScript expected one range of characters to be replaced, and here there would be multiple, as there are many @media queries.

You'd have to use some regex to target the appropriate selectors and then modify them directly in the file.

[ReessKennedy]

Thanks @kamilkrzyskow ... I am going to keep plugging away with your suggestions. What about when building mkdocs-material via Github actions? I get that you could compile your SCSS to CSS but my Github actions is still install via pip ... would I have go even further to somewhat either get my own package on pip? Or install from a public git repo that contains the compiled?
... I guess I have to first create a new, compiled css with my breakpoint edits and then I could throw that into the overrides folder in proper spot and then I'd just have to update this if there are html changes to MKDocs-Material and recompile and update newer css.

[kamilkrzyskow]

Using GitHub Actions is surely an option, but the endeavour is a bit too complex for me to make some kind of proof of concept.
However, here are some pointers (I don't use Docker, so perhaps I'm ignorant to some kind of easier process, keep that in mind):

The tricky part is that you can't really merge branches of compiled files as those will always create some sort of merge conflict, between 2 compilation sources. So either you have to checkout 2 branches, and merge them via simple copy-paste and push the compiled result to a new branch, or keep a branch with your changes, but without re-compiled CSS, so a merge won't cause issues, I'm going with the latter:

1. Create a fork of https://github.com/squidfunk/mkdocs-material
2. Keep the master branch clean without any changes, you'll be updating it from time to time to update the version.
3. Create another branch custom-changes with your changes to the breakpoints in the SCSS file, but don't recompile them to the material directory, so the changes should only be in the src. Additionally add a workflow file you'll be running manually.
4. The GitHub action in step 3 should create a branch custom-theme that is the result of custom-changes rebased onto master, later compile the theme, commit and force push it to the fork repository. The way to build the project with workflows is described here: https://github.com/squidfunk/mkdocs-material/blob/master/.github/workflows/build.yml
5. You can install a branch of a repository using pip install git+https://github.com/username/repository.git@branch_name, you don't need to release a package on PyPi

compiled css with my breakpoint edits and then I could throw that into the overrides folder in proper spot

Each recompiled CSS has a different hash in the file name for cache busting, if you go with that approach you have to keep that in mind and sync the names properly.

[squidfunk]

We'll definitely be looking into how we can make this easier in the future. This has been asked for so many times, we need to find a way. I have some ideas how to make breakpoints configurable, but it's going to be a stretch goal.

[ReessKennedy]

Oh man! Thanks @kamilkrzyskow for the detailed detail on this! What an amazing community Github is (and open source, in general) that there are folks like you willing to carefully share experience with the world.