Serve Generated Sites

After a Python or container build, publish the generated site/ directory. The archive is a portable copy of the same static files.

Preview with Python#

Python's standard HTTP server is useful for local review:

python3 -m http.server \
  --directory /absolute/path/to/private-project-build/site \
  8000

Open http://localhost:8000/manual/. Stop the server with Ctrl-C.

Build the nginx runtime image#

From the Simple Docs repository, build the default runtime:

podman build \
  -t simple-docs-runtime \
  -f Containerfile .

The image contains nginx and the generated public example. It does not contain Python, build.py, or Markdown source.

Serve external output with Podman#

Mount the external generated site over nginx's document root:

podman run --rm \
  --name private-docs \
  -p 8080:8080 \
  -v /absolute/path/to/private-project-build/site:/usr/share/nginx/html:ro,Z \
  simple-docs-runtime

The bind mount hides the example files while the container is running. nginx serves the external generated site without receiving the source Markdown.

Open http://localhost:8080/. nginx redirects the root to /manual/.

The command runs in the foreground. Stop it with Ctrl-C. From another terminal, it can also be stopped by name:

podman stop private-docs

Serve external output with Docker#

docker run --rm \
  --name private-docs \
  -p 8080:8080 \
  -v /absolute/path/to/private-project-build/site:/usr/share/nginx/html:ro \
  simple-docs-runtime

Extract the bundle#

The archive contains a top-level manual-site/ directory:

mkdir -p /absolute/path/to/web-root
tar -xzf /absolute/path/to/private-project-build/manual-site.tar.gz \
  --strip-components=1 \
  -C /absolute/path/to/web-root

Point nginx or another static server at that web root. The server must support directory index.html files for clean URLs.

Open the offline ZIP without a server#

Generate manual-site-offline.zip when a reader needs downloadable documentation that works without nginx, Python, or internet access. Extract the ZIP with the operating system's archive tool, then open:

manual-site-offline/index.html

Do not open the page from inside the ZIP. The extracted files must remain together. Search, navigation, styling, and local images work through file://. External links still require connectivity when followed.

Update the published site#

Regenerate the site after changing Markdown. A bind-mounted nginx container reads the updated files from the host. Restarting nginx is not normally required for static file changes.

If the site is copied into an image instead of bind-mounted, rebuild the image after every documentation change.

Return to the generating sites overview, review Python builds or container builds, or use the Make helpers.