<!-- pagesmith-ai:shared-llms-full:start -->
# Pagesmith — Full LLM Reference

Pagesmith is a filesystem-first content toolkit with two main packages: `@pagesmith/core` (shared content/runtime layer) and `@pagesmith/docs` (convention-based documentation).

Use Pagesmith when you need:
- schema-validated content collections loaded from the filesystem
- lazy markdown rendering with headings and read-time metadata
- framework-agnostic content APIs for React, Solid, Svelte, vanilla JS, Node, Bun, or Deno

Core APIs:
- `defineCollection({...})` to define a typed collection
- `defineConfig({...})` to group collections and markdown options
- `createContentLayer(config)` to query content and run validation
- `entry.render()` to convert markdown on demand

Working rules:
- prefer folder-based markdown entries when content references sibling assets
- follow the markdown guidelines in `.pagesmith/markdown-guidelines.md` when authoring content
- use fenced code blocks with a language identifier, one h1 per page, sequential heading depth

---

## @pagesmith/core

### Content Layer API

| Method | Description |
|---|---|
| `createContentLayer(config)` | Create a content layer |
| `layer.getCollection(name)` | Load all entries (cached) |
| `layer.getEntry(collection, slug)` | Get single entry by slug |
| `layer.convert(markdown, options?)` | Convert raw markdown to HTML |
| `layer.validate(collection?)` | Run all validators |
| `layer.invalidate(collection, slug)` | Cache-bust a single entry |
| `layer.invalidateAll()` | Cache-bust all collections |

### Collection Options

| Option | Type | Description |
|---|---|---|
| `loader` | `string \| Loader` | `'markdown'`, `'json'`, `'json5'`, `'jsonc'`, `'yaml'`, `'toml'`, or custom |
| `directory` | `string` | Directory containing files |
| `schema` | `z.ZodType` | Zod schema for validation |
| `include` | `string[]` | Glob include patterns |
| `exclude` | `string[]` | Glob exclude patterns |
| `computed` | `Record<string, fn>` | Computed fields |
| `validate` | `fn` | Custom validation |
| `filter` | `fn` | Filter entries |
| `slugify` | `fn` | Custom slug generation |
| `transform` | `fn` | Pre-validation transform |
| `validators` | `ContentValidator[]` | Custom content validators |
| `disableBuiltinValidators` | `boolean` | Disable link/heading/code-block validators |

### Vite Plugins

```ts
import { createContentLayer, defineCollection, defineConfig, z } from '@pagesmith/core'

const posts = defineCollection({
  loader: 'markdown',
  directory: 'content/posts',
  schema: z.object({
    title: z.string(),
    description: z.string().optional(),
    date: z.coerce.date(),
    tags: z.array(z.string()).default([]),
  }),
})

const layer = createContentLayer(
  defineConfig({
    collections: { posts },
  }),
)

const entries = await layer.getCollection('posts')
const rendered = await entries[0]?.render()
```

```ts
// Vite integration
import { pagesmithContent, pagesmithSsg, sharedAssetsPlugin } from '@pagesmith/core/vite'
import collections from './content.config'

export default defineConfig({
  plugins: [
    sharedAssetsPlugin(),
    pagesmithContent({ collections }),
    ...pagesmithSsg({ entry: './src/entry-server.tsx', contentDirs: ['./content'] }),
  ],
})
```

### JSX Runtime

Configure tsconfig: `{ "jsx": "react-jsx", "jsxImportSource": "@pagesmith/core" }`

- `h(tag, props, ...children)` — create HTML elements, returns `HtmlString`
- `Fragment` — render children or raw `innerHTML`
- `HtmlString` — wrapper to prevent double-escaping

### CSS Exports

| Import | Contents |
|---|---|
| `@pagesmith/core/css/content` | Prose + inline code |
| `@pagesmith/core/css/standalone` | Full layout + prose + TOC |
| `@pagesmith/core/css/viewport` | Responsive viewport base |
| `@pagesmith/core/css/fonts` | Bundled Open Sans + JetBrains Mono |

### Frontmatter Schemas

- `BaseFrontmatterSchema` — title, description, publishedDate, lastUpdatedOn, tags, draft
- `BlogFrontmatterSchema` — extends base + category, featured, coverImage
- `ProjectFrontmatterSchema` — extends base + gitRepo, links

### Export Map

| Import Path | Purpose |
|---|---|
| `@pagesmith/core` | Main API (defineCollection, createContentLayer, z, etc.) |
| `@pagesmith/core/jsx-runtime` | h, Fragment, HtmlString |
| `@pagesmith/core/markdown` | processMarkdown |
| `@pagesmith/core/css` | buildCss (LightningCSS) |
| `@pagesmith/core/schemas` | Zod schemas and types |
| `@pagesmith/core/loaders` | Loader classes and registry |
| `@pagesmith/core/runtime` | Pre-built CSS/JS accessors |
| `@pagesmith/core/vite` | Vite plugins |
| `@pagesmith/core/mcp` | MCP server for AI agents |

---

## @pagesmith/docs

### Configuration (pagesmith.config.json5)

| Field | Type | Default | Description |
|---|---|---|---|
| `name` | `string` | — | Site name (header) |
| `title` | `string` | — | Browser tab title |
| `description` | `string` | — | Meta description |
| `origin` | `string` | — | Production URL |
| `language` | `string` | `en` | HTML lang |
| `contentDir` | `string` | `content` | Content path |
| `outDir` | `string` | `dist` | Output path |
| `basePath` | `string` | `/` | URL base |
| `maintainer` | `object` | `package.json author` | Maintainer credit for the default footer sign-off |
| `footerLinks` | `array` | `top-level nav links` | Footer links as a flat row or grouped columns |
| `copyright` | `object` | — | Footer legal line config (`projectName`, `startYear`, `endYear`) |
| `sidebar.collapsible` | `boolean` | `true` | Collapsible sidebar |
| `search.enabled` | `boolean` | `true` | Pagefind search |
| `theme.layouts` | `Record` | — | Layout overrides |
| `editLink` | `object \| false` | `auto-detected` | Edit link config or explicit disable |
| `lastUpdated` | `boolean` | `true` | Git-based page timestamps |
| `markdown` | `MarkdownConfig` | — | Pipeline config |

### Content Structure

```json5
// pagesmith.config.json5
{
  $schema: './node_modules/@pagesmith/docs/schemas/pagesmith-config.schema.json',
  name: 'Acme Docs',
  title: 'Acme Docs',
  origin: 'https://acme.github.io',
  basePath: '/acme-docs',
  description: 'Multi-package documentation',
  contentDir: './content',
  outDir: './gh-pages',
  maintainer: {
    name: 'Sujeet Jaiswal',
    link: 'https://sujeet.pro',
  },
  copyright: {
    projectName: 'Acme Docs',
    startYear: 2024,
    endYear: null,
  },
  footerLinks: [
    {
      header: 'Docs',
      links: [
        { label: 'Guide', path: '/guide' },
        { label: 'Reference', path: '/reference' },
      ],
    },
  ],
  editLink: {
    repo: 'https://github.com/acme/docs',
  },
  search: { enabled: true },
}
```

```text
content/
  README.md                 # Home page (DocHome layout)
  guide/
    meta.json5              # Section ordering
    getting-started/
      README.md             # A page
  reference/
    api/README.md
```

### Page Frontmatter

| Field | Type | Description |
|---|---|---|
| `title` | `string` | Page title |
| `description` | `string` | Meta description |
| `navLabel` | `string` | Override top nav label |
| `sidebarLabel` | `string` | Override sidebar label |
| `order` | `number` | Manual sort order |
| `draft` | `boolean` | Exclude from build |

### Home Page Frontmatter

| Field | Type | Description |
|---|---|---|
| `layout` | `string` | Set to `DocHome` |
| `tagline` | `string` | Short description |
| `install` | `string` | Install command |
| `actions` | `array` | CTA buttons (`{ text, link, theme: 'brand' \| 'alt' }`) |
| `features` | `array` | Feature cards (`{ icon?, title, details }`) |
| `packages` | `array` | Package cards (`{ name, description, href, tag }`) |
| `codeExample` | `object` | Code example (`{ label, title, code }`) |

### Section Meta (meta.json5)

| Field | Type | Description |
|---|---|---|
| `displayName` | `string` | Section label in sidebar |
| `items` | `string[]` | Manual page order (slugs) |
| `series` | `array` | Group pages into series |
| `collapsed` | `boolean` | Start sidebar collapsed |
| `orderBy` | `string` | `manual` or `publishedDate` |

### Layout Overrides

```json5
{ theme: { layouts: { home: "./layouts/Home.tsx", page: "./layouts/Page.tsx" } } }
```

All layouts receive: `content`, `frontmatter`, `headings`, `slug`, `site`.
Page layout adds: `sidebarSections`, `prev`, `next`.

### CLI

```bash
pagesmith init [--ai] [--config path]   # Initialize project
pagesmith dev [--port N] [--open]        # Dev server
pagesmith build [--out-dir path]         # Production build
pagesmith preview [--port N]             # Preview built site
```

---

## Markdown Pipeline

# Pagesmith Markdown Guidelines

Markdown feature support for content authored with `@pagesmith/core` and `@pagesmith/docs`.

## Pipeline Order

```
remark-parse → remark-gfm → remark-frontmatter
  → remark-github-alerts → remark-smartypants → remark-math (when `markdown.math` is enabled or auto-detected) → [user remark plugins]
  → remark-rehype
  → rehype-mathjax (when math is enabled)
  → 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
  → heading extraction → [user rehype plugins] → rehype-stringify
```

## Key Rules

- Use fenced code blocks with a language identifier (validator warns otherwise)
- One `# h1` per page (validator enforces)
- Sequential heading depth (no skipping from h2 to h4)
- Prefer relative links for internal content
- `allowDangerousHtml` defaults to `true`; disable it when rendering untrusted markdown
- `math` defaults to `'auto'`; Pagesmith only enables the math plugins when the page contains math markers
- Do NOT add manual copy-button JS inside markdown content — the built-in renderer injects its own copy/collapse runtime
- Include the shipped Pagesmith markdown CSS so code block chrome and tabs render correctly

## Supported Features

| Feature | Syntax | Notes |
|---|---|---|
| GFM tables | `\| col \| col \|` | Alignment via `:---`, `:---:`, `---:` |
| Strikethrough | `~~text~~` | |
| Task lists | `- [x] done` / `- [ ] todo` | |
| Footnotes | `[^id]` + `[^id]: text` | |
| Alerts | `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]` | GitHub-compatible |
| Inline math | `$E = mc^2$` | No spaces inside delimiters |
| Block math | `$$...$$` | Rendered via MathJax |
| Smart quotes | `"text"` → curly quotes | Automatic |
| Em/en dash | `---` / `--` | Automatic |
| External links | `[text](https://...)` | Auto `target="_blank"` |
| Heading anchors | Auto `id` + wrapped anchor | All headings |
| Accessible emoji | Unicode emoji | Auto `role="img"` + `aria-label` |

## Code Block Features (Built-in Renderer)

| Meta | Example | Description |
|---|---|---|
| `title="..."` | `` ```js title="app.js" `` | File title |
| `showLineNumbers` | `` ```js showLineNumbers `` | Line numbers |
| `mark={lines}` | `` ```js mark={3,5-7} `` | Highlight lines |
| `ins={lines}` | `` ```js ins={4} `` | Inserted lines (green) |
| `del={lines}` | `` ```js del={5} `` | Deleted lines (red) |
| `collapse={lines}` | `` ```js collapse={1-5} `` | Collapsible section |
| `wrap` | `` ```js wrap `` | Text wrapping |
| `frame="..."` | `` ```js frame="terminal" `` | Frame style |

## Built-in Content Validators

- **linkValidator** — warns on bare URLs, empty link text, suspicious protocols
- **headingValidator** — enforces single h1, sequential depth, non-empty text
- **codeBlockValidator** — warns on missing language, unknown meta properties

Known valid meta properties: `title`, `showLineNumbers`, `startLineNumber`, `wrap`, `frame`, `collapse`, `mark`, `ins`, `del`.

---

## AI Setup

```bash
npx pagesmith init --ai
```

Generates CLAUDE.md, AGENTS.md, GEMINI.md, skills, markdown guidelines, llms.txt, and llms-full.txt.
<!-- pagesmith-ai:shared-llms-full:end -->