The basic install only requires mkdocs
and mkdocs_materials
to be installed. This can be done system-wide using the system python installation (and associated pip
command).
pip install mkdocs mkdocs_material mkdocs-with-pdf
To check where pip
is located, use which pip
in linux/unix system.
If you are a conda/anaconda user, you can also create a new environment from the provided environment.yml
file
Basic text
Sections, subsections: #
, ##
etc.
Bold: **Text**
Italic: _Text_
Image
<figure markdown id='figureXX'>
![alt-text](relative/path/to/figure.png)
<figcaption>A good figure caption</figcaption>
</figure>
To reference this figure in the text, create a link [Figure XX](path/to/page.md#figureXX)
. If the figure is referenced in the same page, the path/to/page.md
can be omitted.
Table
| header 1| header 2|
|---------|---------|
| item 1 | item 2|
will produce -
header 1 | header 2 |
---|---|
item 1 | item 2 |
Add a span
before for a referencable caption
<span id="table01">Table caption</span>
and refer using link notation Table [1](#table01)
.
Equations
Equations can be added using standard latex \begin{equation}\label{eqxx}\end{equation}
block, or inline with $...$
block. Other latex command works inside these blocks. The equation inside equation
block with label eqxx
can be referred inline using $\ref{eqxx}$
.
References
References can be added as link. For example [Zhang et al. 2016](#zhang2016)
. An entry for this reference cab be added with html <span>
in the end of each page as <span id="zhang2016">Zhang, Y., Stanev, E.V. and S. Grashorn (2016) Unstructured-grid model for the North Sea and Baltic Sea: validation against observations, Ocean Modelling, 97, 91-108.</span>
. Here id
is what makes the link works.
mkdocs serve # to see locally
mkdocs build # build site
mkdocs gh-deploy --force # serve site to github on gh-page branch
You will need github pages fully setup. See Github Pages for more information.