Goal
- Mechanism to automatic generation static documentation in HTML from markdown documents.
- Markdown language is selected to generate low entry level to write documentation also supporting plantuml syntax.
- Markdown files contains images, plantuml diagrams, code snippets, tables, etc. following preparation of functional document
Technical solution
- Pandoc > 5.18
- PlantUML
- pandoc-plantuml-filter
- bash script executed in Debian-OS
- Everything inside docker container
What I did
#. Setup Docker environment
- Install Docker Desktop
- Create Dockerfile
FROM ubuntu:22.04
RUN apt-get update
RUN apt-get install pip -y
RUN apt-get install plantuml -y
RUN apt-get install wget -y
RUN wget https://github.com/jgm/pandoc/releases/download/2.19.2/pandoc-2.19.2-1-amd64.deb
# https://www.pandoc.org/installing.html#linux
RUN dpkg -i pandoc-2.19.2-1-amd64.deb
RUN rm pandoc-2.19.2-1-amd64.deb
RUN pip install pandoc-plantuml-filter- Build docker image with
#!/bin/sh
# Execute command test.sh
docker build -t blog-processor-ubuntu .
docker scan --json blog-processor-ubuntu- Execute command to container mounting sources:
# powershell command
docker run -it --rm -a stdin -a stderr -a stdout --name blog-processor-cntr-wip --mount type=bind,src="/path/to/src/folder",dst=/mnt/src -e PWD=/mnt/src/ --entrypoint /mnt/src/generate_pages.sh blog-processor-ubuntu
#!/bin/sh
find ${PWD}/WebPage -iname "*.md" -type f -exec sh -c 'pandoc --defaults ${PWD}/generate_pages.yaml -o "${0%.md}.html" "${0}" && echo "Generated: ${0%.md}.html" && mv "${0%.md}.html" ${PWD}/output' {} \;