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}

Comments

Popular posts from this blog