Skip to content
Calimero CoreCalimero CoreCalimero Core

Writing Documentation

The documentation you’re reading is an Astro Starlight site under docs/.

Run it locally

Section titled “Run it locally”

  1. Install and start the dev server:

    Terminal window
    cd docs
    npm install
    npm run dev          # http://localhost:4321/core/

  2. Before pushing, build and validate links exactly as CI does:

    Terminal window
    npm run check        # astro build + internal link check

A GitHub Action (docs-ci.yml) runs npm run check on every PR that touches docs/**, so a broken build or a dead internal link fails the PR.

How content is organized

Section titled “How content is organized”

Pages live in src/content/docs/ as Markdown/MDX, split by audience track, and within a track by Diátaxis mode (tutorial / how-to / reference / explanation):

Track Directory For
Cloud cloud/ Everyone new to Calimero: overview, quickstart, writing apps
Build build/ App developers
Operate operate/ Cluster operators: deployment, references for merod, meroctl, configuration and the node API
Protocol protocol/ Reimplementers (concepts + normative spec)
Contribute contribute/ Core developers

The sidebar is listed explicitly in astro.config.mjs, grouped and ordered by hand; a new page appears in it only once it is added there. Keep each page’s sidebar.order frontmatter in step with that order.

Conventions

Section titled “Conventions”
  • Frontmatter carries title, description, and sidebar.order/label. Reserve sidebar.badge for a genuinely incomplete page — not as a blanket marker.
  • One mode per page. A tutorial promises an outcome and doesn’t branch; a reference is exhaustive and doesn’t editorialize. Don’t mix them.
  • Ground claims in code. CLI flags, endpoints, config keys, macros, and byte layouts must match the source: merod’s flags are NodeArgs in crates/merod/src/node_config.rs, meroctl’s commands are the clap definitions in crates/meroctl/src/, and the node’s routes are router in crates/node/src/api.rs. If you can’t confirm something, flag it with a :::caution saying exactly what to check rather than guessing.
  • Normative requirements (protocol spec) go in a :::caution[Normative] callout using RFC 2119 wording (MUST / SHOULD / MAY).
  • Internal links are root-absolute without the base, e.g. /operate/merod/ (Starlight adds the /core base). The link checker enforces this.

Diagrams

Section titled “Diagrams”

Two kinds, both animated with the bespoke step-cascade engine:

  • Sequence/flow diagrams are data-driven via the SeqDiagram island — author lanes and steps as data, no SVG by hand:

    import SeqDiagram from '../../../components/SeqDiagram.astro';
    

    <SeqDiagram id="d-foo" title="..."
      lanes={[{ label: 'A', color: '#3fb950' }]}
      steps={[{ from: 0, to: 0, label: 'do a thing' }]} />

  • Structural diagrams are hand-authored SVG kept in src/components/diagrams/*.astro (raw SVG is first-class in Astro components, but breaks inside MDX), and referenced like any component.

Where to start

Section titled “Where to start”
Contributor architecture orientation
Development workflow