Good documentation portal with GitLab and MkDocs

What if you have Gitlab and want have pretty cool internal documentation portal? We need Gitlab with enabled and configured Gitlab Pages, Gitlab Runner and few packages from MkDocs. You can use any template or extension from MkDocs and use full power of CI/CD.

Here is a directory tree

├── docker-compose.yml
├── docs
│   ├── cat1
│   │   └── index.md
│   ├── cat2
│   │   └── cat2-1
│   │       └── index.md
│   ├── img
│   │   └── .keep
│   └── index.md
├── .gitignore
├── .gitlab-ci.yml
└── mkdocs.yml

mkdocs.yml example

site_name: Documentation portal

nav:
  - "Introduction": index.md
  - "Category 1": cat1/index.md
  - "Category 2":
    - "Category 2-1":
      - "Page 1": cat2/cat2-1/index.md

theme:
  name: 'material'
  palette:
    primary: 'black'
    accent: 'blue'

markdown_extensions:
  - admonition
  - codehilite
  - pymdownx.arithmatex
  - pymdownx.details
  - pymdownx.magiclink
  - pymdownx.superfences
  - pymdownx.emoji
  - toc:
      permalink: true

extra_javascript:
  - 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML'

.gitlab-ci.yml example

image: python:3.5

before_script:
  - pip install mkdocs==1.0
  - pip install mkdocs-material==5.0.0

pages:
  script:
    - mkdocs build
    - mv site public
  artifacts:
    paths:
      - public
  only:
    - master

docker-compose.yml example

version: '3.7'

services:
  app:
    image: squidfunk/mkdocs-material:latest
    networks:
      - default
    volumes:
      - .:/docs
    ports:
      - "8096:8000"

Finally merge to Master and call documentation via https://{root_project}.pages.domain.com/{sub_project}