Quick start

You need Node 22 or later and pnpm. The scaffolded project uses pnpm, and npm create only runs the scaffolder.

Create a project

Scaffold the project.
Terminal window
```
npm create docspp@latest my-docs
```
Install and start it.
Terminal window
```
cd my-docs
pnpm install
pnpm dev
```
Open http://localhost:4321. You see a small shop diagram with three scenarios.
Open diagrams/shop/diagram.yaml, change a title, and save. The page reloads.

If you would rather start from the source, copy templates/starter from the docspp repository.

What you get

my-docs/
├─ diagrams/
│  ├─ diagram.schema.json     editor autocomplete for diagram.yaml
│  └─ shop/
│     ├─ diagram.yaml         nodes, groups, edges, views, scenarios
│     └─ nodes/orders.md      shown when a reader clicks that box
├─ src/content/docs/*.mdx     your pages; embed a diagram with <Diagram name="shop" />
├─ src/styles/custom.css      theme tokens
├─ .github/workflows/         publishes to GitHub Pages
├─ .claude/skills/            a skill that teaches Claude Code the format
├─ astro.config.mjs
└─ package.json

Everything you write lives in three places:

Where	What
`diagrams/<name>/diagram.yaml`	The nodes, edges, views and scenarios of one diagram
`diagrams/<name>/nodes/<id>.md`	Markdown shown when a reader clicks that box
`src/content/docs/*/.mdx`	The pages around your diagrams

Project structure explains each file.

Draw your first diagram

pnpm docspp new payments
pnpm docspp schema

The first command creates diagrams/payments/diagram.yaml with a small working example. The second writes the JSON Schema that gives your editor autocomplete. Here is a similar diagram:

title: Hello, diagrams

nodes:
  browser: { kind: client, title: Browser }
  api:     { kind: service, icon: nodejs, title: API, sub: ":3000" }
  db:      { kind: database, icon: postgresql, title: Database }

edges:
  - browser -> api: HTTPS
  - api -> db: { kind: data, label: SQL }

scenarios:
  load-page:
    title: Load a page
    steps:
      - browser -> api: GET /items
      - api -> db: { label: SELECT, kind: lookup }
      - db -> api: rows
      - api -> browser: 200 OK

Put it on a page with two lines of MDX:

import Diagram from '@packagelab/docspp-astro/Diagram.astro'

<Diagram name="hello" />

Scenario

HTTP request / responseData access

Loading diagram…

Browser→APIGET /items

API→DatabaseSELECT

Database→APIrows

API→Browser200 OK

Press play, click a box, or drag the canvas. Hold Ctrl or ⌘ and scroll to zoom. Your first diagram builds a larger one step by step.

Check your work

pnpm check          # validate every diagram; errors point at file:line:column
pnpm check --json   # the same, for scripts and agents

The build fails when a diagram has errors, so a broken diagram never reaches your published site. The CLI reference lists every command.

Publish

The project ships a GitHub Actions workflow that builds the site and deploys it to GitHub Pages.

Push the project to GitHub.
Open Settings → Pages and set the source to GitHub Actions.
Push to main. The workflow builds the site and publishes it.

Publishing covers custom domains and other hosts.

Next steps

Your first diagram: build one from scratch.
Diagram format: every field, with live examples.
Scenarios: the part readers remember.
Working with an AI agent: let an agent draw your architecture from your code.