Markdown Guide

Available Roles: Docs contributor Platforms: Web Reviewed: 2026-03-14

Use this style guide for docs pages in src/content/docs/docs.

Frontmatter Pattern

Each page should include:

Write for a mixed audience, but default to the reader who is trying to complete a task now.
Prefer direct, operational language over product-positioning language.
Use sentence case in headings.
Use short, concrete openings. The first screen should answer:
- what this page helps the reader do
- when they should use it
- what to do next after the task works
Prefer concrete product terms such as join link, waiting room, summary, recording, permissions, and calendar sync over abstract nouns such as artifact surface, operational layer, or meeting lifecycle unless the abstraction is necessary.
Use second person on task pages. Use explicit role labels on admin, security, and IT pages when responsibility matters more than click-by-click steps.
Keep procedures step-oriented and testable.
State current status plainly on preview or planned pages. Do not write forward-looking copy as if the feature is already fully available.
Do not use internal product-definition headings such as Intended workflow or Current notes in canonical docs.

Use a short operational introduction, usually one or two paragraphs.
Add setup or prerequisites when the reader must decide access, devices, integrations, or policy first.
Include ordered steps for any workflow that requires more than a quick checklist.
Add troubleshooting for pages that describe setup, permissions, networking, mobile use, or any user-facing task that can fail in common ways.
Add related-task links that help the reader continue the workflow.
Use tables or matrices for role comparisons, platform differences, or permission rules when prose becomes hard to scan.

Link to relevant docs pages with absolute docs paths when useful.
Keep links purposeful; avoid long “related links” dumps.
Fix stale or broken docs links as part of the same change set that touches a page.