Formatting reference (sample article)

This is a reference article showing every formatting feature available when writing help articles. Copy the patterns from the Markdown source of this file when you’re writing new ones.

The Markdown source for this article lives at apps/api/public/website/help/articles/sample-formatting.md. Open it side-by-side with the rendered page to see how each block is written.

Text formatting

You can use bold, italic, bold italic, and inline code. You can also ~~strike through~~ text. Links look like this one to costed.app — they’re styled with a gold underline that lifts to navy on hover.

Press Cmd+K on Mac or Ctrl+K on Windows to use keyboard shortcuts — wrap any keys in <kbd> tags.

Lists

Unordered:

First item with bold text
Second item with a link
Third item
- Nested item one
- Nested item two

Ordered:

First, do this
Then this
Finally this

Headings

Use ## for major sections, ### for sub-sections, #### for sub-sub-sections (rarely needed). The H1 is set from frontmatter title — never use a top-level # in the body.

This is an H3

Sub-section text goes here. Use H3s to break up a long H2 section.

This is an H4

Small subdivisions. Rare in help content.

Callouts and quotes

Use blockquotes (>) for important notes, tips, or warnings. They get a gold left-bar and a soft yellow background:

Tip: if you’re about to write a how-to with more than 5 steps, consider splitting it into multiple shorter articles. Short articles rank better, get bookmarked more often, and are easier to keep up to date.

Warning: never paste API keys or passwords into a help article. They’d be public the moment we deploy.

Code blocks

Use triple backticks for code blocks. Add a language tag for syntax-context (purely cosmetic — we don’t ship highlight.js yet).

# Set environment variables before running migration
export DATABASE_URL='postgresql://...'
npx tsx scripts/migrate-suppliers.ts --tenant=mybuilder

SELECT s.name, COUNT(o.id) AS open_orders
FROM tenant_mybuilder.suppliers s
LEFT JOIN tenant_mybuilder.orders o
  ON o.supplier_id = s.id AND o.is_closed = false
GROUP BY s.id, s.name
ORDER BY open_orders DESC
LIMIT 20;

For an inline mention of code, use single backticks: cost_centre_id.

Tables

Pipe tables work — great for listing options, status meanings, or comparison matrices:

Status	What it means	Action required
Draft	Not yet sent	Edit and send
Sent	Awaiting supplier response	Wait
Quoted	Supplier responded	Review pricing
Ordered	Converted to PO	Track delivery
Closed	Complete	No action

Images

Reference images with standard Markdown syntax. Files live in apps/api/public/website/help/images/:

![Screenshot of the supplier import dialog](/help/images/suppliers-import.jpg)

Renders the image with rounded corners, a subtle border, and the alt text as a caption fallback. Images are responsive (max-width: 100%).

For images with explicit captions, use a <figure>:

<figure>
  <img src="/help/images/boq-formula-bar.jpg" alt="The BOQ formula bar" />
  <figcaption>The formula bar lets you reference other rows using A1-style notation.</figcaption>
</figure>

Video

YouTube / Vimeo / Loom embeds — paste the iframe directly into the Markdown:

<iframe
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  title="How to set up cost centres"
  allow="accelerometer; clipboard-write; encrypted-media; picture-in-picture"
  allowfullscreen>
</iframe>

Self-hosted video — drop the MP4 in /help/video/ and use a <video> tag:

<video controls preload="metadata" poster="/help/images/video-poster.jpg">
  <source src="/help/video/boq-import.mp4" type="video/mp4" />
</video>

Downloads

Link to PDFs, spreadsheets, or sample files stored in /help/files/:

Horizontal rule

Use --- on its own line to separate major sections:

Putting it all together

A well-structured help article usually follows this shape:

One-paragraph summary — the article’s headline answer in plain English. If a reader only reads this, they should still have what they came for.
Prerequisites — what they need (an account, a role, a file ready to upload).
Steps — numbered, one action per step, with screenshots where it helps.
Verification — how to confirm it worked.
Common problems — what to do when it didn’t work.

Keep articles scannable. Most readers skim until they find their bit. Use headings every 100–200 words, lots of bullet lists, and short paragraphs. Long unbroken text walls get bounced.

Need help writing one?

Ask Claude — paste your topic, your audience, and what you want them to be able to do at the end. Claude will draft it in this exact format.