Zum Inhalt

Mkdocs

I am working recently even more with mkdocs and explore the many functions it has. I discovered many cool design features in mkdocs-material.

Builtin filters

Here is the list of bultin filters, e.g. mylist | first.

abs, attr, batch, capitalize, center, count, d, default, dictsort, e, escape, filesizeformat, first, float, forceescape, format, groupby, indent, int, join, last, length, list, lower, items, map, min, max, pprint, random, reject, rejectattr, replace, reverse, round, safe, select, selectattr, slice, sort, string, striptags, sum, title, trim, truncate, unique, upper, urlencode, urlize, wordcount, wordwrap, xmlattr, tojson,

How this doc site is made

Following the up-to-date configurations that are used to build this site.

Dockerfile

FROM python:3.9.10-bullseye as python-base

# Setting up proper permissions, running app not as root
RUN mkdir -p /app \
    && groupadd --gid 1000 -r web \
    && useradd -d /app --uid 1000 -r -g web web \
    && chown web:web -R /app \
    && pip install poetry

ARG BUILD_DIR=/app/site

ENV PATH="/app/.local/bin:$PATH"

WORKDIR /app
USER web

COPY ./poetry.lock ./pyproject.toml ./
RUN poetry install

FROM python-base as development

# Expose MkDocs development server port
EXPOSE 8000

COPY --chown=web:web . .

# ARG cannot be used in CMD, but env vars can
CMD ["poetry", "run", "mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]

FROM development as builder

RUN poetry run mkdocs build --strict

FROM nginx:latest as production

COPY --from=builder /app/site /usr/share/nginx/html

To automatically deploy the generated website using a Gitlab CICD, I use the jwilder/nginx-proxy in combination with a docker-compose.yml.

docker-compose.yml

version: '3.8'

services:
  rd_docs:
    image: rd_docs:production
    environment:
      VIRTUAL_HOST: docs.real-digital.ch
      LETSENCRYPT_HOST: docs.real-digital.ch
      LETSENCRYPT_EMAIL: for-letsencrypt@pm.me
    networks:
      - default
      - proxy-tier

networks:
  default:
  proxy-tier:
    external:
      name: proxy-tier

And the CICD configuration using Gitlab with a small helper script:

build.sh

#!/usr/bin/env bash

target=${1:-development}
docker build --tag rd_docs:"$target" --target "$target" .

.gitlab-ci.yml

stages:
  - build
  - deploy

build-job:
  stage: build
  script:
    - ./build.sh production

deploy-job:
  stage: deploy
  script:
    - docker-compose up --force-recreate -d

shutdown-job:
  stage: deploy
  when: manual
  script:
    - docker-compose down


Letztes Update: November 15, 2022
Erstellt: August 7, 2022