Skip to main content

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 default site is served from docs/_site/. Use --config to select a custom documentation directory. Run great-docs build after source 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.

Use --mr, --pipeline or --job for GitLab artifacts. Pass ‘--provider gitlab’ with shorthand repositories or self-managed hosts. Preserve HTTP installation prefixes with --repo-base-url. GitLab metadata reads use GITLAB_TOKEN; direct job downloads also support permitted CI_JOB_TOKEN access.

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 default site is served from 'docs/_site/'. Use '--config' to select a
  custom documentation directory. Run 'great-docs build' after source 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.

  Use '--mr', '--pipeline' or '--job' for GitLab artifacts. Pass '--provider
  gitlab' with shorthand repositories or self-managed hosts. Preserve HTTP
  installation prefixes with '--repo-base-url'. GitLab metadata reads use
  GITLAB_TOKEN; direct job downloads also support permitted CI_JOB_TOKEN
  access.

  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 GitHub CI docs build for a
                              branch.
  --mr INTEGER RANGE          Preview a GitLab merge-request IID in its target
                              project.  [x>=1]
  --pipeline INTEGER RANGE    Preview a GitLab pipeline ID.  [x>=1]
  --job INTEGER RANGE         Download a GitLab job artifact directly.  [x>=1]
  --provider [github|gitlab]  Repository provider for shorthand or self-
                              managed input.
  --repo-base-url TEXT        GitLab instance base, including any HTTP
                              installation prefix.
  --repo TEXT                 Repository URL or provider-specific shorthand
                              (default: 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 provider credentials from a .env file
                              (default: auto-detect .env).
  --config FILE               Path to the project configuration file
  --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 GitHub CI docs build for a branch.
--mr: INTEGER RANGE
Preview a GitLab merge-request IID in its target project.
--pipeline: INTEGER RANGE
Preview a GitLab pipeline ID.
--job: INTEGER RANGE
Download a GitLab job artifact directly.
--provider: [github|gitlab]
Repository provider for shorthand or self-managed input.
--repo-base-url: TEXT
GitLab instance base, including any HTTP installation prefix.
--repo: TEXT
Repository URL or provider-specific shorthand (default: 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 provider credentials from a .env file (default: auto-detect .env).
--config: FILE
Path to the project configuration file

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