Doc Site with @pagesmith/docs

Overview

The Doc Site pattern is the high-level Pagesmith docs workflow. Instead of wiring collections, JSX chrome, and SSG by hand, you install @pagesmith/docs, point it at a docs content directory, and let the preset handle navigation, the default theme, Pagefind search, and the build pipeline.

That means:

• the docs preset owns page discovery, sidebar generation, and search wiring
• you write markdown in a docs tree plus a pagesmith.config.json5
• optional layout overrides stay on @pagesmith/docs via @pagesmith/docs/jsx-runtime
• the example can stay focused on docs content and a couple of custom layouts

Source: examples/doc-site/ | Output: Live Demo

The diagram below highlights the boundary: your project supplies content, config, and optional overrides, while @pagesmith/docs owns the docs-specific runtime and generation pipeline.

Prerequisites

• Node.js 24+

Project Setup

package.json

The example depends only on @pagesmith/docs. Because this repo builds the workspace package directly, the scripts call the local CLI entrypoint; in an installed project you would use pagesmith-docs ... instead.

1{2  "name": "@pagesmith/example-doc-site",3  "private": true,4  "type": "module",5  "scripts": {6    "dev": "node ../../packages/docs/dist/cli/bin.mjs dev --config ./pagesmith.config.json5",7    "build": "node ../../packages/docs/dist/cli/bin.mjs build --config ./pagesmith.config.json5",8    "check": "tsc --noEmit"9  },10  "dependencies": {11    "@pagesmith/docs": "*"12  },13  "devDependencies": {14    "typescript": "^6.0.2"15  }16}

For a standalone project after installation, the equivalent commands are simply pagesmith-docs dev --config ./pagesmith.config.json5 and pagesmith-docs build --config ./pagesmith.config.json5.

Project Structure

1doc-site/2  pagesmith.config.json53  content/4    README.md                # Home page5    guide/6      meta.json5             # Section metadata and series7      installation.md8      project-structure.md9      content-collections.md10      layouts-and-rendering.md11      configuration.md12      search-integration.md13      kitchen-sink.md14    pages/15      about.md16  theme/17    layouts/18      DocHome.tsx            # Home layout override19      DocPage.tsx            # Inner-page layout override20      shared.tsx             # Shared helpers/components for the overrides21  public/22    favicon.svg23  package.json

This example intentionally uses an explicit content/ directory. In zero-config repos, @pagesmith/docs prefers docs/ when that folder exists and falls back to content/ otherwise.

pagesmith.config.json5

The example is configured entirely through pagesmith.config.json5. This excerpt shows the main knobs:

1{2  $schema: "../../node_modules/@pagesmith/docs/schemas/pagesmith-config.schema.json",3  preset: "@pagesmith/docs",4  name: "Pagesmith",5  title: "Example Docs",6  description: "Documentation site built with @pagesmith/docs",7  origin: "https://projects.sujeet.pro",8  contentDir: "./content",9  outDir: "../../gh-pages/examples/doc-site",10  basePath: "/pagesmith/examples/doc-site",11  homeLink: "/pagesmith",12  maintainer: {13    name: "Sujeet Jaiswal",14    link: "https://sujeet.pro",15  },16  copyright: {17    projectName: "Example Docs",18    startYear: 2024,19    endYear: null,20  },21  sidebar: { collapsible: true },22  theme: {23    defaultColorScheme: "auto",24    defaultTheme: "paper",25    layouts: {26      home: "./theme/layouts/DocHome.tsx",27      page: "./theme/layouts/DocPage.tsx",28    },29  },30  footerLinks: [31    {32      header: "Guide",33      links: [34        { label: "Installation", path: "/guide/installation" },35        { label: "Configuration", path: "/guide/configuration" },36      ],37    },38  ],39  editLink: {40    repo: "https://github.com/sujeet-pro/pagesmith",41    branch: "main",42    label: "Edit this page",43  },44  lastUpdated: true,45  search: {46    enabled: true,47    showImages: false,48    showSubResults: true,49  },50}

Key points from the example:

• contentDir is explicit here, but @pagesmith/docs can also run zero-config when docs/ or content/ follows the standard layout
• theme.layouts overrides only the home and page layouts; the rest of the docs preset stays intact
• search.enabled turns on Pagefind without any extra plugin wiring
• the monorepo example builds into ../../gh-pages/examples/doc-site, while a standalone docs site would typically build into gh-pages

Content Structure and Navigation

Top-level folders under content/ become sections. This example keeps one primary guide section plus a small pages/ section for standalone pages.

content/guide/meta.json5 uses the current series-based structure:

1{2  displayName: "Guide",3  orderBy: "manual",4  series: [5    {6      slug: "getting-started",7      displayName: "Getting Started",8      articles: ["installation", "project-structure", "content-collections"],9    },10    {11      slug: "customization",12      displayName: "Customization",13      articles: ["layouts-and-rendering", "configuration", "search-integration"],14    },15    {16      slug: "markdown-showcase",17      displayName: "Markdown Showcase",18      articles: ["kitchen-sink"],19    },20  ],21}

That is the important convention to copy from the example: current docs projects use series groups, not the older flat items: [...]-only pattern shown in some pre-refresh docs.

Layout Overrides

Layout overrides stay on the docs package surface. The example uses @pagesmith/docs/jsx-runtime and reuses the shared docs shell pieces instead of reimplementing everything from scratch.

1import { h } from "@pagesmith/docs/jsx-runtime";2import { Html } from "@pagesmith/docs/theme";

theme/layouts/DocHome.tsx maps the home page frontmatter (hero, features, packages, install, codeExample) onto the stock docs home structure. theme/layouts/DocPage.tsx keeps the expected article landmarks such as:

• data-pagefind-body on the article content
• the shared docs header/sidebar/footer components
• mobile and desktop table-of-contents regions
• prev/next and edit-link props that @pagesmith/docs resolves for you

If you want to customize layout behavior, prefer composing @pagesmith/docs/theme, @pagesmith/docs/components, and @pagesmith/docs/layouts instead of cloning the whole preset.

Search and Runtime

Pagefind is built in. This example only configures it in pagesmith.config.json5:

1{2  search: {3    enabled: true,4    showImages: false,5    showSubResults: true,6  },7}

When search is enabled, @pagesmith/docs handles:

1. indexing during the build
2. shipping the Pagefind web component assets
3. rendering the modal markup in the document shell
4. wiring the trigger and keyboard shortcuts through the shared standalone runtime

Running The Example

From the repo root:

1vp install2vp run dev:eg:doc-site

Inside the example directory, the local scripts are:

1node ../../packages/docs/dist/cli/bin.mjs dev --config ./pagesmith.config.json52node ../../packages/docs/dist/cli/bin.mjs build --config ./pagesmith.config.json5

In a published project with @pagesmith/docs installed, the same workflow becomes:

1pagesmith-docs dev --config ./pagesmith.config.json52pagesmith-docs build --config ./pagesmith.config.json53pagesmith-docs preview --config ./pagesmith.config.json5

When To Use This Shape

Choose this pattern when:

• you want a convention-based docs site with minimal app code
• you want navigation, Pagefind, and the docs theme handled for you
• you still want the option to override layouts without leaving the docs package surface

If you need a fully custom site shell, step down to @pagesmith/site. If your framework already owns the entire shell and you only want the headless content layer, use a lower-level @pagesmith/core or framework-hosted @pagesmith/site integration instead.