Skip to content

pozgo/docker-mkdocs

Repository files navigation

MkDocs in a docker.

Discord
Docker Image MKDocs FOSSA Status

GitHub Open Issues GitHub Stars GitHub Forks

Docker build

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: '[email protected]: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