MkDocs in a docker.

Felling like supporting me in my projects use donate button. Thank You!

Docker Image with MkDocs. It's using tiny image provided by Alpine.
MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

Purpose of this image was to simplify the process of deploying MkDocs. This image is based on Alpine Linux to minimize the size of the image.

ARM based image

To build ARM based image Docker Desktop for macOS can be used.

Example build:

docker build . --file Dockerfile-arm64v8 polinux/mkdocs:arm64v8-1.1.2

Docker compose example

version: '3'

services:
  mkdocs:
    container_name: mkdocs
    image: polinux/mkdocs:1.1.2
    restart: always
    ports:
      - "8000:8000"
    environment:
      LIVE_RELOAD_SUPPORT: 'true'
      ADD_MODULES: 'fontawesome-markdown mkdocs-git-revision-date-localized-plugin mkdocs-material'
      FAST_MODE: 'true'
      DOCS_DIRECTORY: '/mkdocs'
      GIT_REPO: 'git@github.com:username/docs.git'
      UPDATE_INTERVAL: 15
      AUTO_UPDATE: 'true'
    volumes:
      - $HOME/.ssh/id_rsa:/root/.ssh/id_rsa

Environmental Variables

Variable	Notes	Default
`LIVE_RELOAD_SUPPORT`	Support for live reload feature.	`false`
`ADD_MODULES`	List of module to install.	`false`
`FAST_MODE`	Enable fast mode. Rebuilds only changed/added files	`false`
`DOCS_DIRECTORY`	Directory in which documentation is mounted inside of container	`/mkdocs`
`GIT_REPO`	Repository address. Will require ssh key for ssh connection. Example: `-v ${HOME}/.ssh/id_rsa:/root/.ssh/id_rsa`	`false`
`GIT_BRANCH`	Self explanatory	`master`
`AUTO_UPDATE`	Auto update for git repository support	`false`
`UPDATE_INTERVAL`	Update interval in minutes - used only when `AUTO_UPDATE` set to `true`	every `15` minutes
`DEV_ADDR`	Custom IP address and port to serve documentation locall	`0.0.0.0:8000`

Usage

docker run \
    -ti \
    --name mkdocs \
    polinux/mkdocs

Custom config with git repository as source of documentation

docker run \
    -ti \
    --name mkdocs \
    -p 80:9000 \
    -e "ADD_MODULES=mkdocs-bootstrap mkdocs-gitbook mkdocs-bootstrap4" \
    -e "LIVE_RELOAD_SUPPORT=true" \
    -e "FAST_MODE=true" \
    -e "DOCS_DIRECTORY=/my_docs" \
    -e "GIT_REPO=https://my_repos/custom-docs.git" \
    -e "GIT_BRANCH=develop" \
    -e "AUTO_UPDATE=true" \
    -e "UPDATE_INTERVAL=1" \
    -e "DEV_ADDR=0.0.0.0:9000" \
    -v ${HOME}/.ssh/id_rsa:/root/.ssh/id_rsa \
    polinux/mkdocs

See docker-compose.yaml for all compose options examples

Update git repo based deployment

Assuming you are using git repository as source of documentation there are two options available for updating the content of the docs.

Manual

Assuming that container name is mkdocs

docker exec -ti mkdocs bootstrap update
Pulled branch: master
Commit: a4000c525f6db977777bf758987c4df0b44f59b4
Commit Message: Updated nodejs
Date: 2020-03-24 18:52:43
Author: Przemek Ozgo

AUTO_UPDATE

there are two environmental variables that can be used for AUTO UPDATE. See table above ^^

Build

docker build -t polinux/mkdocs .

Docker troubleshooting

Use docker command to see if all required containers are up and running:

docker ps

Check logs of mkdocs server container:

docker logs mkdocs

Sometimes you might just want to review how things are deployed inside a running container, you can do this by executing a bash shell through docker's exec command:

docker exec -ti mkdocs /bin/bash

History of an image and size of layers:

docker history --no-trunc=true polinux/mkdocs | tr -s ' ' | tail -n+2 | awk -F " ago " '{print $2}'

Author

Przemyslaw Ozgo

zar3bski / docker-mkdocs