Skip to content

markdown syntax for mkdocs + material⚓

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

Those pages 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
│   ├── 📁 cast/
│   │   └── 📄 my-video.cast
│   └── 📄 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.

Do not reinvent the wheel, copy existing mkdocs website repository. For example, this website repository URL: https://parcours-devops.gitlab-pages.imt-atlantique.fr/

Local mkdocs server⚓

The recommended way to setup a local web mkdocs webserve for debug purpose before pushing on gitlab/github is to use a Python virtualenv. Do not add the virtualenv folder into the git history of your project.

Setup the virtualenv⚓

1
2
python3 -m venv local-mkdocs-server
source local-mkdocs-server/bin/activate

Install the python packages from the requirement.txt file⚓

With the virtualenv activated:

1
python3 -m pip install -r requirements.txt

This command is needed only at first time, or if packages are added to the requirements.txt file

Start local mkdocs webserver⚓

1
mkdocs serve --strict -a 0.0.0.0:8001
  • the --strict option make the build fail if there is a warning. Ensure for example that every internal links are correct.
  • the -a 0.0.0.0:8001 option is used to set the local IP address as the server IP and the port (8001). To run several mkdocs server at the same time, use different ports.

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 ↩