This repository tracks Presidium's user documentation and provides a sample of how presidium is used.

Presidium is a software documentation management system for agile teams and their users made from the stuff software engineers love. Presidium uses familiar tools already in use by many software development teams to easily compose and publish and manage quality documentation.

Presidium integrates Hugo as a Go library to provide static site generation capabilities compatible with our Presidium Themes.

Read Presidium's documentation for details on all features and for help on setting up a new project using the sample template.

For detailed instructions on getting started, please see Getting Started.

All upcoming features and issues are tracked here.

Presidium integrates Hugo as a Go library, ensuring that the user is building their docs with a Hugo version that is compatible with our Presidium Themes.

Common Hugo CLI commands are available directly as Presidium commands (e.g., presidium server), and all Hugo commands are available through presidium hugo.

Presidium themes are embedded in the binary as a compressed zip archive to ensure offline functionality and avoid Go module embedding restrictions:

1. Themes are Git Submodules: The three Presidium themes (styling-base, layouts-base, layouts-blog) are tracked as git submodules for easy updates
2. Build-time Compression: During make build, themes are zipped into themes.zip and embedded into the binary using Go's //go:embed directive
3. Runtime Extraction: When presidium runs, the zip is extracted to a temporary directory and Hugo is configured to use the local themes via HUGO_MODULE_REPLACEMENTS
4. No Network Required: Once built, the presidium binary requires no network access to use the embedded themes
5. Fast Extraction: Zip extraction is typically 10-50ms, adding negligible overhead

Go's //go:embed directive cannot embed directories that contain go.mod files (other Go modules). The themes are separate Go modules with their own go.mod files, so we:

• Package them as a zip at build time
• Embed the single zip file (no module restrictions)
• Extract at runtime (fast and simple)

Initialize the theme submodules before building or running tests:

git submodule update --init --recursive

Run the build command:

make build

Move the binary into a valid documentation site directory, then run the hugo build cmd:

./presidium hugo 

Or if you want to serve the site after the hugo build, then run:

./presidium hugo server

Or use the server command with the built-in proxy middleware:

./presidium server

The presidium server command runs Hugo's development server behind a proxy layer that provides Caddy-style URL rewriting middleware. This enables advanced features like format conversion and section navigation without requiring an external reverse proxy.

The proxy automatically handles:

1. Article Navigation (?article=<id>): Passes through unchanged; the proxy injects a small client-side script that scrolls to the element with that id while leaving ?article= visible in the URL
2. Section Navigation (?section=<section>): Locates the section slug in the path, masks the path to up-to-and-including the slug, and promotes any remaining segments to ?article=<remainder> so the anchor-scroll script scrolls to that element (e.g. /docs/foo/bar?section=foo → /docs/foo/ with ?article=bar, URL bar unchanged)
3. Markdown Export (?format=md): Serves pre-built markdown output with appropriate Content-Type header
4. Embed Format (?format=embed): Serves embed-optimized HTML for iframe integration
5. WebSocket Support: Transparently proxies WebSocket connections for Hugo's live-reload feature

# Default: proxy on port 3131, Hugo on auto-selected port
presidium server

# Custom port for proxy
presidium server --port 8080

# Disable proxy (direct Hugo server)
presidium server --no-proxy

# Pass additional Hugo flags after the Presidium-specific flags
presidium server --buildDrafts --buildFuture

# Or be explicit with -- separator (both work the same)
presidium server -- --buildDrafts --buildFuture

When presidium server runs:

1. Hugo server starts on an auto-selected internal port (typically 1313+)
2. Presidium proxy starts on port 3131 (or custom --port)
3. Requests flow through middleware chain: Normalize → Rewrite → WebSocket → Proxy
4. Both servers shut down gracefully on Ctrl+C

This architecture is equivalent to running Hugo behind Caddy but without requiring external dependencies.

Run the full test suite:

make test

Verify that the binary works without network access using Docker:

make test-offline

This test:

• Prepares the themes.zip bundle from git submodules
• Builds Presidium inside a Docker container using multi-stage build (Go 1.25 + extended Hugo with LibSass)
• Runs presidium hugo in an isolated container with --network none
• Verifies all expected output files are generated (index.html, presidium.js, links.js, assets, images)
• Confirms no network access was attempted

The multi-stage Docker build ensures proper Linux binary compilation with all required C++ dependencies for SCSS support.

Requirements: Docker must be installed and running.