Rendering Modes

Static by default, published when you need a web server.

printing press is static-first, but static-first does not mean local-only.

Documentation needs to work when opened from disk, shared as an archive, committed to a repository, attached to a release, or served by a static host. It also needs to stay backend-free in all of those places. Always.

The tricky part is that browsers treat file:// and http(s):// differently. Local files, static web servers, and local previews all need the same documentation experience, but they cannot always use the same hydration strategy.

printing press handles that with two output layouts and one local preview mode:

  • static is the default layout, built for local files and offline distribution
  • published is the hosted layout, built for static web servers
  • serve is a local preview of the published layout

Default mode

Default mode is for portable docs that can be opened directly from disk:

ppress ./openapi.yaml

This writes ./api-docs unless we pass --output. Open api-docs/index.html directly, or run:

open api-docs/index.html

The docs should keep working offline because this mode uses portable data hydration instead of relying on a web server.

Default mode is the right choice when we want to:

  • open index.html directly from disk
  • zip the docs
  • attach generated docs to a release
  • commit generated docs to a repository
  • share docs as a folder of files

Published mode

If the intention is to serve the HTML documentation up from a webserver or some kind of static host, this should be the choice.

Use --publish when the generated docs will be served by a static host:

ppress --publish --output ./api-docs ./openapi.yaml

The output is still static and backend-free, but the generated paths and data hydration are tuned for being served over HTTP.

Published mode is the right choice for:

  • GitHub Pages
  • S3
  • Netlify
  • Cloudflare Pages
  • static CDN hosting
  • any web server that serves files from the output directory

Serve mode

Use --serve to preview the published version locally before pushing it to a chosen host.

ppress --serve --output ./api-docs ./openapi.yaml Serve mode renders the docs in published mode and starts the built-in web server, letting us explore the result exactly as it will behave when served over HTTP.

--serve is a local development preview. Use --publish for static hosting instead of treating the preview server as a production server.

Then open the docs:

open http://127.0.0.1:9090

Change the port with --port:

ppress --serve --port 8080 --output ./api-docs ./openapi.yaml

Export controls

When using serve mode, a built-in UI control will be rendered that allows exporting the docs to an archive format.

To disable them when we want the preview without the export panel or local export API endpoints:

ppress --serve --disable-export --output ./api-docs ./openapi.yaml

Base URL and base path

Use --base-url when generated links need a public URL prefix:

ppress --publish --base-url https://docs.example.com/apis/train --output ./api-docs ./openapi.yaml

Use --base-path when a remote or local spec needs a base path for resolving local references:

ppress --base-path ./specs ./specs/openapi.yaml

--base-url changes generated documentation URLs. --base-path changes how local file references are resolved.