Use Make Helpers

On this page

The Makefile provides short commands for common local workflows. Direct Python and Podman commands remain available when troubleshooting or integrating with other tools.

Show available commands#

make help

Run Make from the Simple Docs repository. External documentation can remain in another public or private repository.

Podman Make helpers require GNU realpath with -m support. Make helpers also require SOURCE and BUILD_DIR paths without whitespace. Use the direct Python or Podman commands when a path contains spaces.

Generate the bundled example#

make bundle

This generates:

.build-simple-docs/
├── site/
└── manual-site.tar.gz

Generate an offline ZIP beside those hosted outputs:

make offline-bundle

The additional file is:

.build-simple-docs/manual-site-offline.zip

Extract it and open manual-site-offline/index.html. No server is required.

Preview the example with Python:

make preview PORT=8000

Open http://localhost:8000/en/ and stop the server with Ctrl-C.

Run the example through nginx:

make example PORT=8080

Select the light paper theme for any build or runtime helper:

make bundle THEME=paper
make offline-bundle THEME=paper
make example THEME=paper PORT=8080

Enable Mermaid Rendering#

Set MERMAID=1 to render mermaid fences as static SVG images. It defaults to 0, which keeps the source as escaped, searchable code with no extra tools.

Use the optional container toolchain:

make builder-image MERMAID=1
make bundle-container MERMAID=1
make runtime-image MERMAID=1

The image defaults to simple-docs-builder-mermaid, separate from the standard Python-only simple-docs-builder. bundle-container builds the selected image and generates the hosted site; runtime-image builds nginx with the bundled manual. For a container-generated offline ZIP, use the complete Podman workflow.

With the host Mermaid toolchain installed (Node.js 22.12+, npm-installed mmdc, and a working Puppeteer browser), use:

make bundle MERMAID=1
make offline-bundle MERMAID=1

These host targets do not install the renderer. Even with rendering enabled, mmdc is needed only if the source contains a diagram. See Mermaid authoring for the supported subset.

THEME also supplies diagram colors automatically, for example make bundle-container THEME=paper MERMAID=1. See Mermaid diagram colors for the custom-theme palette contract, neutral fallback, and rebuild requirement.

Generate external documentation with Python#

Override SOURCE with the documentation source directory:

make bundle SOURCE=/absolute/path/to/private-project/docs

SOURCE accepts a flat English source or the parent containing languages.json and all language directories. The container helpers mount that same parent; no additional flags are needed. make check-source checks for a source directory with numbered sections or a manifest file; the generator validates the manifest and content during the build.

The output remains under .build-simple-docs/ in the Simple Docs repository. Override BUILD_DIR to place generated files elsewhere:

make bundle \
  SOURCE=/absolute/path/to/private-project/docs \
  BUILD_DIR=/absolute/path/to/private-project-build

Generate external documentation in a container#

make bundle-container \
  SOURCE=/absolute/path/to/private-project/docs

This builds the reusable builder image, mounts SOURCE read-only, and writes the generated site and bundle under .build-simple-docs/.

Generate and serve the same source through nginx:

make run-container \
  SOURCE=/absolute/path/to/private-project/docs \
  PORT=8080

nginx runs in the foreground. Stop it with Ctrl-C.

Build for a project URL#

Bundle targets accept BASE_PATH:

make bundle-container \
  SOURCE=/absolute/path/to/private-project/docs \
  BASE_PATH=/project-name/

make preview and make run-container require BASE_PATH=/ because their local servers mount the generated site at the domain root.

Override helper settings#

The commonly used variables are:

SOURCE          Documentation source directory
BUILD_DIR       Generated site and bundle parent
BASE_PATH       Deployment URL prefix
THEME           Bundled theme name
PORT            Local server port
PYTHON          Python executable
PODMAN          Podman executable
REALPATH         GNU realpath executable
CHROMIUM        Chromium executable
BUILDER_IMAGE   Builder image name
MERMAID         Render Mermaid fences when set to 1 (default: 0)
MERMAID_BUILDER_IMAGE  Optional image name (default: simple-docs-builder-mermaid)
RUNTIME_IMAGE   nginx runtime image name

Unless overridden, BUILDER_IMAGE follows MERMAID: simple-docs-builder for default builds, or MERMAID_BUILDER_IMAGE when enabled.

Run project checks#

make test
make verify
make test-browser
make test-mermaid

make verify runs the unit tests and generates the hosted bundle. Use make offline-bundle when the downloadable ZIP is also needed. The optional make test-browser target builds temporary hosted and offline fixtures, then uses Chromium to exercise interactive search behavior.

make test-mermaid builds the optional Mermaid image and runs real-renderer integration checks inside it with networking disabled. It is separate from make verify; run it after changing rendering, its toolchain, or diagram examples. Building the image initially needs access to package repositories.

Return to the generating sites overview, or review the direct Python, container, and serving workflows. See create and select themes to add a theme.