Theme extensions, custom_dir, and overrides

[bradumbaugh]

Hi @squidfunk,

Been playing a bit with theme extension, and have a couple of questions. Sorry if this is a pedantic question, just trying to make sure I understand how this works.

The docs about extending the theme say:

Enable Material for MkDocs as usual in mkdocs.yml, and create a new folder for overrides which you then reference using the custom_dir key

Immediately below that text, there's an admonition:

As the custom_dir variable is used for the theme extension process, Material for MkDocs needs to be installed via pip and referenced with the name parameter in mkdocs.yml. It will not work when cloning from git.

However, in the mkdocs.yml file of the mkdocs-material repository, I see this bit of configuration, which doesn't follow those instructions (custom_dir points to material, not overrides):

theme:  
   name: null  
   custom_dir: material

A few questions:

1. Does this mean that the website for MkDocs Material is published without pip, and just references the entire theme, which is included in the material folder (which looks like a copy of the src folder)?

2. If that's true, what is material/overrides? It looks like a collection of minimized assets, and a custom template.... but I assume these files aren't "theme extensions" (since—based on the instructions I mentioned above—to use theme extensions, theme.name would have to be set in mkdocs.yml). But the name of the folder—overrides—trips me up. Which leads me to question 3...

3. Is this a different overrides than mentioned here? If it is, I wonder if changing the name of the folder to something distinct might alleviate a bit of confusion for peope like me who are inspecting the repository for help getting started.

4. When using git to install a theme, is this the best way to customize it? That is, include the whole theme, point custom_dir to its directory, and update the theme files directly in that directory (which would obviously make it a more manual process to apply future theme updates)?

In general, my plan for theme extension is to follow these instructions, but I'm just examining the configuration of the MkDocs Material website and want to be sure I'm understanding what I'm seeing.

Thank you for your time!

[squidfunk]

1. Yes. The theme has to jump through some hoops to make overrides work, because of the limitations stated in the documentation, as the theme's documentation itself is built from custom_dir. This is why on every page there's an explicit reference to the overridden template. The src folder contains the TypeScript and SASS sources which are compiled to JavaScript and CSS and copied over to the material folder.

2. Yes, those are custom overrides for the theme's own documentation like for example icon search and the landing page.

3. Yes and no, see 1. I understand that this can cause confusion, but you're the first to note and since those are essentially overrides, I'd rather not change it to something else which might cause even more confusion.

4. Theme extension after cloning from git is discouraged for the reasons you stated. I understand that this is mainly how Jekyll themes work, but it complicates future updates. Material for MkDocs goes to great lengths to make theme extension easy while trying to guarantee backward compatibility in major version ranges. Better use:

   pip install git+https://github.com/squidfunk/mkdocs-material