Skip to content

How to set up your own documentation page using mkdocs

What is Mkdocs and why use it?

Mkdocs generates HTML from Markdown making an easy documentation page. So you don't have to struggle with html and css so you can focus on things more important.

How to set it up

For this project im going to use Gitlab CI pipelines. CI stands for continuous integration. That means that with every push you can make something do. For example clean up code or generate a documentation page based on what you've written in markdown.

Step 1 choosing a theme

In this github repo there is a catalog of themes that you can choose. I went with the Ivory theme. (note this changed to material theme but the steps are still the same. link)

Step 2 preparing the envoirment

You wanna create a couple of files. These all need to be in the root of your project. * mkdocs.yml The configuration file for mkdocs * requirements.txt The list of dependencies for the python package manager to install * .gitlab-ci.yml The script that builds and deploys you page

mkdocs.yml

Lets start with mkdocs.yml. In this file is described how to page should look and be named. This is the base of a mkdocs file: 

site_name: My Docs by GitLab Pages
site_url: https://pages.gitlab.io/mkdocs
site_dir: public
theme: ivory
In here you can describe the site name and add the theme.

requirements.txt

requirements.txt tell the python package manager (pip) what dependencies you want installed. For this project we need mkdocs and the theme you want installed. This is my requirements file 

mkdocs>=1.5.3
mkdocs-ivory>=0.4.6
To find the version number of the theme you want you need to open the package website and there you can find what the latest version it's on. You don't have to add the version numbers but I do it because if the package maintainer sends out a broken update the package still works.

gitlab-ci.yml

gitlab-ci.yml tells gitlab what to do when a commit is send out. For example this yml file builds a page and publishes it. 

image: python:latest

before_script:
  - time apt update
  - time pip install -r requirements.txt

pages:
  stage: deploy
  script:
    - time mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - "docs/**/*"
        - "mkdocs.yml"

What does everything do?

Variables Description
image Defines what OS should be used to for the scripts
before_script Commands to run before you run the script or build something
pages When this variable is mentioned gitlab knows it a pages job
stage Defines what stage the build process is in. This can be used to run jobs in parallel. for example: all early stage jobs at the same time and all main stage jobs at the same time.
artifacts Jobs can leave files. This tells them to save them
path This tells which files or folders to store as the artifacts
rules This tells when to run the pipeline
if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH If the branch committed to is set to the default branch in gitlab. Then run the pipeline
changes tell the pipeline to only update when certain files or folders are changed

Sources

  • https://gitlab.com/pages/mkdocs
  • https://docs.gitlab.com/ee/ci/variables/index.html
  • https://docs.gitlab.com/ee/user/project/pages/