feat: add diagram examples

.dockerignore

@@ -0,0 +1 @@
+__pycache__/

.gitmodules

@@ -1,3 +1,6 @@
+[submodule "markdown-kroki"]
+	path = docs/submodules/markdown-kroki
+	url = https://github.com/hkato/markdown-kroki
 [submodule "mkdocs"]
 	path = samples/mkdocs/mkdocs
 	url = https://github.com/mkdocs/mkdocs

.pre-commit-config.yaml

@@ -38,11 +38,11 @@ repos:
         - --markdown-linebreak-ext=md
         exclude: ".*\\.patch"
   - repo: https://github.com/gitleaks/gitleaks
-    rev: v8.24.0
+    rev: v8.26.0
     hooks:
       - id: gitleaks
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.6.6
+    rev: 0.7.8
     hooks:
       - id: uv-lock
       - id: uv-export
@@ -58,6 +58,6 @@ repos:
         - --no-hashes
         - --all-extras
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v8.17.3
+    rev: v9.0.1
     hooks:
       - id: cspell

.python-version

@@ -1 +1 @@
-3.9
+3.10

Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.10-alpine
+
+ENV PYTHONUNBUFFERED 1
+
+RUN \
+    apk update \
+    && apk add --update --upgrade --no-cache \
+        cairo-dev fontconfig font-noto g++ gcc gdk-pixbuf-dev libsass make \
+        musl-dev pango-dev podman-compose uv \
+    && fc-cache -f
+
+RUN \
+    addgroup -g 1000 -S mkdocs \
+    && adduser -u 1000 -S mkdocs -G mkdocs
+USER mkdocs
+
+WORKDIR /mkdocs
+COPY --chown=mkdocs:mkdocs pyproject.toml .
+COPY --chown=mkdocs:mkdocs Makefile .
+
+RUN touch README.md && make sync
+
+COPY --chown=mkdocs:mkdocs custom_style_src ./custom_style_src
+COPY --chown=mkdocs:mkdocs docs ./docs
+COPY --chown=mkdocs:mkdocs src ./src
+COPY --chown=mkdocs:mkdocs CHANGELOG .
+COPY --chown=mkdocs:mkdocs LICENSE .
+COPY --chown=mkdocs:mkdocs docker-compose.yml .
+COPY --chown=mkdocs:mkdocs mkdocs.yml .
+
+RUN ls && make docs

Makefile

@@ -33,7 +33,8 @@ sync: setup
 	@echo "########"
 	@echo "# sync #"
 	@echo "########"
-	$(at)uv --directory $(makefile_directory) lock \
+	$(at). $(activate) \
+        && uv --directory $(makefile_directory) lock \
 	    && uv --directory $(makefile_directory) sync --extra all
 	@echo ""
 
@@ -42,7 +43,8 @@ build: sync
 	@echo "#########"
 	@echo "# build #"
 	@echo "#########"
-	$(at)uv --directory $(makefile_directory) lock \
+	$(at). $(activate) \
+        && uv --directory $(makefile_directory) lock \
 		&& uv --directory $(makefile_directory) build
 	@echo ""
 
@@ -59,7 +61,9 @@ docs: sync
 	@echo "########"
 	@echo "# docs #"
 	@echo "########"
-	$(at). $(activate) && cd $(makefile_directory) && mkdocs build
+	$(at). $(activate) \
+        && cd $(makefile_directory) \
+        && mkdocs build
 	@echo ""
 
 .PHONY: samples

docker-compose.yml

@@ -0,0 +1,22 @@
+---
+services:
+  kroki:
+    image: yuzutech/kroki
+    depends_on:
+      - excalidraw
+      - mermaid
+    environment:
+      - KROKI_MERMAID_HOST=mermaid
+      - KROKI_EXCALIDRAW_HOST=excalidraw
+    ports:
+      - "8000:8000"
+    tmpfs:
+      - /tmp:exec
+  mermaid:
+    image: yuzutech/kroki-mermaid
+    expose:
+      - "8002"
+  excalidraw:
+    image: yuzutech/kroki-excalidraw
+    expose:
+      - "8004"

docs/examples/diagrams.md

@@ -0,0 +1,46 @@
+# Diagrams
+
+These diagrams are generated using the public server for
+[`markdown-kroki`](https://github.com/hkato/markdown-kroki).
+
+The minimal `pip` dependencies required to get these diagrams are:
+
+```bash
+pip install markdown-kroki
+```
+
+The minimal `mkdocs` configuration required to get these diagrams to generate is:
+
+```yaml
+markdown_extensions:
+  - markdown_kroki
+```
+
+{!submodules/markdown-kroki/docs/diagrams/actdiag.md!}
+{!submodules/markdown-kroki/docs/diagrams/blockdiag.md!}
+{!submodules/markdown-kroki/docs/diagrams/bytefield.md!}
+{!submodules/markdown-kroki/docs/diagrams/c4plantuml.md!}
+{!submodules/markdown-kroki/docs/diagrams/d2.md!}
+{!submodules/markdown-kroki/docs/diagrams/dbml.md!}
+{!submodules/markdown-kroki/docs/diagrams/ditaa.md!}
+{!submodules/markdown-kroki/docs/diagrams/erd.md!}
+{!submodules/markdown-kroki/docs/diagrams/excalidraw.md!}
+{!submodules/markdown-kroki/docs/diagrams/graphviz.md!}
+{!submodules/markdown-kroki/docs/diagrams/mermaid.md!}
+{!submodules/markdown-kroki/docs/diagrams/nomnoml.md!}
+{!submodules/markdown-kroki/docs/diagrams/nwdiag.md!}
+{!submodules/markdown-kroki/docs/diagrams/packetdiag.md!}
+{!submodules/markdown-kroki/docs/diagrams/pikchr.md!}
+{!submodules/markdown-kroki/docs/diagrams/plantuml.md!}
+{!submodules/markdown-kroki/docs/diagrams/rackdiag.md!}
+{!submodules/markdown-kroki/docs/diagrams/seqdiag.md!}
+{!submodules/markdown-kroki/docs/diagrams/structurizr.md!}
+{!submodules/markdown-kroki/docs/diagrams/svgbob.md!}
+{!submodules/markdown-kroki/docs/diagrams/symbolator.md!}
+{!submodules/markdown-kroki/docs/diagrams/tikz.md!}
+{!submodules/markdown-kroki/docs/diagrams/vegalite.md!}
+{!submodules/markdown-kroki/docs/diagrams/vega.md!}
+{!submodules/markdown-kroki/docs/diagrams/wavedrom.md!}
+{!submodules/markdown-kroki/docs/diagrams/wireviz.md!}
+
+<!--- cspell:ignore actdiag blockdiag bytefield dbml ditaa excalidraw graphviz kroki nomnoml nwdiag packetdiag pikchr rackdiag seqdiag structurizr svgbob symbolator tikz vegalite wavedrom wireviz --->

mkdocs.yml

@@ -5,7 +5,7 @@ site_author: Dominic Walters
 site_dir: site/
 site_name: mkdocs-to-pdf
 site_url: https://mkdocs-to-pdf.readthedocs.io
-copyright: Copyright ©️ 2020, orzih / 2024-2025, Dominic Adam Walters
+copyright: Copyright © 2025 Dom Walters, Hideyuki KATO
 
 extra_css:
   - stylesheets/extra.css
@@ -19,6 +19,13 @@ markdown_extensions:
   - attr_list
   # Footnotes
   - footnotes
+  # Diagrams
+  - markdown_include.include:
+      base_path: docs
+      headingOffset: 1
+  # Diagrams
+  - markdown_kroki:
+      kroki_url: http://localhost:8000
   # Annotations, Grids, Images
   - md_in_html
   # Images
@@ -75,6 +82,7 @@ nav:
       - examples/code-blocks.md
       - examples/content-tabs.md
       - examples/data-tables.md
+      - examples/diagrams.md
       - examples/footnotes.md
       - examples/formatting.md
       - examples/grids.md
@@ -86,13 +94,17 @@ nav:
   - License: LICENSE.md
   - Stuff to Migrate: stuff-to-migrate.md
 
+not_in_nav: |
+    submodules/markdown-kroki/*
+
 plugins:
   - minify:
       minify_html: true
   - search
   - to-pdf:
       cover_title: MkDocs to PDF
       cover_subtitle: An MkDocs plugin to create a PDF
+      enabled_if_env: ENABLE_PDF_EXPORT
 
 theme:
   features:

pyproject.toml

@@ -39,6 +39,8 @@ classifiers = [
 
 [project.optional-dependencies]
 docs = [
+    "markdown-include == 0.8.1",
+    "markdown-kroki == 0.4.0",
     "mkdocs-material == 9.6.7",
     "mkdocs-minify-plugin == 0.8.0",
 ]