Skip to content

MkDocs

Introduction

What is MkDocs? Funny you asked.
You are looking at it right now.
With MkDocs you can start documentation site and/or a blog.
This site is using the material design for MkDocs, but there are other choices available.

Deploying MkDocs

I spun up the the LXC container with Ubuntu 22.04 LTS and installed Docker and Docker Compose.

  1. After updating and upgrading the packages I created a MkDocs folder.
  2. I created a new docker-compose.yml file with the configuration below:
    MkDocs Config
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
    services:
  mkdocs:
    image: squidfunk/mkdocs-material
    ports:
      - "8005:8000"
    volumes:
      - ./:/docs
    stdin_open: true
    tty: true
    restart: unless-stopped
  3. After that I created the site structure like below. 
    - mkdocs.yml (this files will be filled in step 4)
- docs
    - assets
        - images
            *.png
            *.jpg
  index.md
  *.md (site pages)
- docker-compose.yml (created in step 2)

  4. Configuration for your website.

    Website Config
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
    site_name: name-your-website

nav: # Your website navigation
  - Home: index.md
  - Docker containers: # Category this cannot connected to a md file
    - MkDocs: mkdocs.md # Add the page under the category and link the md file

theme:
   name: 'material'
   favicon: assets/images/*.png # This needs to be located at assets/images
   logo: assets/images/*.png # This needs to be located at assets/images
   features: # In this section you can add/enable features
    - content.code.copy
   palette:
    # Palette toggle for automatic mode     
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: grey
      accent: blue
      toggle:
        icon: material/weather-night
        name: Switch to dark mode

    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: blue grey
      accent: cyan
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode

markdown_extensions: # Configure the markdown extension.
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
    More information about creating the configuration file.
    Creating
    Customization
    Theming
    Markdown extension
    Extension list

  5. After configuring your initial website you can start your Docker container (docker compose up -d)

Rescources