For AI agents: the complete documentation index is available at https://lazygophers.github.io/pamphlet/en/llms.txt, the full documentation bundle is available at https://lazygophers.github.io/pamphlet/en/llms-full.txt, and this page is available as Markdown at https://lazygophers.github.io/pamphlet/en/start/install.md.
Pamphlet
  • English

      • Installation

      You do not have to install it.

      npx @nekoleapuki/pamphlet-cli build plan.md

      npx ships with npm and means "download this package, run it once, don't leave it on my machine". The first run spends a dozen seconds downloading (measured: 86 packages, 15 seconds); after that npx has its own cache.

      Installing it anyway

      If you use it often, install it globally and the command is just pamphlet:

      npm i -g @nekoleapuki/pamphlet-cli
pamphlet build plan.md

      Or per project:

      pnpm add -D @nekoleapuki/pamphlet-cli
      The package name and the command name differ

      The npm package is @nekoleapuki/pamphlet-cli; the installed command is pamphlet.

      It is not published as pamphlet because that name was taken in 2018 (https://www.npmjs.com/package/pamphlet, latest 4.0.0). It is not an abandoned package and cannot be reclaimed.

      Installing gives you the compiler only. No diagram engine comes with it — text-only documents do not need them, and together they weigh about 340MB (see The other seven diagram types).

      If you want diagrams

      This version implements exactly one engine, Mermaid, and it goes through a headless browser:

      npm i -g mermaid-isomorphic playwright && npx playwright install chromium

      About 150MB and a minute the first time, once. A text-only document never launches the browser. Why a real browser is unavoidable: Mermaid.

      Check what is installed

      pamphlet doctor

      Its messages are Chinese-only for now. Installed:

      ✓ mermaid（mermaid）

      Not installed:

      ✗ mermaid（mermaid）：装一次就好：npm i -g mermaid-isomorphic playwright && npx playwright install chromium（首次约 150MB）

      Any missing engine exits 3 (environment missing).

      Requirements

      • Node.js ≥ 20 (engines.node in packages/pamphlet/package.json)
      • No Java — unless PlantUML lands one day; it is the only one of the seven engines that needs Java ≥ 11

      One thing to know before upgrading

      During 0.x only patch compatibility is promised.

      UpgradePromise
      0.0.1 → 0.0.2Breaks nothing
      0.0 → 0.1May break syntax, CLI flags, the AST

      The first published version is 0.0.1. This matches what semantic versioning says about a zero major version; it is not a rule Pamphlet invented.

      Check that your documents still compile on every minor upgrade:

      pamphlet lint "docs/**/*.md"

      Put that in CI and it tells you immediately which document stopped compiling — see Checking documents in CI.

      :::danger Three things explicitly unstable

      • The AST shape (what pamphlet ast prints) — no compatibility promise during 0.x
      • CLI flags — may be renamed or removed in a minor release
      • The plugin API — likewise :::

      These three are exactly the parts that need the most adjustment early on. Freezing them at 0.1 (considered, rejected) would weld shut the parts most in need of change. The cost is real: it is unfriendly to early adopters. That cost was accepted in exchange for being able to correct the syntax freely during 0.x.

      1.0 will revisit this, and should promise considerably more than patch compatibility.

      Source: ADR-0006