Skip to content

Writing this documentation

The site is Astro Starlight in docs-site/: Markdown and MDX pages under src/content/docs/, built to static HTML with search included, deployable to any static host. .github/workflows/docs.yml builds it on every pull request that touches docs-site/, so a broken page or link fails the check, and publishes main to GitHub Pages at docs.ivoryos.ai (at ivoryos-ai.github.io/ivoryos-next until the custom domain is set). Write links between pages root-absolute, /guide/designer/: the build prefixes the sub-path when there is one. The two hero buttons on the home page are the exception, written relative, since Starlight does not run frontmatter links through that step.

Terminal window
cd docs-site
npm install
npm run dev # http://localhost:4321, live reload
npm run build # dist/
FolderSidebar group
start/Start here
guide/User guide: the pages
run/User guide: running experiments
desktop/, cloud/User guide: desktop app, Cloud
dev/instruments/, dev/extend/, dev/internals/Developer guide
reference/Reference

Order within a group is sidebar.order in the frontmatter. Use .mdx when a page needs <Steps>, <Tabs> or <Aside>; plain .md otherwise (:::note / :::tip / :::caution asides work in both).

Every picture under src/assets/screenshots/ comes from scripts/screenshots.mjs, which drives the installed Google Chrome against a dedicated example deck and captures each documented state of the app at 1440×900, light theme, 2×. After an interface change, regenerate rather than retouch:

Terminal window
# 1. a fresh deck, in its own data folder (docs-site/.deck-data, ignored by git)
rm -rf docs-site/.deck-data
uv run --project edge_server --with baybe==0.15.0 --with plotly python docs-site/scripts/docs-deck.py
# 2. in docs-site/, every scene (about five minutes; starts several runs on the deck)
npm run screenshots
npm run screenshots -- designer-workflow once # only these scenes

Start from a fresh data folder so run numbers and history match the text (the Data History pages select Run #1). The scenes are ordered so that the runs they start come out in the order the prose expects. Add a scene for a new state rather than a one-off capture, so the next person can regenerate it.

  • Say what the person does and what they see, in the words the interface uses, bold for things they click (Load to Designer).
  • One idea per sentence. Lead with the outcome. No marketing.
  • A screenshot shows one thing; crop with clip in the scene when the whole window is noise.
  • Explain the why when a behaviour would otherwise look like a bug (why Stop skips cleanup, why a batch step reads the first row only). AGENTS.md has the reasons.
  • Keep the developer pages exact: if a rule is in the code, name the function so it can be checked.