Documentation style

marimohub docs are operator-first. Write for someone evaluating, configuring, deploying, operating, or troubleshooting a self-hosted notebook hub.

Page types

Use one clear page type.

Type	Use for	Pattern
Tutorial	First success	Goal, prerequisites, steps, expected result
How-to	A specific operator task	Task, config, command, validate, next link
Reference	Complete facts	Tables, defaults, generated content, anchors
Explanation	Why the system works the way it works	Concepts, trade-offs, links to references

Do not mix long explanation into a task page. Link to architecture or reference material instead.

Voice

• Prefer direct, present-tense sentences.
• Address the reader as "you" when giving instructions.
• Use active voice unless passive voice is clearer.
• Keep paragraphs short. Start with the point.
• Avoid "easy", "simple", "just", and similar words that can minimize operator effort.
• Avoid idioms and culture-specific phrases.
• Spell out acronyms on first use when they are not common in infrastructure docs.

Examples

• Use example.com, hub.example.com, and sandboxes.example.net for sample domains.
• Use placeholders such as <bucket-name> when the reader must supply a value.
• Never include real tokens, cookies, keys, personal emails, or private hostnames.
• Mark secret values as secret and explain where to store them.

Structure

• Keep existing URLs stable. Add redirects before renaming public docs pages.
• Put operator workflows in docs/.
• Put implementation rationale and internal design in development_docs/.
• Keep generated reference pages generated. For configuration docs, edit packages/config/src/spec.ts and run:

pnpm --filter @marimo-hub/config docs:generate

Screenshots

• Capture the local hub with sample data. Exclude credentials, private URLs, and personal information.
• Crop to the relevant cell, dialog, or controls. Place the image beside the instructions it illustrates.
• Store PNG files in docs/public/screenshots/. Use a descriptive filename, such as workspace-files.png.
• Use a <figure class="doc-screenshot"> with descriptive image alt text.
• Add a short <figcaption> unless the surrounding heading, description, and alt text already explain the screenshot.
• Link the image to its full-size file. Include the new-tab behavior in the link’s accessible label.
• Set the image’s intrinsic width and height, plus loading="lazy" and decoding="async".
• Add doc-screenshot--narrow for dialogs, doc-screenshot--portrait for tall forms, or doc-screenshot--card for a single gallery card.
• Check the page on desktop and mobile, in light and dark themes.

Verification

For docs-only changes, run:

pnpm --filter @marimo-hub/docs test
pnpm --filter @marimo-hub/docs build

Before finishing, remove comments and prose that only narrate the change or repeat what the surrounding heading, code, or command already says. Keep comments that explain a maintenance rule, source of truth, or non-obvious constraint.