README.md

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

Example build:

docker buildx build --platform linux/arm64 --file Dockerfile-arm64v8 -t polinux/mkdocs:arm64v8-1.2.2 .

Docker compose example

version: '3'

services:
  mkdocs:
    container_name: mkdocs
    image: polinux/mkdocs:1.2.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