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

Content authoring

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

Publier uses Astro’s MDX pipeline and wires every required remark/rehype plugin automatically. Everything below works out of the box.

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.

Drop a meta.yaml into any subdirectory of src/content/docs/ to control its sidebar entry:

src/content/docs/guides/meta.yaml
title: Guides
order: 20

order sorts sibling sections; pages within a section are sorted by their own order frontmatter.

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

astro-expressive-code is bundled automatically. 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>
  1. Install the package.
  2. Import a component.
  3. Use it in MDX.
</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.