Skip to content
Sona

Writing docs

The public docs are the pages in site/src/content/docs/. The contributor and agent references (docs/architecture.md, docs/design.md, docs/ui-architecture.md and others) stay in the repository’s docs/ folder.

Preview the site

Section titled “Preview the site”
Terminal window
devenv shell -- docs

This installs the dependencies and starts the site on http://localhost:4321. Pages reload when you save.

Check before you push

Section titled “Check before you push”
Terminal window
cd site
npm run lint
npm run build

npm run lint checks the markdown. npm run build fails on a broken internal link. The Pages workflow runs both on every pull request that touches site/.

Writing rules

Section titled “Writing rules”
  • Lead with what the reader wants to do. Use second person, active voice and short sentences.
  • Give each page one title in title case, and sentence-case headings that name the task: “Install on Linux”.
  • Open with one or two sentences, then the steps. Use a numbered list for steps, bullets for options and a table for reference facts. Nest lists at most two levels.
  • Prefer a code block or a table to a paragraph.
  • Keep history, internal reasons and implementation detail out of user pages. Link to docs/ for depth.
  • Use an aside only for a real warning or tip.
  • Reference pages open with a one-line > description. Each command or token is a heading, its arguments are a bullet list (name type (optional) - description), and platform-only items carry Linux, macOS or Windows.

The home page picture

Section titled “The home page picture”

The picture at the top of the home page and the README, src/assets/hero-light.webp and hero-dark.webp, is three real Sona windows (The Slow Rush and Moon Music album pages behind, Now Playing with time-synced lyrics in front), offset and layered with rounded corners and soft shadows on a transparent background, 2400 px wide and under 400 KB each. Make it again when the interface changes enough to date it:

  1. Run a build with -tags probe,sqlite_fts5 in devenv shell -- headless, signed out, with SONA_PREVIEW=1 SONA_PRIVATE=1, at scale 2 and a 1280×800 window. Use only catalogue content: no account, no personal data.
  2. Capture each screen in Light and Dark (Settings, Appearance, Mode) over the automation socket, once the artwork has loaded.
  3. Composite them and write the WebP files with quality about 85.