great-docs preview

Preview your documentation locally.

great-docs preview [OPTIONS]

Starts a local HTTP server and opens the built documentation site in your default browser. If the site hasn’t been built yet, it will build it first.

The site is served from great-docs/_site/. Use great-docs build to rebuild if you’ve made changes.

Use --site-dir to preview a site from any directory (e.g. output from a --from-repo build).

Use --pr, --run, or --branch to fetch and preview a site that CI already built (no hosting setup required). Downloading CI artifacts needs a GitHub token with Actions: read (via GITHUB_TOKEN, a .env, or ‘gh auth login’ + --use-gh). For fork PRs you’ll be viewing contributor-authored HTML locally.

Full --help output

Usage: great-docs preview [OPTIONS]

  Preview your documentation locally.

  Starts a local HTTP server and opens the built documentation site in your
  default browser. If the site hasn't been built yet, it will build it first.

  The site is served from 'great-docs/_site/'. Use 'great-docs build' to
  rebuild if you've made changes.

  Use '--site-dir' to preview a site from any directory (e.g. output from a '
  --from-repo' build).

  Use '--pr', '--run', or '--branch' to fetch and preview a site that CI
  already built (no hosting setup required). Downloading CI artifacts needs a
  GitHub token with 'Actions: read' (via GITHUB_TOKEN, a .env, or 'gh auth
  login' + '--use-gh'). For fork PRs you'll be viewing contributor-authored
  HTML locally.

  Examples:
    great-docs preview                    # Preview on port 3000
    great-docs preview --port 8080        # Preview on port 8080
    great-docs preview --site-dir /tmp/weathervault-site
    great-docs preview --pr 302           # Newest CI build for PR #302
    great-docs preview --run 18273645521  # A specific workflow run
    great-docs preview --pr 302 --path reference/mcp/gd_config.html

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --port INTEGER            Port for the local preview server  [default: 3000]
  --site-dir DIRECTORY      Path to a pre-built site directory to serve
                            (bypasses project detection)
  --pr INTEGER              Preview the CI docs build for this PR number.
  --run INTEGER             Preview a specific workflow run id.
  --branch TEXT             Preview the newest CI docs build for a branch.
  --repo TEXT               GitHub repo as 'owner/repo' (default: detect from
                            git remote / config).
  --artifact TEXT           Name of the CI artifact to fetch.  [default: docs-
                            html]
  --path TEXT               Open the browser at this page within the site
                            (e.g. reference/index.html).
  --no-open                 Serve without launching a browser.
  --refresh                 Ignore the local cache and re-download.
  --clear-cache             Delete the downloaded PR-preview cache and exit.
  --use-gh                  Fetch via the 'gh' CLI (uses your existing gh
                            auth) instead of a token.
  --env-file FILE           Load a .env for GITHUB_TOKEN/GH_TOKEN (default:
                            auto-detect .env).
  --help                    Show this message and exit.

Options

--project-path: DIRECTORY: Path to your project root directory (default: current directory)
--port: INTEGER = 3000: Port for the local preview server
--site-dir: DIRECTORY: Path to a pre-built site directory to serve (bypasses project detection)
--pr: INTEGER: Preview the CI docs build for this PR number.
--run: INTEGER: Preview a specific workflow run id.
--branch: TEXT: Preview the newest CI docs build for a branch.
--repo: TEXT: GitHub repo as owner/repo (default: detect from git remote / config).
--artifact: TEXT = docs-html: Name of the CI artifact to fetch.
--path: TEXT =: Open the browser at this page within the site (e.g. reference/index.html).
--no-open: Serve without launching a browser.
--refresh: Ignore the local cache and re-download.
--clear-cache: Delete the downloaded PR-preview cache and exit.
--use-gh: Fetch via the gh CLI (uses your existing gh auth) instead of a token.
--env-file: FILE: Load a .env for GITHUB_TOKEN/GH_TOKEN (default: auto-detect .env).

Examples

  great-docs preview                    # Preview on port 3000
  great-docs preview --port 8080        # Preview on port 8080
  great-docs preview --site-dir /tmp/weathervault-site
  great-docs preview --pr 302           # Newest CI build for PR #302
  great-docs preview --run 18273645521  # A specific workflow run
  great-docs preview --pr 302 --path reference/mcp/gd_config.html