# @pagesmith/docs Full AI Reference

This file is the package-shipped source of truth for AI assistants using `@pagesmith/docs`.

## Install

```bash
npm add @pagesmith/docs
```

## Versioning note

- Package-shipped guidance in `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/` and `node_modules/@pagesmith/docs/schemas/` is version-matched to what is installed.
- The Pagesmith docs site is maintained for latest behavior and can differ from older installed versions.

## Priority order

1. `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/setup-docs.md` for bootstrap/retrofit setup in existing repositories.
2. `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/migration.md` for upgrading an existing integration and adopting the latest package guidance/features.
3. `node_modules/@pagesmith/docs/REFERENCE.md` for complete config, CLI, content structure, frontmatter, markdown, and deployment details.
4. `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/usage.md` for package rules, expected docs structure, and copy-paste agent prompts.
5. `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/recipes.md` for step-by-step task recipes.

## Key rules

- Use `@pagesmith/docs` for convention-based docs sites.
- Keep docs structure in your content directory (defaults to `docs/` if it exists, otherwise `content/`) with `README.md` as home.
- Configure **`home`**, **`server`** (`host`, `devPort` default **3000**, `previewPort` default **4000** — both accept the literal `"auto"` to scan upward from 4000 for the first available port, `strictPort` honored only when the resolved port is a number, `logLevel` default **`info`**), **`icon`**, **`maintainer`**, **`footerLinks`**, **`footerText`**, **`copyright`**, **`editLink`**, and **`lastUpdated`** in `pagesmith.config.json5` as needed.
- Use `meta.json5` and frontmatter for ordering and labels, not hardcoded nav lists.
- Keep search configuration inside `pagesmith.config.json5`; Pagefind is built in, and layout overrides should scope `data-pagefind-body` to the content-only wrapper rather than the full shell.
- Use `theme.layouts` keys (`home`, `page`, `listing`, `notFound`) for layout overrides.
- Use the version-matched schema files in `node_modules/@pagesmith/docs/schemas/` when editing config, meta.json5, or frontmatter.
- When `pagesmith.config.json5` is committed, keep its `$schema` pointing at the installed file in `node_modules/@pagesmith/docs/schemas/pagesmith-config.schema.json`.
- For GitHub repos, bootstrap flows should default to GitHub Pages values: probe `https://<owner>.github.io` for `origin`, keep `basePath` as `/<repo-name>`, and treat root hosting as a manual config edit.
- Prefer the package MCP server for config/page introspection: `pagesmith-docs mcp --stdio`.
- Prefer AI-first setup with `pagesmith-docs init --ai` so docs structure + assistant context stay aligned from day one.
- Prefer `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/migration.md` when the repo already uses `@pagesmith/docs` and the task is to upgrade or adopt newer guidance.
- Keep onboarding first in manual nav order (for example `getting-started` first in `guide/meta.json5`).
- `markdown.images.lazyLoading` (default `true`) and `markdown.images.eagerCount` (default `1`) control lazy/eager loading hints on content images; both are JSON-safe and validated by `schemas/pagesmith-config.schema.json`.
- Sitemap generation (the `sitemap: true` config default) delegates to `@pagesmith/site/ssg-utils`'s `generateSitemap` — output is unchanged, but any custom tooling that imported the old in-package serializer should switch to that shared export.
- Install/refresh consumer Agent Skills with `npx pagesmith skills install` (the umbrella command ships from `@pagesmith/site`; `pagesmith-docs` has no `skills` subcommand of its own). `--check` verifies without writing, for CI.

## Package files

All paths below are under `node_modules/@pagesmith/docs/`:

| File | Purpose |
|---|---|
| `node_modules/@pagesmith/docs/REFERENCE.md` | Complete config, CLI, content structure, frontmatter, markdown, layout, deployment |
| `node_modules/@pagesmith/docs/README.md` | User-facing quick start and API overview |
| `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/setup-docs.md` | Canonical bootstrap/retrofit prompt for existing repos |
| `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/docs-guidelines.md` | Docs-specific structure, navigation, and ownership rules |
| `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/markdown-guidelines.md` | Markdown authoring and pipeline rules for docs projects |
| `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/migration.md` | Upgrade playbook and copy-paste prompt for existing integrations |
| `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/usage.md` | Agent rules, integration shape, copy-paste prompts for common workflows |
| `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/recipes.md` | Step-by-step recipes (bootstrap, sections, pages, meta, layouts, MCP) |
| `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/errors.md` | Error catalog with patterns and fixes |
| `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/changelog-notes.md` | Version highlights |
| `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/AGENTS.md.template` | Template for project AGENTS.md with task-specific file pointers |
| `node_modules/@pagesmith/docs/schemas/*.schema.json` | Version-matched schemas for config, meta.json5, and docs frontmatter |
| `node_modules/@pagesmith/docs/llms.txt` | Compact AI context index (also exposed via `@pagesmith/docs/llms`) |
| `node_modules/@pagesmith/docs/llms-full.txt` | This file — full AI context (also exposed via `@pagesmith/docs/llms-full`) |

## Agent prompts by use case

Start with `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/setup-docs.md` for bootstrap or retrofit work in an existing repo.
Start with `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/migration.md` when the repo already uses `@pagesmith/docs` and the task is to upgrade or adopt new package guidance.
The `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/usage.md` file contains follow-up prompts for these workflows:

1. **Initial installation and setup** → reads `node_modules/@pagesmith/docs/REFERENCE.md`, `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/recipes.md`
2. **Upgrade existing integration** → reads `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/migration.md`, `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/changelog-notes.md`, `node_modules/@pagesmith/docs/REFERENCE.md`
3. **Writing documentation pages** (frontmatter, code blocks, mermaid) → reads `node_modules/@pagesmith/docs/REFERENCE.md`
4. **Updating docs structure** → reads `node_modules/@pagesmith/docs/REFERENCE.md`, `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/recipes.md`
5. **Docs organization and meta files** → reads `node_modules/@pagesmith/docs/REFERENCE.md`
6. **Troubleshooting build/config errors** → reads `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/errors.md`
7. **Layout overrides and theming** → reads `node_modules/@pagesmith/docs/REFERENCE.md`, `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/recipes.md`

## Pointer snippet for consuming projects

Add to project-level `CLAUDE.md` or `AGENTS.md`:

```
For @pagesmith/docs bootstrap and retrofit tasks, read node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/setup-docs.md
For @pagesmith/docs usage and prompts, read node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/usage.md
For the full @pagesmith/docs reference, see node_modules/@pagesmith/docs/REFERENCE.md
For version-matched docs schemas, read node_modules/@pagesmith/docs/schemas/*.schema.json
```

## Related core package

- Core reference: `node_modules/@pagesmith/core/REFERENCE.md`
- Core usage: `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/usage.md`
- Core README: `node_modules/@pagesmith/core/README.md`

## Navigation types

`@pagesmith/docs` exports navigation and content types for theme customization:

Types: `NavItem`, `SidebarSection`, `SidebarItem`, `PrevNextLink`, `SiteModel`, `DocsPage`, `DocsSectionMeta`, `DocsRootMeta`
Functions: `buildSiteModel`, `getPrevNext`, `getSitePayload`

## Primary export surface (`@pagesmith/docs`)

Also exported from the main package entry (see `src/index.ts` / `REFERENCE.md`):

- Config and commands: `build`, `defineDocsConfig`, `loadDocsConfig`, `preview`, `reportConfigIssues`, `resolveDocsConfig`, `startDev`, `validateConfig`, `withBase`, `docsPreset`
- Theme: `Html`
- MCP: `createDocsMcpServer`, `startDocsMcpServer`

## MCP tools

The docs MCP server (`pagesmith-docs mcp --stdio`) exposes:

- `docs_validate_config` — validate pagesmith.config.json5
- `docs_resolve_config` — resolve effective config with defaults
- `docs_list_pages` — list all pages with routes and source files
- `docs_get_page` — get a page by slug with markdown source
- `docs_search_pages` — search pages by query (title, description, content)

Version-matched MCP resources:
- `pagesmith://docs/agents/usage`
- `pagesmith://docs/llms-full`
- `pagesmith://docs/reference`
- `pagesmith://core/reference`

## Theme system

Built-in multi-theme support with header toggle dropdown and footer theme selector:
- **Color scheme**: `color-scheme-auto` (OS) | `color-scheme-light` | `color-scheme-dark`
- **Theme**: `theme-paper` (warm, low-contrast) | `theme-high-contrast` (WCAG AAA)
- Config: `theme.defaultColorScheme` (`'auto'|'light'|'dark'`), `theme.defaultTheme` (`'paper'|'high-contrast'`)
- User preferences persist in `localStorage('pagesmith-theme')`
- Progressive enhancement: no-JS uses OS preference; JS enables toggle UI and persistence
- FOUC prevention via inline `<script>` in `<head>` before CSS loads
- Theme runtime: delegated to `@pagesmith/site/runtime/standalone` via `theme/runtime/main.ts`
- Styles: inherited from `@pagesmith/site/css/standalone` via `theme/styles/main.css`; docs-only additions in `theme/styles/layout/home.css` and `theme/styles/components/not-found.css`
- Footer links support two shapes: a flat link grid of `{ label, path }` links or grouped columns of `{ header?, links }`. On wide screens the footer uses up to 4 evenly spaced columns, and prev/next navigation now renders between page metadata and the footer link area. When `footerLinks` is omitted, the footer falls back to the major top-level nav links.
- `DocHome` uses the same main content-column width and inline padding as `DocPage`, so the landing page and content pages stay visually aligned even when sidebars appear or disappear around the content.
- Footer legal line: configurable with `copyright` for `{ projectName, startYear, endYear?: number | null }`; the default sign-off is "Made with love using Pagesmith" with a heart icon, a link to `https://projects.sujeet.pro/pagesmith/`, and an optional maintainer credit from `maintainer` or `package.json` author. `footerText` overrides only that sign-off segment.
- `editLink` auto-detects from supported git remotes unless set to `false`, and `lastUpdated` defaults to `true`.