Skip to content
✨ Publier v1 is live — a polished docs platform built for the open web.
On this page

Content authoring

Write documentation in MDX — frontmatter, callouts, code blocks, components, tabs, and sidebar ordering.

Publier uses Astro’s MDX pipeline. Keep the scaffold’s integrations, or follow configuration when wiring an existing project. Optional snippets and diagrams have the setup described below.

Frontmatter

Every .mdx file in src/content/docs/ starts with a YAML frontmatter block:

src/content/docs/my-page.mdx
---
title: Introduction
description: A short summary shown in search results and the <head>.
tags: [getting-started]
order: 10
---


Page content here.
  • title (required) — shown in the sidebar, <title> tag, and search results.
  • description — used in <meta name="description"> and the OpenGraph card.
  • tags / order — for filtering and sidebar position.
  • draft: true — hides the page from the sidebar and static build.

Set page order with sidebar.order in frontmatter. For section labels and order in the default docs route, configure:

publier.config.yaml
docs:
  sidebar:
    meta:
      guides: { label: Guides, order: 20 }

Section keys are content-folder paths. A custom route can use the exported readMetaYaml() helper to read folder files and pass metadata to buildSidebar(). The default route does not read those files automatically. See configuration.

Callouts

Directive shorthand — no imports needed:

:::note
A neutral informational note.
:::


:::tip[Pro tip]
A helpful suggestion with a custom title.
:::


:::caution
Heads up — this may cause surprising behavior.
:::


:::danger
Destructive action ahead.
:::

Code blocks

The scaffold registers astro-expressive-code explicitly. Keep it after docsShell() and before MDX. Tag fences with a language and optional metadata:

```ts title="example.ts" {2,5-7} ins="new" del="old"
import { foo } from './foo';
const value = new Thing();
// ... lines 5-7 highlighted
```

Supported metadata: title, line ranges {2,5-7}, ins=, del=, showLineNumbers.

Tabs, cards, steps

Layout and prose primitives come from @publier/shell/components. Interactive primitives (Accordion, Tabs, Tooltip) come from @publier/primitives:

import { Card, CardGrid, Steps, Badge } from '@publier/shell/components';
import { Tabs, TabPanel, Accordion, AccordionItem } from '@publier/primitives';


<Tabs labels={["install", "dev"]}>
  <TabPanel>`pnpm add @publier/shell`</TabPanel>
  <TabPanel>`publier dev`</TabPanel>
</Tabs>


<Steps>
  <li>Install the package.</li>
  <li>Import a component.</li>
  <li>Use it in MDX.</li>
</Steps>


<CardGrid>
  <Card title="Zero JS">Most components are native HTML + CSS — no hydration overhead.</Card>
  <Card title="Typed">Every component ships full TypeScript types.</Card>
</CardGrid>

See Components for the full list.

Snippets

Reuse MDX fragments across pages. Put shared content in src/content/snippets/:

<Snippet file="install.mdx" package="@publier/shell" />

{{propName}} placeholders in the snippet are substituted with the attribute values. Enable snippets in astro.config.ts:

astro.config.ts
docsShell({ snippets: { directory: 'src/content/snippets' } })

See the Snippet component reference for the full surface.

Mermaid diagrams

Install the peer deps once — Publier auto-detects them:

Terminal window
pnpm add astro-mermaid mermaid

Then drop a fenced mermaid block in any MDX file:

```mermaid
graph TD
  A[Write MDX] --> B[Run publier dev]
  B --> C[Site renders]
```

Dark/light theme follows your ThemeToggle automatically.

Math equations

Enable via docsShell({ math: true }) and install the peer deps:

Terminal window
pnpm add remark-math rehype-katex katex

Then write inline or block math:

Inline: $E = mc^2$


Block:
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Site-wide search is powered by Pagefind. After every build, the scanner crawls dist/**/*.html and emits a static, WASM-backed index at dist/pagefind/. docsShell() auto-wires the ⌘K dialog — no extra config.

To opt out:

astro.config.ts
docsShell({ search: false })

To exclude a specific element from the index, add data-pagefind-ignore to it. See content and search maintenance for built-index checks and troubleshooting.