{frontmatter.title} — {site.title}

); } ``` ### Layout Props **All layouts** receive: `content`, `frontmatter`, `headings`, `slug`, `site`. **Page layout** additionally: `sidebarSections`, `prev`, `next`. **Listing layout** additionally: `listingCards`, `listingGroups`, `listingTotal`. **Home layout** additionally: `frontmatter.hero`, `frontmatter.features`, `frontmatter.packages`, `frontmatter.install`, `frontmatter.installHtml`. `frontmatter.installHtml` is the pre-rendered HTML produced by piping the user-supplied `install` field through the Pagesmith markdown code pipeline. The default `DocHome` layout injects it via `innerHTML`. Custom home layout overrides should do the same instead of re-implementing chrome by hand — that way the install snippet always matches the rest of the site's code blocks. Layouts use `@pagesmith/docs/jsx-runtime`: ```tsx import { Fragment } from "@pagesmith/docs/jsx-runtime"; export default function DocPage(props) { const { content, frontmatter, headings, slug, site, sidebarSections, prev, next } = props; return ( {frontmatter.title} — {site.title}

); } ``` ## Navigation - **Top nav** — auto-generated from top-level content folders; override with `headerLinks` in your content root's `meta.json5` (for example `docs/meta.json5`) - **Sidebar** — auto-generated per top-level section as a flat page list. Nested files stay in the same section, and `series` groups plus `items` ordering come from `meta.json5`. - **Breadcrumbs** — auto-generated from the content slug path on every non-home page with depth > 1 (e.g. `guide/getting-started/intro` shows "Guide / Getting Started / Intro"). No configuration needed. - **Prev/next** — auto-generated from flattened sidebar items on every non-home page - **Footer** — renders either a flat link grid or grouped link columns. On wide screens it uses up to 4 evenly spaced columns. Uses `footerLinks` when configured, otherwise falls back to the top nav items. The bottom legal line combines `copyright` with the Pagesmith sign-off, and `footerText` overrides only the sign-off segment. ## Search Pagefind full-text search is bundled. Enable with `search.enabled: true` (default). Trigger with `Cmd+K` / `Ctrl+K`. When overriding layouts, put `data-pagefind-body` on the content-only wrapper, ideally the page `

` or a dedicated home-page body wrapper, rather than the full shell that includes navigation or footer chrome. The search runtime is always loaded under your `basePath`. Pagesmith emits an explicit `` element ahead of the Pagefind component-UI loader script so search keeps working on sub-path deploys (GitHub Pages project sites, `/docs/`, etc.). You do not need to set this yourself. Set `search.enabled: false` to opt out entirely. When disabled, the Pagefind binary is never invoked at build time, the `/pagefind/` directory is not produced, and every page is rendered without the Pagefind UI script, stylesheet, modal markup, or trigger button — useful for shaving the index, WASM, and UI bundle when search is not needed. ## Programmatic API ```ts import { build, startDev, preview, defineDocsConfig, validateConfig, resolveDocsConfig, loadDocsConfig, reportConfigIssues, withBase, docsPreset, Html, buildSiteModel, getPrevNext, getSitePayload, } from "@pagesmith/docs"; await build({ configPath: "./pagesmith.config.json5" }); await startDev({ port: 3000 }); await preview({ port: 4000 }); // Config validation const config = resolveDocsConfig("./pagesmith.config.json5"); const issues = validateConfig(config); reportConfigIssues(issues); // Load raw user config (without resolution) const userConfig = loadDocsConfig("./pagesmith.config.json5"); // URL helper const url = withBase("/guide/getting-started", config.basePath); ``` ## Export Map | Import Path | Purpose | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@pagesmith/docs` | Main API (build, startDev, preview, defineDocsConfig, validateConfig, resolveDocsConfig, loadDocsConfig, reportConfigIssues, withBase, docsPreset, Html, buildSiteModel, getPrevNext, getSitePayload) | | `@pagesmith/docs/components` | Re-exported shared chrome components for docs overrides | | `@pagesmith/docs/layouts` | Re-exported shared layout wrappers for docs overrides | | `@pagesmith/docs/jsx-runtime` | JSX runtime for docs layout overrides | | `@pagesmith/docs/jsx-dev-runtime` | JSX dev runtime for docs layout overrides | | `@pagesmith/docs/schemas` | Zod schemas for config, layout props, page data | | `@pagesmith/docs/schemas/*` | Individual JSON schema and generated schema entry points | | `@pagesmith/docs/preset` | Docs preset for Vite integration (`docsPreset`) | | `@pagesmith/docs/theme` | Theme/runtime export surface (`Html`) backed by the shared site chrome/layout exports | | `@pagesmith/docs/build-validator` | Docs-aware re-export of build-output validators | | `@pagesmith/docs/mcp` | Stdio MCP server entry (`createDocsMcpServer`, `startDocsMcpServer`) | | `@pagesmith/docs/llms` | Compact AI context index | | `@pagesmith/docs/llms-full` | Full AI context reference | | `@pagesmith/docs/skills/pagesmith-docs-setup/references/*` | Package-shipped AI guidance files | | `@pagesmith/docs/agents/setup-docs` | Bootstrap prompt for project agents | | `@pagesmith/docs/agents/usage` | Agent operating rules and prompts | | `@pagesmith/docs/agents/recipes` | Task-specific recipes | | `@pagesmith/docs/agents/changelog-notes` | Version highlights for agents | | `@pagesmith/docs/agents/errors` | Error catalog for agent workflows | | `@pagesmith/docs/agents/migration` | Upgrade playbook for existing integrations | | `@pagesmith/docs/agents/template` | Project memory template | ## GitHub Pages Deployment Create `.github/workflows/gh-pages.yml`: ```yaml name: Deploy Docs on: push: branches: [main] permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 24 - run: npm ci - run: npx pagesmith-docs build - uses: actions/upload-pages-artifact@v5 with: path: gh-pages deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - id: deployment uses: actions/deploy-pages@v5 ``` ## When Adding New Pages 1. Create `/

//README.md` with title and description frontmatter 2. Add the slug to the section's `meta.json5` `items` array 3. Write content following the markdown guidelines below 4. Run `npx pagesmith-docs dev` to verify rendering ## Markdown Guidelines The markdown pipeline processes content through unified with these plugins in order: ``` remark-parse → remark-gfm → remark-frontmatter → remark-github-alerts → remark-smartypants → remark-math (when `markdown.math` is `true` or `'auto'` detects math markers) → [custom remark plugins in lower-level integrations] → lang-alias transform → remark-rehype → rehype-mathjax (when math is enabled, before the built-in code renderer) → applyPagesmithCodeRenderer (dual themes, line numbers, titles, copy, collapse, mark/ins/del) → rehype-code-tabs → rehype-scrollable-tables → rehype-slug → rehype-autolink-headings → rehype-external-links → rehype-accessible-emojis → rehype-local-images → heading extraction → docs link/asset transforms → rehype-stringify ``` In `pagesmith.config.json5`, the `markdown` field is intentionally JSON-safe: - `allowDangerousHtml?: boolean` - `math?: boolean | 'auto'` - `shiki.themes`, `shiki.langAlias`, `shiki.defaultShowLineNumbers` Function-based `remarkPlugins` and `rehypePlugins` remain available through the lower-level `@pagesmith/core` APIs, not through the JSON5 docs config. When stock docs rendering knows the markdown source path, relative local images inherit intrinsic dimensions automatically and relative JPEGs can emit `