GitLab¶

Make mkdocs playing nice with gitlab-ci is pretty easy.

Build a Dockerimage and upload it into gitlabs build in registry
In the documentation project put all markdownfiles in docs directory
Add mkdocs.yml and .gitlab-ci.yml in the documentation project's root directory

Project managing docker container¶

Dockerfile

FROM python:latest

RUN pip install \
  mkdocs \
  mkdocs-material \
  mkdocs-awesome-pages-plugin \
  mkdocs-git-revision-date-localized-plugin \
  mkdocs-git-authors-plugin

CMD ['mkdocs', '--help']

.gitlab-ci.yml

---
image: docker:latest
build:
  script:
    - VERSION=$(docker run --rm python:latest pip search mkdocs | awk '$1 =="mkdocs" {gsub(/\(|\)/, ""); print $2}')
    - docker login -u ${CI_REGISTRY_USER} -p ${CI_JOB_TOKEN} ${CI_REGISTRY}
    - docker build --pull -t ${CI_REGISTRY_IMAGE}:${VERSION} -t ${CI_REGISTRY_IMAGE}:latest .
    - docker push ${CI_REGISTRY_IMAGE}:${VERSION}
    - docker push ${CI_REGISTRY_IMAGE}:latest

Info

In this example the project for the container is called docker/mkdocs

Project hosting documentation¶

directory structure

.
├── docs
│   ├── index.md
│   ├── archlinux
│   │   ├── finish.md
│   │   ├── image.md
│   │   ├── installation.md
│   │   └── partition.md
│   ├── blog
│   │   ├── 2018
│   │   │   └── [...]
│   │   ├── 2019
│   │   │   └── [...]
│   │   └── 2020
│   │       └── [...]
│   ├── links
│   │   ├── foreman.md
│   │   ├── gitlab.md
│   │   ├── grafana.md
│   │   ├── index.md
│   │   ├── mailcow.md
│   │   └── webmail.md
│   └── [...]
├── mkdocs.yml
└── overrides
    ├── landing.html
    └── main.html

.gitlab-ci.yml

---
pages:
  image: ${CI_REGISTRY}/docker/mkdocs:latest
  only:
    - master
  script:
    - mkdocs build -v -d public
  artifacts:
    paths:
      - public

Last update: January 26, 2021