Publishing

An idocs site is a static Astro site. pnpm build writes it to dist/, and any host that serves files can serve it.

pnpm check     # validate every diagram
pnpm build     # writes the site to dist/

The build fails when a diagram has errors, so a broken diagram never reaches the published site.

GitHub Pages

The starter ships .github/workflows/deploy.yml. It installs, runs pnpm check, builds, and deploys to GitHub Pages on every push to main.

1. Push the project to a GitHub repository.
2. Open Settings → Pages and set the source to GitHub Actions. You do this once.
3. Push to main. The workflow builds the site and publishes it at https://<owner>.github.io/<repo>/.

If the first deploy is skipped

Until Pages is enabled with the GitHub Actions source, the deploy step cannot run. The workflow detects that and skips it with a notice, so the build still succeeds. Enable Pages, then re-run the workflow.

GitHub Pages on a private repository needs a paid GitHub plan. On a free plan, use one of the other hosts below.

When the docs live in a subfolder

GitHub only runs workflows from the .github/workflows/ folder at the root of a repository. If the idocs project sits in a folder of a larger repository (say docs/), the starter’s workflow never runs there. Move it to the repository root and point each step at the folder:

on:
  push:
    branches: [main]
    paths: [docs/**]          # only rebuild when the docs change

defaults:
  run:
    working-directory: docs   # every `run:` step starts here

# ...and in the steps:
- uses: pnpm/action-setup@v4
  with:
    package_json_file: docs/package.json
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: pnpm
    cache-dependency-path: docs/pnpm-lock.yaml
- uses: actions/upload-pages-artifact@v3
  with:
    path: docs/dist

BASE_PATH stays /<repo>, because the folder is not part of the published address.

If a node cites code in a sibling repository, give refs: the repository’s URL instead of a relative path. idocs check only looks for paths, so pnpm check --strict keeps passing in a checkout that has no neighbours.

Project pages and the base path

A project site lives under /<repo>/, not at the root. The workflow sets two variables, and astro.config.mjs reads them:

export default defineConfig({
  site: process.env.SITE_URL,     // https://<owner>.github.io
  base: process.env.BASE_PATH,    // /<repo>
})

Locally both are unset, so the site is served at /. With a custom domain or a <owner>.github.io repository, remove BASE_PATH from the workflow:

- run: pnpm build
  env:
    SITE_URL: https://docs.example.com

Write links in your pages as relative links (../../format/nodes/), or build them from import.meta.env.BASE_URL. A link that starts with / does not include the base path.

Other hosts

Netlify

Build command pnpm build, publish directory dist. Set SITE_URL to your site’s address.

Vercel

Framework preset Astro. Build command pnpm build, output directory dist.

Cloudflare Pages

Framework preset Astro. Build command pnpm build, output directory dist.

Any static host

Copy the contents of dist/ to the host. It needs no server code.

Set SITE_URL wherever you build, so absolute URLs in the sitemap and metadata are right.

Previewing

pnpm build
pnpm preview

pnpm preview serves the built dist/, which is the closest thing to what your readers get.

What the build does with diagrams

1. Reads every diagrams/<name>/diagram.yaml.
2. Validates and compiles it. Errors stop the build with file:line:column and a suggestion.
3. Bundles the icons it uses and renders node docs and notes to HTML.
4. Passes the compiled diagram, as JSON, to the page that embeds it.

Warnings, such as an unknown icon or a stale refs: path, are printed but do not stop the build. To fail on warnings too, run pnpm idocs check --strict before the build.

Keeping it fast

Each <Diagram> loads its interactive part only when it scrolls into view. The layout engine is the largest piece of that code, so pages without diagrams pay nothing for it. A page with several diagrams loads the engine once.