MkDocs

#ssg   #mkdocs   #wip  

---

Table of Content

[[MkDocs]]

https://www.mkdocs.org/

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. Start by reading the introductory tutorial, then check the User Guide for more information.

mkdocs installation

https://squidfunk.github.io/mkdocs-material/

The step described here is really to install mkdocs-material theme which also installs mkdocs as dependency.

# assuming venv is active
pip install -U pip setuptools mkdocs-material mkdocs-awesome-pages-plugin mkdocs-git-revision-date-plugin

# pip freeze output as of 20240201 using [email protected] saved as requirements.txt, so optionally run 
# pip install -r requirements.txt
# to install

usage

Prepare docs/ directory and markdown files inside, and mkdocs.yml file.

Run mkdocs serve to serve locally as demo, and mkdocs build to generate the whole site contents in public/ directory.

mkdocs.yml configuration file

code block

https://squidfunk.github.io/mkdocs-material/reference/code-blocks/

[[WIP]] add examples on syntax, title, line numbering, and line highlighting.

mermaid diagram

[[WIP]]

tags

https://squidfunk.github.io/mkdocs-material/plugins/tags/

[[WIP]]

manual deploy

See [Cloudflare Pages].

deploy using gitlab cicd

See [[GitLab CI/CD]].

Here is my .gitlab-ci.yml file as of Feb 2024.

# GitLab CI/CD pipeline to 
# 1. build a mkdocs site
# 2. upload the product to Cloudflare Pages

stages:
- build
- deploy

build-mkdocs:
  image: $HARBOR_HOST/cache-dockerhub/library/python:3.11.7
  # image: $HARBOR_HOST/$HARBOR_PROJECT/mkdocs:0.9
  stage: build
  variables:
    PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
  cache:
    key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG"
    paths:
      - "$PIP_CACHE_DIR"
  before_script:
    - echo "Build a site using MkDocs Material"
    # - cd "$PIP_CACHE_DIR" && find . -not -path "*/\.git/*" | sed -e "s/[^-][^\/]*\// |/g" -e "s/|\([^ ]\)/|-\1/"
    # - cd "$CI_PROJECT_DIR"
    - mkdocs --version || pip install -r requirements.txt
  script:
    - mkdocs build --site-dir public --verbose --strict
  after_script:
    # - cd "$PIP_CACHE_DIR" && find . -not -path "*/\.git/*" | sed -e "s/[^-][^\/]*\// |/g" -e "s/|\([^ ]\)/|-\1/"
    - cd "$CI_PROJECT_DIR/public" && find . | sed -e "s/[^-][^\/]*\// |/g" -e "s/|\([^ ]\)/|-\1/"
  artifacts:
    paths:
      - "public/"

deploy-cloudflare-pages:
  image: $HARBOR_HOST/cache-dockerhub/library/node:21.6.1
  stage: deploy 
  variables:
    CLOUDFLARE_API_TOKEN: $CLOUDFLARE_API_TOKEN
    CLOUDFLARE_ACCOUNT_ID: $CLOUDFLARE_ACCOUNT_ID
  dependencies:
    - build-mkdocs
  cache:
    key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG"
    paths:
      - .npm/
  before_script:
    - echo "Deploy MkDocs site to Cloudflare Pages"
    # - echo "commit hash to be used in the arg is ${CI_COMMIT_SHORT_SHA}"
    - npm ci --cache .npm --prefer-offline
    # - find . -not -path "*/\.git/*" | sed -e "s/[^-][^\/]*\// |/g" -e "s/|\([^ ]\)/|-\1/"
  script:
    - npx wrangler pages deploy public --project-name beryl --branch main --commit-hash "${CI_COMMIT_SHORT_SHA}" 
  after_script:
    - npx wrangler pages deployment list --project-name beryl
    # - find . -not -path "*/\.git/*" | sed -e "s/[^-][^\/]*\// |/g" -e "s/|\([^ ]\)/|-\1/"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH