Project structure

An idocs project is an ordinary Astro site with the Starlight docs theme and the idocs integration. If you know Astro, nothing here is new.

Directorydiagrams/
- diagram.schema.json editor autocomplete (generated)
- Directoryshop/
  - diagram.yaml the model, views and scenarios
  - Directorynodes/
    gateway.md shown when a reader clicks the gateway
    orders.md
  - Directoryscenarios/ optional: one file per long scenario
    …
Directorysrc/
- Directorycontent/docs/
  - index.mdx
  - architecture.mdx
  - editing.mdx
- styles/custom.css your theme tokens
- content.config.ts
.github/workflows/deploy.yml builds and publishes to GitHub Pages
Directory.claude/skills/idocs/ teaches Claude Code the format
- …
astro.config.mjs
CLAUDE.md notes for agents working in the project
package.json

diagrams/

One folder per diagram. The folder name is what <Diagram name="..."> refers to.

File	Purpose
`diagram.yaml`	The diagram. See the diagram format.
`nodes/<id>.md`	Documentation for one node, shown in the drawer. Optional. See node docs.
`scenarios/<id>.yaml`	One scenario in its own file; the file name is its id. Optional. See scenarios.
`assets/*.svg`	Your own icons, referenced as `icon: ./assets/name.svg`. Optional.

diagrams/diagram.schema.json is generated by pnpm idocs schema. Point a diagram at it with # yaml-language-server: $schema=../diagram.schema.json on the first line.

src/content/docs/

Your pages, as .mdx files. A page is Markdown with components. Embed a diagram anywhere in it:

import Diagram from '@the-package-labs/idocs-astro/Diagram.astro'

<Diagram name="shop" scenario="checkout" />

The Diagram component lists every option.

astro.config.mjs

Registers three integrations: idocs() compiles diagrams/ at build time, react() runs the diagram on the client, and starlight() provides the docs chrome. The sidebar list in the Starlight options decides the navigation.

idocs({ dir: 'my-diagrams' }) changes the diagrams folder (default diagrams).

src/styles/custom.css

Override --idocs-* variables here to restyle every diagram. Theming lists them.

.github/workflows/deploy.yml

Checks the diagrams, builds the site and publishes it to GitHub Pages. It sets SITE_URL and BASE_PATH, which astro.config.mjs reads.

.claude/skills/idocs/ and CLAUDE.md

The idocs agent skill, so Claude Code can write and fix diagrams without being told the format. Other agents can install it with npx skills add.