Docs CLI Reference

Docs projects use the package-owned pagesmith-docs CLI from @pagesmith/docs. It is the canonical command surface for scaffolding, developing, building, previewing, and exposing docs-aware MCP tools.

Installation

1npm add @pagesmith/docs

Then run commands with npx pagesmith-docs ... or through package scripts.

Command Summary

1pagesmith-docs init [options]2pagesmith-docs dev [options]3pagesmith-docs build [options]4pagesmith-docs preview [options]5pagesmith-docs validate [options]6pagesmith-docs mcp --stdio [options]

Configuration File

pagesmith-docs resolves the config file in this order (first match wins):

1. --config <path> (explicit override)
2. pagesmith.config.ts (loaded via jiti, supports defineConfig)
3. pagesmith.config.mts
4. pagesmith.config.mjs
5. pagesmith.config.js
6. pagesmith.config.json5
7. pagesmith.config.json

1import { defineConfig } from "@pagesmith/docs";23export default defineConfig({4  name: "my-docs",5  title: "My Docs",6  origin: "https://example.com",7  basePath: "/my-docs",8});

init writes a JSON5 file. When you already have a .ts/.js config, init reads it for prompt defaults but does not overwrite the file — the user owns code-shaped configs.

How The Commands Fit Together

Notice that init is a setup step you can rerun safely, dev/build/preview form the main docs workflow, and mcp --stdio is a separate path for assistant tooling rather than static-site output.

pagesmith-docs init

Use init when you want Pagesmith to scaffold or backfill a docs project.

What it does:

1. Creates or updates pagesmith.config.json5.
2. Adds the $schema reference to node_modules/@pagesmith/docs/schemas/pagesmith-config.schema.json.
3. Scaffolds starter content when the expected docs pages are missing.
4. Detects GitHub Pages-friendly defaults from the repo name and git remote.
5. Optionally installs AI artifacts with --ai.

Common flags:

init runs as an interactive prompt by default when stdout and stdin are both TTYs. It auto-falls back to non-interactive mode (using the detected defaults) when --yes / --non-interactive is passed, when CI=1 or PAGESMITH_NON_INTERACTIVE=1 is set, or when stdout/stdin are not TTYs. This keeps CI/CD pipelines from blocking on a prompt.

In non-interactive mode init fails fast when --name, --origin, or --base-path cannot be resolved from flags, the existing pagesmith.config.{ts,json5,...}, or smart defaults (git remote, package.json name, repo basename). The error message points at the missing flag and config key so the failure is immediately actionable.

Examples:

1npx pagesmith-docs init2npx pagesmith-docs init --yes --ai3npx pagesmith-docs init --non-interactive --ai --content-dir docs --base-path /my-repo --origin https://my-user.github.io4CI=1 npx pagesmith-docs init --ai   # non-interactive auto-detected from env

init is safe to rerun. It backfills missing config fields instead of blindly replacing the whole file.

pagesmith-docs dev

Starts the docs development server with live reload.

1npx pagesmith-docs dev

Common flags:

Use dev for content editing, layout work, navigation checks, and local theme iteration.

pagesmith-docs build

Builds the full static docs site.

1npx pagesmith-docs build

The build resolves config, loads content and meta.json5, renders markdown through the shared Pagesmith pipeline, renders docs layouts, copies static assets, publishes markdown companion assets under preserved content-relative /assets/... paths, and runs Pagefind when search is enabled.

Examples:

1npx pagesmith-docs build2npx pagesmith-docs build --base-path /my-repo3BASE_URL=/my-repo npx pagesmith-docs build

Base-path precedence:

1. --base-path
2. BASE_URL
3. basePath in config
4. Git remote detection
5. /

pagesmith-docs preview

Serves the built output directly from disk.

1npx pagesmith-docs preview

Use preview to verify production behavior such as built search assets, slashless routing, and basePath handling.

pagesmith-docs validate

Runs the docs validator against your content and (optionally) the build output.

1npx pagesmith-docs validate2npx pagesmith-docs validate --content       # only content3npx pagesmith-docs validate --build         # only build output (after a build)4npx pagesmith-docs validate --full          # enable every opt-in offline check

Common flags:

Validate exits non-zero on the first error so it works as a CI gate.

pagesmith-docs mcp --stdio

Starts the docs-aware MCP server from @pagesmith/docs.

1npx pagesmith-docs mcp --stdio

Common flags:

The server exposes tools such as:

• docs_validate_config
• docs_resolve_config
• docs_list_pages
• docs_get_page
• docs_search_pages

Version-matched resources exposed by the docs MCP server:

• pagesmith://docs/agents/usage
• pagesmith://docs/llms-full
• pagesmith://docs/reference
• pagesmith://core/reference

Zero-Config Behavior

pagesmith-docs dev, build, preview, and mcp --stdio can run without pagesmith.config.json5 when the project already follows the default conventions:

• <repo-root>/docs if it exists, otherwise <repo-root>/content
• standard docs pages like README.md
• optional meta.json5 files for navigation
• default output under gh-pages

init is still the preferred way to make the contract explicit, add schema validation, and install AI artifacts.

Recommended Scripts

1{2  "scripts": {3    "docs:dev": "pagesmith-docs dev",4    "docs:build": "pagesmith-docs build",5    "docs:preview": "pagesmith-docs preview"6  }7}

Typical Workflow

1npx pagesmith-docs init --yes --ai2npx pagesmith-docs dev --open3npx pagesmith-docs build4npx pagesmith-docs preview

Related References

• Docs Getting Started
• AI Assistants
• Prompts Cookbook