Configuration

Reference for astro.config.ts, publier.config.yaml, theme.yaml, and meta.yaml.

Publier uses three configuration files. Most projects only need the first two.

File	What it controls	Required
`astro.config.ts`	Astro integrations and Vite plugins	✓
`publier.config.yaml`	Site name, nav, search, analytics, fonts, snippets	—
`theme.yaml`	Color preset + brand overrides	—
`meta.yaml` (per folder)	Sidebar label and order for a content directory	—

`astro.config.ts`

A single integration call wires the full Publier pipeline — MDX, Qwik, Tailwind, theme tokens, syntax highlighting, callouts, and Mermaid auto-detection:

import { defineConfig } from 'astro/config';
import tailwind from '@tailwindcss/vite';
import { docsShell } from '@publier/shell/integration';

export default defineConfig({
  integrations: [docsShell()],
  vite: { plugins: [tailwind()] },
});

You do not need to list mdx() or qwik() yourself — Publier adds them when missing and skips them when you add them explicitly. Your declaration always wins.

Auto-wired by `docsShell()`

Every auto-wire is idempotent — Publier detects existing config and backs off.

Disableable defaults (on by default):

Auto-wire	Disable	Skipped when
`@astrojs/mdx`	`docsShell({ mdx: false })`	already in `integrations[]`
`astro-expressive-code`	`docsShell({ expressiveCode: false })`	already in `integrations[]`
`astro-mermaid` (auto-detected)	`docsShell({ mermaid: false })`	already in `integrations[]` or not installed
`prefetch` (prefetchAll + viewport)	`docsShell({ prefetch: false })`	`astro.config.ts` already sets `prefetch:`
`rehype-autolink-headings`	`docsShell({ autolinkHeadings: false })`	—

Opt-in features (off by default):

Feature	Enable	Peer deps
Math (KaTeX)	`docsShell({ math: true })`	`remark-math`, `rehype-katex`, `katex`
Snippets	`docsShell({ snippets: { directory: 'src/content/snippets' } })`	—

Driven by publier.config.yaml (inert when the key is absent):

vars: — expands {{var}} placeholders inside MDX text.
fonts: — emits Google Fonts links or @font-face blocks plus --font-sans / --font-serif / --font-mono overrides.
analytics: — injects provider snippets (GA4, PostHog, Plausible, Fathom, Umami) into <head>.
sidebar.hidden: true in page frontmatter — excludes the page from the auto-generated sidebar.

Ordering

Astro runs integrations in array order. Publier’s auto-adds run after your declared integrations, so your hooks always see content first. Markdown plugin arrays are concatenated — Publier’s plugins run after yours.

`src/content.config.ts`

import { defineCollection } from 'astro:content';
import { docsLoader, blogLoader, contentLoader } from '@publier/shell/loaders';
import { docsSchema, blogSchema, changelogSchema } from '@publier/shell/schemas';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  blog: defineCollection({ loader: blogLoader(), schema: blogSchema }),
  changelog: defineCollection({
    loader: contentLoader({ base: './src/content/changelog' }),
    schema: changelogSchema,
  }),
};

`publier.config.yaml`

Project-root YAML file. Missing or invalid → Publier logs a warning and uses defaults.

name: My Docs                       # site name (OG images, RSS, meta tags)
url: https://docs.example.com       # canonical URL for sitemaps

nav:
  links:
    - label: GitHub
      href: https://github.com/my-org/my-docs
      external: true

snippets:
  directory: src/content/snippets   # reusable MDX fragments

search:
  enabled: true                     # show the ⌘K dialog

llms:
  enabled: true                     # generate /llms.txt and /llms-full.txt
  collections: [docs]

See Global settings for the full field list.

`theme.yaml`

Pick a built-in preset, then optionally override individual tokens:

preset: maple   # almond, aspen, catppuccin, dark, dusk, emerald, light,
                # maple, neutral, ocean, purple, ruby, solar, vitepress

colors:
  primary: "oklch(65% 0.2 50)"

See Theming for the full token reference.

`meta.yaml` (per folder)

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

title: Guides
order: 20

Pages within the section are sorted by their own order frontmatter.

Configuration

astro.config.ts

Auto-wired by docsShell()

Ordering

src/content.config.ts

publier.config.yaml

theme.yaml