Customization¶
A great starting point¶
Project documentation is as diverse as the projects themselves and the DANS theme is a good starting point for making it look great. However, as you write your documentation, you may reach a point where some small adjustments are necessary to preserve the desired style.
Adding assets¶
MkDocs provides several ways to interfere with themes. In order to make a few tweaks to an existing theme, you can just add your stylesheets and JavaScript files to the docs directory.
Additional stylesheets¶
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 your docs directory:
1 2 | |
Then, add the following line to your mkdocs.yml:
1 2 | |
Spin up the development server with mkdocs serve and start typing your changes in your additional stylesheet file – you can see them instantly after saving, as the MkDocs development server implements live reloading.
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 your docs directory:
1 2 | |
Then, add the following line to your mkdocs.yml:
1 2 | |
Further assistance can be found in the MkDocs documentation.
Theme development¶
The Material theme, on which the DANS theme is based, uses Webpack as a build tool to leverage modern web technologies like Babel and SASS. If you want to make more fundamental changes, it may be necessary to make the adjustments directly in the source of the Material theme and recompile it. This is fairly easy.
In fact, this is exactly the way how the DANS theme has been derived from the Material theme.
If you want to go this road, make a new clone of the original mkdocs-material repository, consult the docs over there, and go ahead.