Skip to content
Beef Docs

Rich Formatting Standard

Rich Formatting Standard

Section titled “Rich Formatting Standard”

People read our PRs, Linear issues, and docs on surfaces that render more than plain Markdown. Use a richer format when it lets the reader get the point faster than prose would: a diagram for a flow, a table for a comparison, a collapsed block for a long log. Do not add formatting as decoration. A short answer stays a short paragraph.

This applies to people and agents alike. Agents tend to write everything as bullet lists, so this page is the reference their instructions point to.

What Renders Where

Section titled “What Renders Where”

Checked on 2026-10-13. Recheck when a surface changes.

Surface Mermaid Callouts Collapsible Raw HTML Images
Docs site (Starlight) Yes, via astro-mermaid :::note, :::tip, :::caution, :::danger <details> Yes, but see HTML in Docs _assets/ beside the page
GitHub PR body, comment, review Yes > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION] <details> Sanitized subset only Drag-and-drop in the browser; no API upload
GitHub file view .md fences, .mmd, .mermaid GitHub alerts in .md <details> in .md Shown as source .png, .svg render
Linear issue, document, comment Yes in the editor (/diagram or a pasted mermaid fence) None; use a bold lead line >>> then space No Upload as an attachment
Agent chat in a terminal No No No No No

GitHub also renders math ($...$), GeoJSON and TopoJSON maps, STL models, and suggestion blocks in review comments. Starlight callouts show as plain text on GitHub, and GitHub alerts show as plain blockquotes on the docs site. Use the syntax of the surface the reader will open.

A mermaid fence sent to Linear through the API or MCP has not been verified to become a diagram. Open the issue after posting and check.

Choosing a Format

Section titled “Choosing a Format”
Content Use
A flow with three or more actors, or a request crossing services Mermaid sequenceDiagram
Dependencies, routing, or a decision tree Mermaid flowchart
A lifecycle with named states Mermaid stateDiagram-v2
Three or more options compared on the same attributes Table
Logs, full test output, or detail most readers skip <details> on GitHub, >>> on Linear
One caveat the reader must not miss A single callout, never several in a row
A UI change Before and after screenshots, plus the preview link
A concrete fix in a review thread GitHub suggestion block
Anything else Plain sentences

Agent replies in a terminal render Markdown text only. Keep diagrams and callouts for the PR, issue, or doc where a person will read them. When a reply hands over Markdown to paste, wrap it in a four-backtick fence so the inner mermaid and code fences do not close it early.

Writing Diagrams for People

Section titled “Writing Diagrams for People”
  • Name boxes in plain words a new teammate would understand. Avoid internal codes, ticket numbers, and legends that need decoding.
  • Label each arrow with what moves or why. Draw arrows only for real dependencies.
  • Keep one idea per diagram. Split anything past about 15 nodes.
  • Quote labels that contain punctuation: A["Processor (NestJS)"]. Unquoted (, ), and @ inside [...] break the flowchart parser.
  • Do not put ; in sequence diagram messages. Mermaid reads it as the end of the statement.

Check a diagram before committing it. GitHub renders it in the PR file view, and pnpm dev from docs/ renders it on the docs site. A diagram that fails to parse shows “Error rendering diagram” on the site.

HTML in Docs

Section titled “HTML in Docs”

Write docs pages in Markdown. Reach for the next option only when the previous one cannot express the content:

  1. Markdown with Mermaid, tables, and Starlight callouts.
  2. An .mdx page using Starlight components such as Tabs, Steps, Cards, or FileTree.
  3. A standalone HTML artifact, such as an interactive prototype or a generated report, under docs/public/<area>/. Link it from a Markdown page that says what it is, who owns it, and how to regenerate it. The docs site serves it behind Cloudflare Access.

Do not hand-write HTML layouts inside .md pages. Reviewers read them as source in diffs, GitHub strips most of the markup, and they drift from the site theme.

Screenshots and Media

Section titled “Screenshots and Media”

GitHub has no API for attaching images to PR comments. Do not commit screenshots into docs/public/ just to get a URL for a PR. Instead:

  • attach the images to the Linear issue, and
  • link the Railway preview (beef-pr-<n>) in the PR body so reviewers can see the change live.

A person can still drag images into the PR body in the browser. Commit an image under docs/ only when a docs page shows it.

Sources

Section titled “Sources”