Skip to content

markdown syntax for mkdocs + material⚓

WORK IN PROGRESS

This site is generated from markdown files with mkdocs accompanied by the material theme via the gitlab CI gitlab CI

This page lists the specific syntaxes used for this site and the site https://mee-labs.gitlab-pages.imt-atlantique.fr/

and explains how to generate such a site from https://gitlab.imt-atlantique.fr/

Structure of a git repository for mkdocs + material⚓

📁 My-chaton-site/
├── 📁 docs/
│   ├── 📁 img/
│   │   └── 📄 chaton-1-resized.jpg
│   └── 📄 accueil-chaton.md
├── 📄 mkdocs.yml
├── 📄 requirement.txt
├── 📄 .gitlab-ci.yml
└── 📄 README.md
  • docs: directory in which the content of the site is located, text in markdown format, images, videos etc. It is possible to create subdirectories to better organize the content (img/ in the example above).
  • mkdocs.yml: yaml configuration file of mkdocs
    • Site information (name, repository link, etc.)
    • Organization of the site menu
    • List of plugins and extensions used
    • List of additional CSS and javascript
  • requirement.txt: list of python packages to install to generate the site
  • .gitlab.ci.yml: yaml file of the gitlab CI. This is the list of actions to be performed to generate and deploy a mkdocs site
  • README.md: entry point of the git/gitlab repository documentation.

1
[IMT Atlantique Gitlab](https://gitlab.imt-atlantique.fr/)
will give: IMT Atlantique Gitlab

This is done with the option {:target="_blank"}:

1
[IMT Atlantique Gitlab](https://gitlab.imt-atlantique.fr/){:target="_blank"}
will give: IMT Atlantique Gitlab

A link to a section of the current page (anchor)⚓

Each title generates an anchor link that can be addressed.

1
[voir cette section](#serveur-mkdocs-local)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
will give: [voir cette section](#serveur-mkdocs-local)

The link is the *slug*[^1] of the section title.

### Creating an anchor anywhere

It is possible to create an invisible link that will redirect to its location. Useful for linking to a table or figure

```md
[](){#my-anchor}

Creating the link to this anchor:

1
[Voir figure](#my-anchor)

Test d'une ancre

Creating a link to another page of the site⚓

1
[Simplified git workflow](../git#simplified-workflow-overview)

Git page

And we can even make a link to a particular section, in a new tab:

1
[Simplified git workflow](../git/git.md#simplified-workflow-overview){:target="_blank"}

Simplified git workflow

Managing figures⚓

Simple addition of a figure⚓

1
![Small image of a kitten](../img/markdown/kitten-1-small.jpg)

Small image of a kitten

Note

Here again, we can see that it is a relative path to the image. So it depends on the structure of your project.

Customize figure with CSS⚓

You need a CSS file (for example in docs/assets/extra.css)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
img[src*="#border"] {
    height: auto;
    width: auto;
    border: 1.5px solid #9f9f9f;
    transition: transform ease-in-out 0.3s;
}
img[src*="#shadow"] {
    box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
}
img:active[src*="#zoom"] {
    cursor: zoom-out;
    transform: scale(2.0);
}
img[src*="#zoom"] {
    cursor: zoom-in;
}
img[src*="#center"] {
    display: block;
    margin-left: auto;
    margin-right: auto;
}
img[src*="#no-border"] {
    border: 0px;
    width: 200px;
}

a.md-logo img {
    border: none;
}

Then, you can apply these options on an image with the previously defined css option:

1
![Small centered image of a kitten](../img/markdown/kitten-1-small.jpg#center#shadow)

Small centered image of a kitten

You can see that the image is centered and has shadow.

Adding a figure with HTML⚓

Useful to add image caption

source: https://squidfunk.github.io/mkdocs-material/reference/images/

markdown_extensions: - attr_list - md_in_html - pymdownx.blocks.caption

1
2
3
4
<figure markdown>
  ![Small centered image of a kitten](../img/markdown/kitten-1-small.jpg#center#shadow)
  <figcaption>Fig 1 : My lovely kitten </figcaption>
</figure>

Small centered image of a kitten

Fig 1 : My lovely kitten

Local mkdocs server⚓

1
mkdocs serve
This command will start a local server at http://127.0.0.1:8000.

Sources⚓

  1. A slug is a unique string (typically a normalized version of title or other representative string), often used as part of a URL. The input form will render an error message if the current slug field is not unique https://www.sanity.io/docs/studio/slug-type ↩