10 KiB
| template |
|---|
| overrides/main.html |
Customization
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.
Adding assets
MkDocs provides several ways to customize a theme. In order to make a few
tweaks to Material for MkDocs, you can just add your stylesheets and JavaScript
files to the docs directory.
Additional CSS
If you want to tweak some colors or change the spacing of certain elements,
you can do this in a separate stylesheet. The easiest way is by creating a
new stylesheet file in the docs directory:
.
├─ docs/
│ └─ stylesheets/
│ └─ extra.css
└─ mkdocs.yml
Then, add the following line to mkdocs.yml:
extra_css:
- stylesheets/extra.css
Spin up the live preview server and start typing your changes in your additional style sheet file – you should see them almost instantly after saving.
Additional JavaScript
The same is true for additional JavaScript. If you want to integrate another
syntax highlighter or add some custom logic to your theme, create a new
JavaScript file in the docs directory:
.
├─ docs/
│ └─ javascripts/
│ └─ extra.js
└─ mkdocs.yml
Then, add the following line to mkdocs.yml:
extra_javascript:
- javascripts/extra.js
Further assistance can be found in the MkDocs documentation.
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 custom_dir key:
theme:
name: material
custom_dir: overrides
!!! warning "Theme extension prerequisites"
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`.
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 overrides directory.
The directory layout of the theme is as follows:
.
├─ .icons/ # Bundled icon sets
├─ assets/
│ ├─ images/ # Images and icons
│ ├─ javascripts/ # JavaScript
│ └─ stylesheets/ # Stylesheets
├─ partials/
│ ├─ integrations/ # Third-party integrations
│ │ ├─ analytics.html # - Google Analytics
│ │ └─ disqus.html # - Disqus
│ ├─ languages/ # Localized languages
│ ├─ footer.html # Footer bar
│ ├─ header.html # Header bar
│ ├─ language.html # Localized labels
│ ├─ logo.html # Logo in header and sidebar
│ ├─ nav.html # Main navigation
│ ├─ nav-item.html # Main navigation item
│ ├─ palette.html # Color palette
│ ├─ search.html # Search box
│ ├─ social.html # Social links
│ ├─ source.html # Repository information
│ ├─ source-date.html # Last updated date
│ ├─ source-link.html # Link to source file
│ ├─ tabs.html # Tabs navigation
│ ├─ tabs-item.html # Tabs navigation item
│ ├─ toc.html # Table of contents
│ └─ toc-item.html # Table of contents item
├─ 404.html # 404 error page
├─ base.html # Base template
└─ main.html # Default page
Overriding partials
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, create a footer.html file in the overrides/partials
directory:
.
├─ overrides/
│ └─ partials/
│ └─ footer.html
└─ mkdocs.yml
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. To override a block, create a main.html file inside the overrides
directory:
.
├─ overrides/
│ └─ main.html
└─ mkdocs.yml
Then, e.g. to override the site title, add the following line to main.html:
{% extends "base.html" %}
{% block htmltitle %}
<title>Lorem ipsum dolor sit amet</title>
{% endblock %}
Material for MkDocs provides the following template blocks:
| Block name | Purpose |
|---|---|
analytics |
Wraps the Google Analytics integration |
announce |
Wraps the announcement bar |
config |
Wraps the JavaScript application config |
content |
Wraps the main content |
disqus |
Wraps the Disqus integration |
extrahead |
Empty block to add custom meta tags |
fonts |
Wraps the font definitions |
footer |
Wraps the footer with navigation and copyright |
header |
Wraps the fixed header bar |
hero |
Wraps the hero teaser (if available) |
htmltitle |
Wraps the <title> tag |
libs |
Wraps the JavaScript libraries (header) |
outdated |
Wraps the version warning |
scripts |
Wraps the JavaScript application (footer) |
source |
Wraps the linked source files |
site_meta |
Wraps the meta tags in the document head |
site_nav |
Wraps the site navigation and table of contents |
styles |
Wraps the stylesheets (also extra sources) |
tabs |
Wraps the tabs navigation (if available) |
For more on this topic refer to the MkDocs documentation.
Additional variables
Besides template blocks, Material for MkDocs provides extra variables for parts
that cannot be overridden with template blocks (due to technical limitations of
the template engine). If you want to add further information after the Made
with Material for MkDocs hint in the footer, add the following line to
main.html:
{% extends "base.html" %}
{% set extracopyright %}
<!-- Add your additional information here -->
{% endset %}
Material for MkDocs provides the following additional variables:
| Block name | Purpose |
|---|---|
extracopyright |
Adds custom copyright information |
Theme development
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.
Environment setup
In order to start development on Material for MkDocs, a Node.js version of at least 14 is required. First, clone the repository:
git clone https://github.com/squidfunk/mkdocs-material
Next, all dependencies need to be installed, which is done with:
cd mkdocs-material
pip install -r requirements.txt
pip install mkdocs-minify-plugin
pip install mkdocs-redirects
npm install
Development mode
Start the watcher with:
npm start
Then, in a second session, start the MkDocs live preview server with:
mkdocs serve
Point your browser to localhost:8000 and you should see this documentation in front of you.
!!! warning "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:
npm run build
This triggers the production-level compilation and minification of all
stylesheets and JavaScript sources. When the command exits, the final files are
located in the material directory. Add the theme_dir variable pointing to
the aforementioned directory in the original mkdocs.yml.
Now you can run mkdocs build and you should see your documentation with your
changes to the original theme.
-
Prior to version 7.0, the build was based on Webpack. This led to broken builds due to frequent incompatibilities with loaders and plugins, so we decided to swap Webpack for a leaner custom solution which is now based on RxJS as the application itself. This enabled us to remove more than 500 dependencies (~30% less). ↩︎