Add idocs to an existing site

If you already have an Astro site with Starlight, adding idocs takes a few minutes. For a new site, use the quick start instead.

Install the packages.

pnpm add @the-package-labs/idocs-astro @the-package-labs/idocs-react @astrojs/react react react-dom
pnpm add -D @the-package-labs/idocs

On pnpm 10 or later, allow the build scripts it asks about by adding this to pnpm-workspace.yaml:

allowBuilds:
  esbuild: true
  sharp: true

Register the integrations in astro.config.mjs.

import react from '@astrojs/react'
import starlight from '@astrojs/starlight'
import idocs from '@the-package-labs/idocs-astro'
import { defineConfig } from 'astro/config'

export default defineConfig({
  integrations: [
    idocs(),   // compiles diagrams/ at build time; the build fails on a broken diagram
    react(),
    starlight({
      title: 'My docs',
      // Widens the content column for diagrams and keeps prose at a readable width.
      customCss: ['@the-package-labs/idocs-astro/starlight.css'],
    }),
  ],
})

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

Add the types. In src/env.d.ts:

/// <reference types="@the-package-labs/idocs-astro/virtual" />

Create a first diagram.

pnpm idocs new shop
pnpm idocs schema        # editor autocomplete for diagram.yaml
pnpm idocs check

Put it on a page, such as src/content/docs/shop.mdx.

---
title: Shop
tableOfContents: false
---
import Diagram from '@the-package-labs/idocs-astro/Diagram.astro'

<Diagram name="shop" />

Check in CI. Add "check": "idocs check" to the scripts in package.json, and run it before you build.

Fonts

The starter loads IBM Plex Sans and IBM Plex Mono through Fontsource. To match it:

pnpm add @fontsource/ibm-plex-sans @fontsource/ibm-plex-mono

customCss: [
  '@fontsource/ibm-plex-sans/400.css',
  '@fontsource/ibm-plex-sans/600.css',
  '@fontsource/ibm-plex-mono/400.css',
  '@the-package-labs/idocs-astro/starlight.css',
],

Or use your own fonts and set --idocs-sans and --idocs-mono. See theming.

An Astro site without Starlight

The same steps apply, except for customCss. Give the diagram a wide container, since a diagram is wide. <Diagram> is a normal Astro component and does not need Starlight.

Check that it works

Run pnpm dev and open the page. You should see the diagram, a scenario button and a player. If you do not:

Symptom	Check
`<Diagram name="x"> does not match a diagram`	The folder name differs. The error lists the names that exist.
The page says “Loading diagram…” and nothing appears	A browser console error. Is `react()` from `@astrojs/react` in `astro.config.mjs`?
The page is narrow and the diagram tiny	Add `@the-package-labs/idocs-astro/starlight.css` to Starlight’s `customCss`.
Edits to a diagram do not show	Save the file again. If you upgraded idocs, restart the dev server.

Errors and warnings covers what idocs check reports.