DANS MkDocs theme"¶
Write optimal documentation in DANS style¶
"Material" is a theme for MkDocs, an excellent static site generator geared towards project documentation. It is built using Google's Material Design guidelines. This theme has been implemented for MkDocs by Martin Donath in such a way that it can be tweaked and rebuilt and redistributed. That is exactly what I have done to create a DANS theme for MkDocs documentation. It can still be tweaked further, but I have made it less customizable, because, after all, it is a specialization for a specific organization.
Most of the documentation has been written by Martin Donath, but I have simplified and adapted his material for the purposes at hand.
See also the authors-notes.
Python 3.4 or higher.
1 2 3 4 5
Basic familiarity with the MkDocs generator of static pages from Markdown.
Your project has a top-level folder named
docs, containing a family of Markdown, HTML, and image files.
At the top-level of your project, next to
docs, there is a file
mkdocs.yml with settings for mkdocs and settings for this theme.
1 2 3
You can use the mkdocs.yml of the documentation you are reading now as an example.
The DANS theme is not available on PyPI. In order to get it and use it, you have to clone its GitHub repo to your own computer:
The place where your cloned repository resides on your own computer is immaterial.
~/github is just an example.
From there, you build the theme as follows:
This will install the theme locally on your computer in the place where Python modules live.
Now, if you want to use this theme in a project, put this in the
mkdocs.yml of that project:
You can tweak the way the theme behaves by means of a few parameters under
theme, e.g. as follows:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
The paths for
favicon are relative to the
development flag produces a layout that reminds the user that your documentation is still
under develoment (if you want to put that differently, use
development_label). In that case, you can point to the production docs by means of
client setting places the logo of the client for which the project is done in the top bar. If the client is DANS, you do not have to pass this setting, because the default values draw in the DANS logo.
If you have a large set of pages, you might want to put the first level of navigation in a horizontal line of tabs. For that, set
disclaimer is true (which is the default), the footer shows a message that the docs have been produced as a product of a specific project, and that the material may be subject to change.
You can suppress that message by
MkDocs includes a development server, so you can review your changes as you go. The development server can be started with the following command:
Now you can point your browser to http://localhost:8000 where the docs will be served. From here on, you can start writing and editing your documentation. Every time you save a documentation file, the docs will be reloaded.
You can also just build the docs without serving them:
And you can deploy the docs to the GitHub pages of the project's repository:
A number of very convenient Markdown extensions are enabled. Navigate to them via Extensions, e.g. Admonition.
For optimal navigation, customize your navigation interface by means of the
nav variable in your
If you have external links, consider abbreviating those links in your
mkdocs.yaml. Two advantages:
- if you use a link multiple times, you can just use the same short abbreviation
- easier to maintain the external links in your docs, should they become broken and in need for updates.
I have made some simplifications, and maybe I have not covered all aspects of the theme. Maybe I have got the DANS styles wrong.
What to expect¶
Responsive design and fluid layout for all kinds of screens and devices, designed to serve your project documentation in a user-friendly way in 37 languages with optimal readability.
Easily customizable favicon and logo; straight forward localization through theme extension; integrated GitHub.
Well-designed search interface accessible through hotkeys (F or S), intelligent grouping of search results, search term highlighting and lazy loading.