My setup is a bit unusual since it contains the theme as a Git submodule
instead of installing it via
I chose to do this, because it provides me with more control over the version of the theme.
These notes therefore also include an introduction to using Git submodules.
Git repo and submodule creation
If you want to skip this section, you can clone the resulting repo.
Install Python packages:
pip install mkdocs
Create project folder:
mkdocs new new_page cd new_page
Commit the base:
git add --all && git commit -m "initial commit"
Add theme as a Git submodule:
git submodule add -b master https://github.com/squidfunk/mkdocs-material.git
Commit Git submodule:
git commit -m "feat(material): Add theme as Git submodule"
Add theme to config
Add the following to
theme: name: null custom_dir: mkdocs-material/material # 404 page static_templates: - 404.html # Necessary for search to work properly include_search_page: false search_index_only: true # Default values, taken from mkdocs_theme.yml language: en font: text: Roboto code: Roboto Mono favicon: assets/favicon.png icon: logo: logo
And commit the changes:
git add --all && git commit -m "feat(mkdocs): Use the new theme"
Install theme’s dependencies:
pip install -r mkdocs-material/requirements.txt
Working with Git submodules
This section explains how to interact with the Git repo we just created. This is especially important if it is used by more than one person.
Clone the repo and init as well as populate its submodule with content:
git clone --recurse-submodules https://github.com/makomi/mkdocs-template
Updating the theme
If you’d like to update all submodules to their latest versions:
cd mkdocs-template git submodule update --remote --recursive
However, sometimes you want to update a submodule to its latest release instead of the last commit on its master branch.
For this, lookup the submodule’s latest release tag, e.g.
7.1.9, and check it out:
cd mkdocs-material git pull git checkout 7.1.9 cd ..
Commit the updated submodule:
git add mkdocs-material git commit -m "feat(material): Update theme to release 7.1.9" git push
Another Git user can then update his submodule to the version you committed:
git pull --recurse-submodules
Building and deploying the site
Building the site locally
Deploying locally built site
GitHub: Project pages
Official documentation Build, commit to
gh-pages branch, and push branch to Github:
git checkout master mkdocs gh-deploy
See official documentation on deploying to organization and user pages for details.
mkdocs build scp -r ./site user@host:/path/to/web_server/root
Adapting the template to your needs
GitHub: Set custom domain name
echo -n "example.com" > docs/CNAME
Optimize for offline-viewing
These changes will result in a
site folder that can be viewed in a web browser without the need for any kind of web server:
site_url: "" # instruct MkDocs to build the site so it works with the `file://` scheme use_directory_urls: false # link to index.html files instead of directories plugins:  # disable the search plugin
Good ideas: Using MkDocs for technical reporting (2020-09-15)
“In this post I will explain why MkDocs is well suited for writing technical reports on machine learning models and introduce relevant parts of the MkDocs ecosystem.”
Recommended general-purpose plugins:
“Technical documentation often incurs the usage of a lot of acronyms, which may need additional explanation, especially for new user of your project. For these matters, Material for MkDocs uses a combination of Markdown extensions to enable site-wide glossaries.”
“Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow. Material for MkDocs provides several different types of admonitions and allows for the inclusion and nesting of arbitrary content.”
- Data tables
“MkDocs plugin that adds a page to your site combining all pages, allowing your site visitors to File > Print > Save as PDF the entire site. See demo.”
“MkDocs plugin that enables displaying the date of the last git modification of a page. The plugin uses babel and timeago.js to provide different localized date formats. Initial fork from mkdocs-git-revision-date-plugin.”
“MkDocs Plugin to enumerate the headings (h1-h6) across MkDocs pages.”
- MkDocs Awesome Pages Plugin
“An MkDocs plugin that simplifies configuring page titles and their order.”
- MkDocs PDF Export Plugin
“An MkDocs plugin to export content pages as PDF files.”
“An MkDocs plugin to minify HTML and/or JS files prior to being written to disk.
HTML minification is done using htmlmin.
JS minification is done using jsmin.”
“Material for MkDocs provides dedicated styles for primary and secondary buttons that can be added to any
buttonelement. This is especially useful for documents or landing pages with dedicated call-to-actions.”
- Content tabs
“Sometimes, it’s desirable to group alternative content under different tabs, e.g. when describing how to access an API from different languages or environments. Material for MkDocs allows for beautiful and functional tabs, grouping code blocks and other content.”
“Material for MkDocs provides support for several HTML elements that can be used to highlight sections of a document or apply specific formatting. Additionally, Critic Markup is supported, adding the ability to display suggested changes for a document.”
“While images are first-class citizens of Markdown and part of the core syntax, it can be difficult to work with them. Material for MkDocs makes working with images more comfortable by providing styles for alignment and image captions.”
“Diagrams help to communicate complex relationships and interconnections between different technical components, and are a great addition to project documentation. Material for MkDocs integrates with Mermaid.js, a very popular and flexible solution for drawing diagrams.”
“Footnotes are a great way to add references to supplemental or additional information for a specific section of a document without interrupting the document flow. Material for MkDocs provides the ability to insert inline footnotes and render them at the bottom of the page.”
“Material for MkDocs supports several flavors of lists that cater to different use cases, including unordered lists and ordered lists, which are supported through standard Markdown, as well as definition lists and task lists, which are supported through extensions.”
- Meta tags
metatags allow to provide additional metadata for a document, e.g. page titles and descriptions, additional assets to be loaded, and Open Graph data. While arbitrary metadata can always be added via customization, some common meta tags can be configured.”
- Icons + Emojis
“One of the best features of Material for MkDocs is the possibility to use more than 8.000 icons and thousands of emojis in your project documentation with practically zero additional effort. Furthermore, custom icons can be added and used in
mkdocs.yml, documents and templates.”
“Macros and variables are powerful tools to parametrize Markdown files, as they allow to perform Jinja templating directly from Markdown. This is especially useful to include technical data from other files and add central variables via
Upgrading Material (theme)
See the official upgrade page for summary of what changed between major releases.