Project documentation is as diverse as the projects themselves and Material for MkDocs is a great starting point for making it look beautiful. However, as you write your documentation, you may reach a point where small adjustments are necessary to preserve your brand's style.
If you want to tweak some colors or change the spacing of certain elements, you can do this in a separate style sheet. The easiest way is by creating a new style sheet file in the
Then, add the following lines to
Then, add the following lines to
Extending the theme¶
If you want to alter the HTML source (e.g. add or remove some parts), you can extend the theme. MkDocs supports theme extension, an easy way to override parts of Material for MkDocs without forking from git. This ensures that you can update to the latest version more easily.
Setup and theme structure¶
Enable Material for MkDocs as usual in
mkdocs.yml, and create a new folder for
overrides which you then reference using the
Theme extension prerequisites
custom_dir setting is used for the theme extension process, Material for MkDocs needs to be installed via
pip and referenced with the
name setting in
mkdocs.yml. It will not work when cloning from
The structure in the
overrides directory must mirror the directory structure of the original theme, as any file in the
overrides directory will replace the file with the same name which is part of the original theme. Besides, further assets may also be put in the
In order to override a partial, we can replace it with a file of the same name and location in the
overrides directory. For example, to replace the original
footer.html partial, create a new
footer.html partial in the
MkDocs will now use the new partial when rendering the theme. This can be done with any file.
Overriding blocks recommended¶
Besides overriding partials, it's also possible to override (and extend) template blocks, which are defined inside the templates and wrap specific features. In order to set up block overrides, create a
main.html file inside the
Then, e.g. to override the site title, add the following lines to
The following template blocks are provided by the theme:
| ||Wraps the Google Analytics integration|
| ||Wraps the announcement bar|
| ||Wraps the main content|
| ||Empty block to add custom meta tags|
| ||Wraps the font definitions|
| ||Wraps the footer with navigation and copyright|
| ||Wraps the fixed header bar|
| ||Wraps the hero teaser (if available)|
| ||Wraps the |
| ||Wraps the version warning|
| ||Wraps the meta tags in the document head|
| ||Wraps the site navigation and table of contents|
| ||Wraps the style sheets (also extra sources)|
| ||Wraps the tabs navigation (if available)|
Material for MkDocs is built on top of TypeScript, RxJS and SASS, and uses a lean, custom build process to put everything together.1 If you want to make more fundamental changes, it may be necessary to make the adjustments directly in the source of the theme and recompile it.
In order to start development on Material for MkDocs, a Node.js version of at least 14 is required. First, clone the repository:
Next, all dependencies need to be installed, which is done with:
Start the watcher with:
Then, in a second terminal window, start the MkDocs live preview server with:
Point your browser to localhost:8000 and you should see this very documentation in front of you.
Automatically generated files
Never make any changes in the
material directory, as the contents of this directory are automatically generated from the
src directory and will be overwritten when the theme is built.
Building the theme¶
When you're finished making your changes, you can build the theme by invoking:
material directory. When running
mkdocs build, you should now see your changes to the original theme.
Prior to 7.0.0 the build was based on Webpack, resulting in occasional broken builds due to incompatibilities with loaders and plugins. Therefore, we decided to swap Webpack for a leaner solution which is now based on RxJS as the application itself. This allowed for the pruning of more than 500 dependencies (~30% less). ↩