Create a site using MKDocs¶

mkdocs is a collection of Python scripts that turn a structured folder containing Markdown documents into a static website.

Setting up mkdocs¶

Running mkdocs locally (on your own computer)¶

Installing mkdocs locally (on your own computer) allows you to quickly preview your generated documentaiton instead of having to wait on GitLab every time you pushed your changes.

• Install Python
• install PIP

Installing mkdocs¶

pip install mkdocs-material
pip install mkdocs-git-revision-date-localized-plugin
or
pip3 install mkdocs-material
pip3 install mkdocs-git-revision-date-localized-plugin

    sudo python -m ensurepip 

sudo nano ~/.bash_profile
PATH="/Users/username/Library/Python/3.8/bin:${PATH}"
export PATH
source ~/.bash_profile

Running mkdocs on (HvA)Gitlab¶

To have Gitlab start the mkdocs site generation from your repository, it needs three files:

gitlab-ci.yml¶

This file starts the process of building your site. You don’t need to alter this file if you’re planning to run from the HvA GitLab server.

mkdocs.yml¶

This file determines the look and structure of the generated site. It should always be adapted to any new project.

requirements.txt¶

This file is used by GitLab to start the site building process. You don’t need to alter the contents of this file.

Style and appearance¶

Your mkdocs generated site can be tailored to your needs and whishes by editing the file mkdocs.yml that resides in the root folder of your repository.

You can find documentation on how to change the appearance here:

• changing the colors
• changing the logos

Plugins¶

mkdocs supports the use of plugins. A comprehensive list of plugins can be found here. Plugins need to be installed before they can be used. Most plugins are available as a python package that can be installed as using pip3. Be sure to include the plugin as a package in your requirements.txt file so your continuous integration runner can also use it.