Skip to content

MkDocs

MkDocs is a fast, simple static site generator.

Documentation source files are written in Markdown,
and configured with a single YAML configuration file.

Installation & Build

Installation

I use a built docker images to serve the docs.
The container is accessible through a traefik proxy

Dockerfile 
  FROM python:latest

  LABEL author="enoks" \
        description="Publishing My Notes" \
        date="2021" \
        version="1.0.0"

  EXPOSE 8000
  WORKDIR /mkdocs
  RUN pip install --upgrade pip && \
      pip install mkdocs markdown-include mkdocs-material pymdown-extensions mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin

  # mkdocs-material to use material theme
docker-compose.yml 
      version: '3.3'

      networks:
        zabra:
          external: true

      services:
        mkdocs:
          build:
            context: .
            dockerfile: ./build/Dockerfile
          image: enoks/mkdocs
          container_name: mkdocs
          restart: always
          logging:
            driver: json-file
            options:
              max-size: 10m
              max-file: '3'
          expose:
            - 8000
          networks:
            - zabra
          entrypoint: mkdocs serve -a 0.0.0.0:8000
          labels:
            # Enable proxy through traefik and https
            - "traefik.enable=true"
            - "traefik.http.routers.mkdocs.rule=Host(`doc.enoks.fr`)"
            - "traefik.http.routers.mkdocs.entrypoints=websecure"
            - "traefik.http.routers.mkdocs.tls=true"
            - "traefik.http.routers.mkdocs.tls.certresolver=letsencrypt"
            # Enforce HSTS (HTTP Strict Transport Security) & STS Headers for Trafeik UI.
            - "traefik.http.middlewares.servicests.headers.stsseconds=31536000"
            - "traefik.http.middlewares.servicests.headers.stspreload=true"
            - "traefik.http.middlewares.servicests.headers.stsincludesubdomains=true"
            - "traefik.http.middlewares.servicests.headers.isdevelopment=false"
            - "traefik.http.routers.mkdocs.middlewares=servicests"
            # TLS hardening is defined in Traefik side.
          volumes:
            - ./mkdocs:/mkdocs
Repo Tree 
  ├── docker-compose.yml #to deploy
  ├── build
  │             ├── Dockerfile #to build image
  │             ├── .dockerignore
  ├── mkdocs # folder wich contains a mkdocs files tree mounted on container
  │             ├── docs
  │             │             ├── elk
  │             │             │             └── elk.md
  │             │             ├── extra.css
  │             │             ├── img
  │             │             │             └── ZabraHost.png
  │             │             ├── index.md
  │             │             └── mkdocs.md
  │             ├── example1_mkdocs.yml
  │             ├── example2_mkdocs.yml
  │             └── mkdocs.yml # (.gitignore)  based on example2_mkdocs.yml, nav is built dynamically on server...
  └── README.md

Writing Documentation

Files and directories with names which begin with a dot are ignored (for example: .toto.txt)

Files Tree 
    mkdocs.yml
    docs/
        index.md # required
        about.md
        cloud/   # sub-folder
        aws.md
mkdocs.yml 
  #(example1_mkdocs.yml)
  site_name: ENOKS DOCS
  site_url: 'https://doc.enoks.fr'
  site_author: ZABRA || ENOKS
  site_description: >-
  doc.enoks.fr is a collection of notes about different technos and stuffs
  like docker, ansible, kubernetes, traefik, netxcloud, elk, devops, sre

  theme:
    name: material
    favicon: img/favicon.ico
    #logo: img/favicon.ico
    features:
        - content.tabs.link
        - navigation.top
        - header.autohid

    palette:
      - scheme: default
        primary: deep purple
        accent: red
        toggle:
          icon: material/toggle-switch-off-outline
          name: Switch to dark mode
      - scheme: slate
        primary: brown
        accent: amber
        toggle:
          icon: material/toggle-switch
          name: Switch to light mode

  copyright: Copyright © 2021 - Enoks

  extra_css:
    -  stylesheets/extra.css

  extra:
    social:
      - icon: fontawesome/solid/paper-plane
        link: mailto:toto@example.com
    analytics:
      provider: google
      property: G-1DJD59F34T

  plugins:
    - search
    - minify:
        minify_html: true
    - git-revision-date-localized:
        timezone: Europe/Paris
        enable_creation_date: true
  # https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/options/
  markdown_extensions:
    - admonition
    - nl2br
    - meta
    - attr_list
    - pymdownx.details
    - pymdownx.tasklist
    - pymdownx.emoji
    - pymdownx.saneheaders
    - pymdownx.tabbed:
        alternate_style: true
    # Highlight code blocks
    - pymdownx.highlight:
        anchor_linenums: true
        line_spans: __span
        pygments_lang_class: true
    - pymdownx.inlinehilite
    - pymdownx.snippets
    - pymdownx.superfences
    # code blocks
    - markdown_include.include:
        base_path: docs

For this site i use nav option because i don't like the auto-generated nav order
I use a little script to list and sort files and then generated a nav

Extensions

  • Extensions referenced in Mkdocs site: https://squidfunk.github.io/mkdocs-material/reference/
  • Third party: https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions

Examples of extensions:

  • pymdown : a collection of beautiful extensions
  • admonition: adds rST-style admonitions to Markdown documents
  • nl2br : will cause newlines to be treated as hard breaks; To avoid used <br> each time
  • meta : to add some meta in markdow file.
  • markdown_include.include: to include a file into a markdown file.

Material Theme

https://squidfunk.github.io/mkdocs-material/

Switched from readthedocs to material
Dockerfile updating by adding mkdocs-material in pip install

Possible to just use the image: squidfunk/mkdocs-material