MkDocs¶
Perhaps unsurprisingly, a package built around making documentation has excellent documentation. A user guide for MkDocs has some introductory material for making content, but the Material of MkDocs documentation is the best reference, with more detail and examples of the features unique to the theme.
Configuration¶
The mkdocs.yaml file is where the magic happens. The .yaml format (commonly .yml) is a human readable language commonly used for configuration files, and stands for "YAML Ain't Markup Language". Basically, one loads in the desired libraries and extensions for the site, in addition to specifying the site structure by pointing to markdown files which actually contain the content for each page. Best practice would dictate that one only load the content strictly necessary to make the site run, but I have adopted a master .yaml approach, which can be accessed here.
Text¶
Admonitions¶
A much better discussion of admonitions can be found elsewhere but useful common use cases are shown below:
!!! quote
... there's something in science like the shine of the Patronus Charm, driving back all sorts of darkness and madness ...
<p align=right> Eliezer Eudkowsky (Less Wrong), Harry Potter and the methods of rationality
Quote
... there's something in science like the shine of the Patronus Charm, driving back all sorts of darkness and madness ...
Eliezer Eudkowsky (Less Wrong), Harry Potter and the methods of rationality
Icons¶
[:fontawesome-brands-python:](https://jove2021.cloud.edu.au/){ .md-button .md-button--primary class="text-center" style="margin-left: 45%; font-size:60px"}
Elements¶
Tables¶
| Method | Description |
| :---------: | :----------------------------------: |
| Line 1 | :material-check: This |
| Line 2 | :material-check-all: is a |
| Line 3 | :material-close: test |
Tabs¶
Code¶
Information on code blocks can be found in the Material for MkDocs documentation
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
Annotations¶
.yaml configuration
Annotation to code requires the content.code.annotate feature to be enabled in the theme configuration of mkdocs.yaml:
Images¶
Material for MkDocs documentation
Information on inserting images can be found in the Material for MkDocs documentation
Placing images in markdown (well, HTML) is not a simple as it should be. In the simples form, one uses markdown of the form:
for example, the code  places the image malamute.jpg:
It is unlikely that one will place images without some configuration; the image above is left justified and rather small. Below, methods for simple image manipulation are outlined.
.yaml configuration
Most image manipulation is performed using the attribute lists extension which should be enabled in the mkdocs.yaml:
Sizing¶
Sizing is most easily achieved (with consistent outcomes) using the width attribute. Using this, one can specify the width of the image (in pixels) or as a percentage of the page width. No width designation will place the image at full size or the page width, whichever is smaller. To alter the width attribute, one should use place the width parameter inside curly brackets {}, for example:
Shown below are the same image placed with a range of width parameters:
The markdown used to produce the above image is {width="300"}
The markdown used to produce the above image is {width=50%}
The markdown used to produce the above image is 
Alignment¶
If you have spent any time with HTML, you will appreciate that alignment is non-trivial. So whilst the align attribute is now depreciated, it is still supported by all browsers, and that is unlikely to change. It also provides a relatively easy way to perform alignment. As with the width attribute, one should place the alignment flag inside curly brackets {}, for example:
Shown below are the same image placed with different alignment flags:
Text written below the markdown to place the image will be wrapped on the right of the image.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Text written below the markdown to place the image will be wrapped on the left of the image.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Centring¶
Most likely, one will want to centre images, which can be achieved not with an alignment flag, but rather a workaround of the form {: .center}. For example, the markdown {width="600" : .center} gives the placement:
Captions¶
In order to have a caption for an image, it is necessary to use HTML directly:
Object attributes can be specified, but unlike image placement with markdown, the image will be placed centrally by default. For example, the HTML
<figure markdown>
{ width="300" }
<figcaption>This is both a malamute and a good boi</figcaption>
</figure>
yields