Skip to content

Advanced customization options¤

Material for nbdev uses mkdocs.yml configuration file for generating documentation. This file is located in mkdocs/mkdocs.yml and is pre-configured with reasonable default settings. You can easily customize the documentation by modifying the mkdocs.yml file, such as changing the theme, adding new markdown extensions, and adjusting other settings.

Editing pre-configured CSS file¤

In addition to changing the settings, you can make minor changes to the documentation by writing your own CSS and JavaScript.The easiest way is by editing the pre-configured CSS and JavaScript files inside mkdocs/docs_overrides directory:

.
└── mkdocs/
    └── docs_overrides/
        ├── css/
        │   └── extra.css
        ├── js/
        │   └── extra.js
        └── images/
            └── compass-outline.png

Note

The docs_overrides directory will be created only once when you run the nbdev_mkdocs new command; please ensure that you add this folder to git to preserve your changes.

Changing the favicon¤

You can easily change the default favicon by adding the new image to the mkdocs/docs_overrides/images directory and referencing it in the mkdocs.yml file.

In mkdocs.yml, replace the default image name compass-outline.png with the new favicon image name:

favicon: images/{new_fav_icon_name}

Adding a new CSS file¤

If you want to change the colours or spacing of certain elements, edit the extra.css file in the mkdocs/docs_overrides/css directory. The file is already configured in the mkdocs.yml file, and after making the changes, save the file, stop the server and re-run the nbdev_mkdocs preview command to preview your changes in the browser.

Adding a new JavaScript file¤

If you want to integrate another syntax highlighter or add some custom logic to your theme, edit the extra.js file in the mkdocs/docs_overrides/js directory. The file is already configured in the mkdocs.yml file, and after making the changes, save the file, stop the server and re-run the nbdev_mkdocs preview command to preview your changes in the browser.

Please refer to the Material for Mkdocs documentation for more customization options.

Using Mathematical formulas¤

MathJax is being already set up as described here.

Using the block syntax¤

Blocks must be enclosed in $$...$$ or \[...\] on separate lines:

$$
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
$$
\[ \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} \]

Using the inline block syntax¤

Inline blocks must be enclosed in $...$ or \(...\):

The homomorphism $f$ is injective if and only if its kernel is only the 
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such 
that $f(a)=f(b)$.

The homomorphism \(f\) is injective if and only if its kernel is only the singleton set \(e_G\), because otherwise \(\exists a,b\in G\) with \(a\neq b\) such that \(f(a)=f(b)\).