GitHub

CLI Reference

Static Docs command line commands, arguments, and flags.

All commands follow this pattern:

bash
static-docs <command> [options]

--config accepts either a site.toml file or a project directory containing site.toml.

init

Scaffold a new project directory.

bash
static-docs init [path]
ParameterTypeStatusDescription
pathargumentOptionalDirectory to initialize. Defaults to the current directory.

build

Build the site to output_dir from site.toml.

bash
static-docs build --config <path/to/site.toml>
ParameterTypeStatusDescription
--configflagOptionalPath to site.toml or a project directory. Defaults to site.toml.

preview

Start the local development server with live reload.

bash
static-docs preview --config <path/to/site.toml> --host 127.0.0.1 --port 8000

serve is an alias for preview.

ParameterTypeStatusDescription
--configflagOptionalPath to site.toml or a project directory. Defaults to site.toml.
--hostflagOptionalNetwork interface to bind. Defaults to 127.0.0.1.
--portflagOptionalPort to listen on. Defaults to 8000.

publish

Build the site and copy the output to a destination directory.

bash
static-docs publish --config <path/to/site.toml> --destination ./release
ParameterTypeStatusDescription
--configflagOptionalPath to site.toml or a project directory. Defaults to site.toml.
--destinationflagOptionalOptional destination directory. Defaults to the configured output_dir.

gh-deploy

Build the site, add GitHub Pages artifacts, and force-push the output to a deploy branch.

bash
static-docs gh-deploy --config <path/to/site.toml> --remote origin --branch gh-pages
ParameterTypeStatusDescription
--configflagOptionalPath to site.toml or a project directory. Defaults to site.toml.
--remoteflagOptionalGit remote to push to. Defaults to origin.
--branchflagOptionalBranch to force-push generated output to. Defaults to gh-pages.
--messageflagOptionalCommit message for the deploy commit. Defaults to Deploy static-docs site.

api generate

Generate Markdown API reference pages from Python source files.

bash
static-docs api generate --source src --output content/api --package my_package
ParameterTypeStatusDescription
--sourceflagOptionalPython source directory. Defaults to src.
--outputflagOptionalDirectory where generated Markdown pages are written. Defaults to content/api.
--packageflagOptionalOptional package prefix for generated module names.
--titleflagOptionalTitle for the generated API index page. Defaults to API Reference.
--include-privateflagOptionalInclude private Python objects.
--include-initflagOptionalInclude __init__.py modules.
Getting StartedConfiguration