Installation

Install the supported toolchain, scaffold a site, sign in, and run the dev server.

Prerequisites

• linux-x64 — macOS and Windows are not supported today.
• Node.js 24 LTS — supplies Corepack for the package manager.
• pnpm 11 — manages dependencies and the lockfile. Run corepack enable after installing Node; Corepack reads the project’s packageManager pin.
• Bun — runs Astro. Install with curl -fsSL https://bun.sh/install | bash and make sure bun and bunx are on your PATH.

Publier’s dev and build commands run Astro under Bun (bunx --bun astro …). pnpm installs the packages; Bun executes them. Node’s restrictions on TypeScript inside node_modules are the reason for the Bun runtime.

Check node --version, pnpm --version, bun --version, and bunx --version before scaffolding.

1. Install the CLI

curl -fsSL https://publier.net/install.sh | sh

The installer verifies the downloaded binary and installs it to $HOME/.publier/bin. Follow its printed shell-specific instructions to add that directory to your startup file. For the current shell:

export PATH="$HOME/.publier/bin:$PATH"
publier --version

With a custom PUBLIER_INSTALL_DIR, add that prefix’s bin directory instead. The installer prints instructions; it does not change the calling shell’s PATH.

2. Scaffold a project

publier new my-site
cd my-site

publier new asks you to pick a template:

The scaffolder uses pnpm install (pnpm is the package manager; bun is the runtime). Flags: --template, --theme, --git/--no-git, --install/--no-install.

3. Sign in

publier dev and publier build require a valid license token:

publier login

This opens browser sign-in. For a terminal without a browser, use publier login --device. publier login --token <jwt> imports an existing access token.

Credentials are cached at ~/.config/publier/auth.json, or under an absolute $XDG_CONFIG_HOME. PUBLIER_TOKEN takes precedence. For CI, follow the deployment guide; a token alone does not provision a fresh runner.

4. Start the dev server

publier dev

Your site is live at http://localhost:4321. MDX edits hot-reload. Restart publier dev after changing publier.config.yaml or theme.yaml; the CLI does not watch those files for automatic restarts.

5. Project layout

my-site/
├── src/
│   ├── content/
│   │   ├── docs/              ← Documentation pages (MDX)
│   │   ├── blog/              ← Blog posts
│   │   └── changelog/         ← Changelog entries
│   ├── components/            ← Your custom Astro components
│   └── pages/                 ← Optional: override any injected route
├── public/                    ← Static assets (logo, favicon, OG images)
├── astro.config.ts            ← docsShell() + the five framework integrations
├── src/content.config.ts      ← Astro content collections
├── publier.config.yaml        ← Site config (nav, search trigger, analytics)
└── theme.yaml                 ← Color theme + typography

6. Add your first page

Create a new MDX file under src/content/docs/:

---
title: My first page
description: A short description shown in search results and the <head>.
---

Hello from **Publier**!

:::tip
Use callouts, tabs, cards, and steps — all work out of the box.
:::

import { Accordion, AccordionItem } from '@publier/primitives';

<Accordion>
  <AccordionItem title="How do I customize the theme?">
    Edit `theme.yaml` — change `preset:` or override individual tokens.
  </AccordionItem>
</Accordion>

Save the file — the dev server picks it up immediately and adds it to the sidebar.

7. Build for production

publier build

Static HTML is emitted to dist/. Deploy anywhere: Cloudflare Pages, Netlify, Vercel, GitHub Pages, nginx. See the deployment guide.

Next steps

• Moving existing docs? — migrate content and verify old URLs.
• Upgrades and rollbacks — maintain CLI and project packages.
• Configuration — every option in publier.config.yaml, theme.yaml, and astro.config.ts.
• Content authoring — MDX frontmatter, snippets, and conventions.
• Theming — pick or customize a built-in theme.
• Components — MDX primitives for prose. UI components — page-level widgets.