Skip to content

Latest commit

 

History

History
 
 

docs

Documenting on mkdocs

Installation (optional; for local development)

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

Writing markdown document

Basic text

Sections, subsections: #, ## etc.

Bold: **Text** $\rightarrow$ Text

Italic: _Text_ $\rightarrow$ 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.

Build and deploy site

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.