Use `glaze render-site` to export the Glazed help browser as a static site that can be previewed locally or hosted without a Go server.
glaze render-site existsglaze render-site exports the same help browser used by glaze serve, but writes everything to disk instead of starting a live HTTP server. The exported site contains the SPA assets, a runtime config file, and a static JSON snapshot of the loaded help sections.
This matters when you want browser-based help without keeping a Go process running. It is useful for publishing documentation to a static host, attaching generated docs to a release artifact, or previewing a frozen documentation snapshot during review.
glaze render-site from the command lineThe simplest invocation exports the built-in Glazed documentation into ./glaze-site:
glaze render-site
You can also export a custom help tree from one or more markdown files or directories:
glaze render-site ./pkg/doc
glaze render-site ./pkg/doc ./more-docs
If you want to choose the destination directory explicitly, use --output-dir:
glaze render-site ./pkg/doc --output-dir /tmp/glaze-doc-site
When the command runs:
site-config.js file and a site-data/ JSON tree the SPA can browse without /api/....These flags control where the site is written and how the generated URLs behave:
| Flag | What it does | When to use it |
|---|---|---|
--output-dir | Chooses the export directory | Use it when you do not want the default ./glaze-site path |
--overwrite | Allows reusing a non-empty output directory | Use it when regenerating an existing export |
--base-path | Writes a base path into the runtime config | Use it when the site will be hosted under a prefix such as /docs |
--data-dir | Renames the relative directory that stores exported JSON | Use it only if you have a hosting constraint or want a different layout |
--site-title | Sets the title written into the runtime config | Use it when exporting docs for another application or branded site |
The exported site is a normal directory tree. The exact asset filenames under assets/ are content-hashed and may change between builds, but the stable files and directories look like this:
| Path | Purpose |
|---|---|
index.html | SPA entrypoint |
site-config.js | Runtime config that tells the frontend to run in static mode |
assets/ | Bundled JS and CSS assets for the embedded frontend |
site-data/health.json | Health metadata with the number of exported sections |
site-data/sections.json | Full list of section summaries used for the sidebar |
site-data/sections/<slug>.json | Per-section detail payloads |
site-data/indexes/topics.json | Topic-to-slug lookup index |
site-data/indexes/commands.json | Command-to-slug lookup index |
site-data/indexes/flags.json | Flag-to-slug lookup index |
site-data/indexes/top-level.json | Slugs marked as top-level |
site-data/indexes/defaults.json | Slugs shown by default |
site-data/manifest.json | Build metadata for the exported snapshot |
The exported output is static, so you can preview it with any simple file server. A quick local check looks like this:
glaze render-site ./pkg/doc --output-dir /tmp/glaze-doc-site --overwrite
python3 -m http.server 8123 --directory /tmp/glaze-doc-site
Then open:
http://127.0.0.1:8123/
Because the frontend uses hash routes, links such as #/sections/help-system work on simple static hosting without server-side route rewrites.
The generated output can be copied to any static host that serves plain files. In practice that includes:
If you are hosting under a sub-path such as /docs, export with --base-path /docs so the runtime config points the SPA at the right static JSON directory.
glaze render-site ./pkg/doc --output-dir ./dist/docs --base-path /docs --overwrite
glaze serveglaze serve and glaze render-site use the same help content and the same frontend, but they solve different delivery problems:
| Command | Best for | Runtime model |
|---|---|---|
glaze serve | Local exploration, embedding into a live Go server, dynamic API access | Starts an HTTP server and serves /api/... plus the SPA |
glaze render-site | Publishing or sharing a frozen documentation snapshot | Writes files to disk and serves no live API |
Choose serve when you want a running server process. Choose render-site when you want an artifact you can copy, host, or review later.
| Problem | Cause | Solution |
|---|---|---|
output directory "...\" is not empty | The destination already contains files and --overwrite was not set | Re-run with --overwrite or choose a fresh output directory |
| The export completes but expected pages are missing | The supplied markdown files were not loaded or did not contain valid help frontmatter | Verify the paths exist, files end in .md, and the frontmatter includes fields like Title, Slug, and SectionType |
The browser loads index.html but sections do not appear | The site is being opened incorrectly or the exported JSON tree is missing | Serve the directory over HTTP and confirm site-config.js and site-data/sections.json exist |
Links work at / but not under /docs or another prefix | The static host path and exported base path do not match | Re-export with --base-path set to the hosted prefix |
| A regenerated site still shows old content | The old output directory contents were left in place | Re-run with --overwrite to clear the export directory before writing the new snapshot |
glaze help export-help-entries — Export help sections to files, JSON, CSV, or SQLiteglaze help serve-help-over-httpglaze help writing-help-entriesglaze help how-to-write-good-documentation-pagesglaze help sections-guide