Getting Started with @pagesmith/docs

@pagesmith/docs is a convention-based documentation site builder. It turns a directory of markdown files — with optional JSON5 config when you need overrides — into a complete docs site with navigation, sidebar, table of contents, Pagefind search, and a default theme — all without writing any JavaScript or layout code.

This guide covers everything you need to go from an empty project to a running docs site.

Follow the arrows left to right: install pulls in core, init lays down config and content, and your scripts drive dev, build, and search indexing.

AI-First Setup

Paste this into your AI assistant when you want it to retrofit docs into an existing repo or create a fresh docs section with the right Pagesmith structure:

Set up docs using Pagesmith for this repository. Read https://projects.sujeet.pro/pagesmith/prompts/setup-docs.md first and follow it exactly. Use npx pagesmith-docs init --yes --ai for bootstrap work and keep pagesmith.config.json5 at the repo root.

If @pagesmith/docs is already installed and you want the version-matched local file instead of the hosted one:

Set up docs using Pagesmith for this repository. Read node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/setup-docs.md first and follow it exactly.

If you want full copy-paste prompt bodies for both initial setup and upgrades, use Agent Prompts Cookbook. That page includes the repo-configuration prompt plus the upgrade prompt for an existing @pagesmith/docs integration.

Your agent will create:

• pagesmith.config.json5 — site configuration, including a $schema pointer to the installed package schema
• a chosen docs folder (docs/ by default, or an existing docs-like folder after confirmation)
• starter guide/ and reference/ sections with meta.json5 and README.md pages
• root package.json scripts: docs:dev, docs:build, docs:preview
• AI context files and markdown guidelines
• CLAUDE.md / AGENTS.md pointers to the package guidance, setup prompt, and schema files
• Claude skills for docs maintenance (/update-docs, /ps-update-all-docs) when AI artifacts are installed

When the repo has a GitHub remote, the setup flow defaults to GitHub Pages:

• basePath defaults to /<repo-name>
• origin starts from https://<owner>.github.io and uses the resolved host if that URL redirects
• if you want root-hosted docs instead, edit pagesmith.config.json5 manually after setup

The rest of this guide explains each piece in detail for manual setup or customization.

Install

1npm add @pagesmith/docs

This is the only Pagesmith package you need for the docs workflow. You do not need to install @pagesmith/core or @pagesmith/site separately when using @pagesmith/docs.

After installation, the canonical docs CLI is available as npx pagesmith-docs. The package also exposes @pagesmith/docs/preset for pagesmith-site, but docs projects should prefer pagesmith-docs.

Quick Init

The fastest non-interactive setup flow is:

1npx pagesmith-docs init --yes --ai

For an agent or scriptable workflow, pass explicit values:

1npx pagesmith-docs init --yes --ai --content-dir docs --base-path /my-repo --origin https://my-user.github.io

If https://my-user.github.io redirects to a custom host, use the redirected origin. If you want the docs site hosted at the root instead of /<repo-name>, edit pagesmith.config.json5 manually after init.

It is safe to rerun pagesmith-docs init later. The command updates pagesmith.config.json5 to add missing scaffold fields and refresh the $schema path instead of skipping the file outright.

Create a Configuration File

If your repository already follows the default conventions, pagesmith-docs dev, pagesmith-docs build, pagesmith-docs preview, and pagesmith-docs mcp --stdio work without a config file at all. In zero-config mode, Pagesmith uses <repo-root>/docs when it exists, falls back to <repo-root>/content, and writes the build to <repo-root>/gh-pages.

Add pagesmith.config.json5 at the project root when you want to override those defaults:

1{2  $schema: "./node_modules/@pagesmith/docs/schemas/pagesmith-config.schema.json",3  // Required: site identity4  name: "My Docs",5  title: "My Docs",6  description: "Documentation for my project",7  origin: "https://docs.example.com",89  // Optional: content and output paths10  contentDir: "./docs",11  outDir: "./gh-pages",1213  // Optional: deployment under a subdirectory14  basePath: "/docs",1516  // Optional: footer attribution17  maintainer: {18    name: "Sujeet Jaiswal",19    link: "https://sujeet.pro",20  },2122  // Optional: footer copyright23  copyright: {24    projectName: "Acme Docs",25    startYear: 2024,26    endYear: null,27  },2829  // Optional: footer navigation30  footerLinks: [31    {32      header: "Docs",33      links: [34        { label: "Guide", path: "/guide" },35        { label: "API Reference", path: "/reference" },36      ],37    },38    {39      header: "Project",40      links: [{ label: "GitHub", path: "https://github.com/example/repo" }],41    },42  ],4344  // Optional: search (enabled by default)45  search: {46    enabled: true,47  },48}

Configuration Fields

Content Directory Structure

The content directory is the source of truth for your docs site. Top-level folders become navigation sections, and each markdown file inside one of those folders becomes a page for that section.

1content/2  README.md              # Home page (the site landing page)3  guide/4    README.md            # "Guide" section landing page5    meta.json5           # Section configuration (optional)6    getting-started/7      README.md          # /guide/getting-started8    advanced-usage/9      README.md          # /guide/advanced-usage10  reference/11    README.md            # "Reference" section landing page12    meta.json5           # Section configuration (optional)13    api/14      README.md          # /reference/api15    docs-cli/16      README.md          # /reference/docs-cli

Key conventions:

• content/README.md is always the home page, rendered at /.
• Top-level folders (e.g. guide/, reference/) define the docs sections. By default they appear in the header; use headerLinks in meta.json5 to control which sections are shown.
• README.md inside a section folder is the section landing page (e.g. guide/README.md serves /guide).
• Markdown files inside a section become pages even when nested. Nested folders keep their URL paths, but the section sidebar stays flat from the docs reader’s perspective.
• meta.json5 series group pages into sidebar buckets. Pages not referenced by any series stay visible under an automatic Miscellaneous group.
• Files and folders starting with . or _ are ignored.
• Files with draft: true in frontmatter are excluded from the build.

README.md Files as Pages

The docs system uses README.md as the entry file for each page. This is intentional: it mirrors how GitHub renders folder READMEs, so your content reads well both on the rendered site and when browsing the repository directly.

A simple page looks like:

1# Page Title23Your content here. The first `h1` heading is used as the page title4if no `title` frontmatter is provided.

Frontmatter Options

Frontmatter is optional. When provided, it is written in YAML between --- fences at the top of the markdown file.

1---2title: Getting Started3description: Learn how to set up your first docs site.4navLabel: Start Here5sidebarLabel: Quick Start6order: 17draft: false8---

Additional frontmatter fields are passed through to layout components, so you can define custom fields and access them in layout overrides.

Home Page Setup

The root content/README.md is rendered using the home layout. It supports special frontmatter fields to build a hero section and features grid without writing HTML.

1---2title: My Project3tagline: The Best Documentation Tool4description: Build beautiful docs sites with zero configuration.5actions:6  - text: Get Started7    link: /guide/getting-started8    theme: brand9  - text: View on GitHub10    link: https://github.com/example/repo11    theme: alt12features:13  - title: Fast Setup14    details: Go from zero to a published docs site in under five minutes.15  - title: Built-in Search16    details: Full-text search powered by Pagefind, no configuration needed.17  - title: Markdown First18    details: Write in markdown, get a polished site with navigation and TOC.19---20## Additional Content2122Any markdown below the frontmatter is rendered in a content section below the hero and features.

Hero Fields

The home layout builds the hero from frontmatter. You can either use the top-level convenience fields (title, tagline, description, actions) or provide an explicit hero object:

1---2hero:3  name: My Project4  text: The documentation framework5  tagline: Convention over configuration6  actions:7    - text: Quick Start8      link: /guide9      theme: brand10---

Each action in the actions array has:

• text — the button label
• link — the URL (internal path or external URL)
• theme — visual style, either "brand" (primary color) or "alt" (secondary style)

Features Fields

The features array renders a card grid below the hero:

1features:2  - title: Feature Name3    icon: "rocket symbol or emoji"4    details: A short description of the feature.

Each feature has title (required), details (required), and an optional icon string.

Running the Dev Server

Start the development server with live reload:

1npx pagesmith-docs dev

The dev server defaults to port 3000. Use --port to change it:

1npx pagesmith-docs dev --port 8080

Use --open to automatically open the site in your default browser:

1npx pagesmith-docs dev --open

The dev server watches the content directory and rebuilds pages on change. A WebSocket connection triggers automatic browser reload when content is updated.

Building for Production

Build a static site:

1npx pagesmith-docs build

The output goes to the configured outDir (default gh-pages/). The build:

1. Processes all markdown files through the markdown pipeline
2. Renders each page using the appropriate layout
3. Bundles the theme CSS and runtime JavaScript
4. Copies static assets from publicDir
5. Runs Pagefind to generate the search index (if search is enabled)

Override the output directory or base path from the CLI:

1npx pagesmith-docs build --out-dir ./public --base-path /my-docs

Previewing the Build

Preview the built site locally:

1npx pagesmith-docs preview

This starts a static file server pointing at the output directory. Use --port to change the default port (4000):

1npx pagesmith-docs preview --port 5000

CLI Reference

1pagesmith-docs dev [options]       Start a docs dev server2pagesmith-docs build [options]     Build a docs site3pagesmith-docs preview [options]   Preview the built docs site45Options:6  -p, --port <number>         Server port (dev: 3000, preview: 4000)7  --open                      Open browser on server start8  --out-dir <path>            Output directory (overrides config)9  --base-path <path>          Base URL path prefix (overrides config)10  --log-level <level>         Log level: silent|error|warn|info|verbose (default: warn)11  --config <path>             Config file path (default: pagesmith.config.json5)

Package Scripts

A typical package.json setup:

1{2  "scripts": {3    "docs:dev": "pagesmith-docs dev",4    "docs:build": "pagesmith-docs build",5    "docs:preview": "pagesmith-docs preview"6  },7  "dependencies": {8    "@pagesmith/docs": "^0.8.0"9  }10}

Search

Pagefind full-text search is enabled by default. It indexes your content during pagesmith-docs build and provides a search modal triggered by Cmd+K / Ctrl+K.

To disable search:

1{2  search: { enabled: false },3}

Search works automatically with no additional configuration. The search index is regenerated on every build.

What to Read Next

• Meta and Navigation — control sidebar ordering, series grouping, and header links
• Layout Overrides — replace built-in layouts with custom components