README
¶
cli-web-docs
cli-web-docs is a static HTML documentation generator for urfave/cli v3 command trees, featuring:
- canonical Markdown from urfave/cli-docs, rendered to HTML by goldmark
- single-page or per-command output via
Options.PerPage - shared layout subpackage (also consumed by cli-web-ops) so docs + ops pages read as one site
- dark-mode-aware default stylesheet, fully overridable via
Options.CSS - pure Go, no JavaScript in the generated output
- pairs with any static host (GitHub Pages, S3, Caddy via
deploy/Caddyfile.example)
Documentation
See docs/FEATURES.md for a feature inventory and examples/ for four runnable demos (render, multi-page, custom-theme, deep-tree). Local dev verbs live in .agent-guard/agent-guard.yaml; agent-guard lint validates that against the Makefile.
Support
If you found a bug or have a feature request, create a new issue. Participation in this community is governed by the Code of Conduct. Security disclosures go through SECURITY.md.
Sibling repos in the cli-* family: cli-guard, cli-mcp, cli-web-ops.
License
See LICENSE.
See also
- AGENTS.md - agent-facing operating rules.
- docs/FEATURES.md - inventory of what ships today.
- .agent-guard/agent-guard.yaml - allowlisted commands.
Cross-reference convention from coilysiren/agentic-os#59.
Documentation
¶
Overview ¶
Package webdocs renders a urfave/cli v3 command tree as a static HTML documentation site.
Pipeline:
- urfave/cli-docs/v3 generates canonical Markdown from the command tree.
- yuin/goldmark renders the Markdown as HTML (GFM tables, footnotes, fenced code blocks).
- webdocs wraps the rendered HTML in the shared layout shell from cli-web-docs/layout (also consumed by cli-web-ops, so docs and ops pages share visual identity).
Two layout modes:
- Single-page (default): one index.html with cli-docs's full Markdown for the root command (subcommands inlined) rendered into one page.
- Multi-page (Options.PerPage = true): one HTML file per visible subcommand, plus an index.html that lists the tree.
Independent of every other cli-* extension at the type level. Operates on any *cli.Command via the public urfave/cli API.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Render ¶
Render writes documentation for cmd into Options.OutputDir.
Example ¶
Render the documentation for a *cli.Command into a directory. Single-page output is the default; pass Options.PerPage = true for one HTML file per visible subcommand.
app := &cli.Command{
Name: "demo",
Usage: "tiny demo cli",
Commands: []*cli.Command{
{Name: "hello", Usage: "say hello"},
},
}
dir, _ := os.MkdirTemp("", "webdocs-example-*")
defer os.RemoveAll(dir)
if err := webdocs.Render(app, webdocs.Options{
OutputDir: dir,
Title: "Demo Docs",
}); err != nil {
fmt.Println("render:", err)
return
}
_, err := os.Stat(filepath.Join(dir, "index.html"))
fmt.Println("index.html exists:", err == nil)
Output: index.html exists: true
Types ¶
type Options ¶
type Options struct {
// OutputDir is the directory to write into. Created if it does not
// exist. Required.
OutputDir string
// Title overrides the page <title>. Defaults to the root command name.
Title string
// PerPage = true emits one HTML file per visible subcommand at
// "<path>.html" plus an index.html that lists the tree.
PerPage bool
// CSS overrides the embedded default stylesheet. Empty = use the
// shared layout.DefaultCSS.
CSS string
}
Options control the rendered output. Zero value is usable: single-page mode, default CSS, title taken from cmd.Name.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
custom-theme
command
Command custom-theme demonstrates overriding the default stylesheet with operator-supplied CSS.
|
Command custom-theme demonstrates overriding the default stylesheet with operator-supplied CSS. |
|
deep-tree
command
Command deep-tree renders documentation for a CLI with three levels of nested subcommands and a realistic flag surface.
|
Command deep-tree renders documentation for a CLI with three levels of nested subcommands and a realistic flag surface. |
|
multi-page
command
Command multi-page renders a small CLI as a multi-page documentation site: one HTML file per visible subcommand plus an index.html that lists the tree.
|
Command multi-page renders a small CLI as a multi-page documentation site: one HTML file per visible subcommand plus an index.html that lists the tree. |
|
render
command
Command render is a tiny example that emits cli-web-docs HTML for a sample CLI into ./site.
|
Command render is a tiny example that emits cli-web-docs HTML for a sample CLI into ./site. |
|
Package layout is the shared HTML layout shell for the cli-web-* family (cli-web-docs and cli-web-ops).
|
Package layout is the shared HTML layout shell for the cli-web-* family (cli-web-docs and cli-web-ops). |