4.4 KiB
How to set up your own documentation page using mkdocs
What is Mkdocs
Mkdocs generate html from markdown making an easy documentation page.
How to set it up
For this project im going to use Gitlab CI pipelines. CI stands for continuous intergration. 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 if themes that you can choose. I went with the Ivory theme.
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 mkdocsrequirements.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 what dependencies you want installed. For this project we need mkdocs and the theme you want to install. This is my requirements file
mkdocs>=1.5.3
mkdocs-ivory>=0.4.6
You see that I install mkdocs and the theme To find the version number of the theme you need to open the package website and there you can see what version number its on.
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?
pages | 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 pipline |
if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH | If the branch commited to is set to the default branch in gitlab. Then run the pipline |
changes | tell the pipline to only update when certain files or folders are changed |