Formatting
Everything a page can do: front matter, callouts, open questions and ladders, tables, code, images and placeholders, each shown as it renders.
A page is one markdown file with front matter at the top. Everything below is standard markdown plus a few additions, each shown here as source and as it renders.
Front matter
---
title: Send fees
description: "One sentence, used in search results and link previews."
permalink: /guide/daily-spending-wallet/sending/send-fees/
parent: Sending
nav_order: 3
layout: guide
status: rewritten
sources: [BRC-29, ARC documentation]
---| Field | What it does |
|---|---|
title | The page name, in the tree, the breadcrumb and the heading |
description | Search results, link previews, the section index |
permalink | The URL, always with a trailing slash |
status | new, rewritten, pending light edit or pending rewrite. A pending status shows a badge beside the title |
rewrite_note | One line on what the rewrite must change. Delete it when done |
sources | What the page was written from |
allows | Banned terms this page may use, with the reason obvious from the page |
The share card is generated from title, description and the page's
section, so there is no image field to set and nothing to keep in step.
The site renders the page's # Heading, with any status badge beside it, so the one in the markdown is not drawn twice.
Text
**bold**, _italic_, backticks for inline code, and [a link](/guide/) all work as expected. Italic text directly under an image becomes its caption.
A link on its own line, pointing outside the site, opens in a new tab automatically. Nothing to mark up.
Headings
## and ### appear in the On this page rail and get their own anchor. #### renders but is not listed, which makes it the right level for something that should not clutter the rail.
Don't
Use # inside a page. The title is already the h1 and a second one breaks the outline.
The callouts
This is the main addition, and the reason not to use blockquotes for emphasis. Every example on this page is collected into its checklist like any other rule, so each one is written as a real formatting rule.
:::do[Do]
Put one rule in each callout. Every line inside a Do or a Don't becomes its own checklist item.
:::Do
Put one rule in each callout. Every line inside a Do or a Don't becomes its own checklist item.
:::dont[Don't]
Put a rule in a fact panel or a tip. Only Do, Don't and Recommendation reach the checklist.
:::Don't
Put a rule in a fact panel or a tip. Only Do, Don't and Recommendation reach the checklist.
:::fact[Why this matters]
A fact panel explains. It never enters the checklist, so nothing the
reader must do belongs in one.
:::Why this matters
A fact panel explains. It never enters the checklist, so nothing the reader must do belongs in one.
:::callout[Recommendation]
Keep a recommendation to one or two sentences, so it reads whole in the checklist.
:::Recommendation
Keep a recommendation to one or two sentences, so it reads whole in the checklist.
Do and Don't items are collected into the page's checklist, which readers can tick off. A Recommendation counts as a do. So choosing a directive is a content decision, not a styling one.
Do
Write each callout so it stands on its own. In the checklist it appears without the paragraph above it.
Open questions and ladders
Two more blocks, for where the guide does not know, or where the honest answer is "it depends". Neither is a rule, so neither goes into the checklist.
Open questions hold what a page cannot answer yet: something nobody has tested, or a trade-off that has not settled. On pattern pages, open questions come after the rules and before Related.
:::open[Open questions]
- Do people read an allowance as a limit or as a balance?
- Does showing the remaining allowance reduce top-ups or increase them?
:::Open questions
- Do people read an allowance as a limit or as a balance?
- Does showing the remaining allowance reduce top-ups or increase them?
A ladder grades a contested behaviour. It is always three list items, in this order, each starting with its bold label, because the coloured edge follows the order and the label carries the meaning.
:::ladder[Asking for an allowance]
- **OK:** after the user has paid once, with the amount and period stated.
- **Grey area:** at connection, before the user has seen what it pays for.
- **Not OK:** a standing allowance with no limit, or one preselected.
:::Asking for an allowance
- OK: after the user has paid once, with the amount and period stated.
- Grey area: at connection, before the user has seen what it pays for.
- Not OK: a standing allowance with no limit, or one preselected.
Do
Use an open question rather than a confident rule when the guide is guessing. A rule that turns out wrong costs more trust than a question left open.
Lists
Ordinary markdown. Numbered lists for sequences, bullets for sets.
- First
- Second
- Third
- One thing
- Another thing
Tables
Good for a comparison and bad for anything else. On a narrow screen a table scrolls sideways rather than stacking, because stacking a comparison destroys the comparison.
| Form | Looks like | Read |
|---|---|---|
| Handle | `anna@example.com` | Always || Form | Looks like | Read |
|---|---|---|
| Handle | anna@example.com | Always |
Don't
Use a table for a list with one column of content. It reads worse and scrolls worse.
Code
Fence it, and name the language if it has one.
```ts
const wallet = await connect({ app: "Example" });
```const wallet = await connect({ app: "Example" });Without a language, it renders as a plain block, which is right for a path, a command or a sample of output.
npm run checkQuotes
A quotation, from a person, with the attribution in the sentence that introduces it.
Reserved for actual quotations. For emphasis, use a callout.
Images
_The caption, if the image needs one._See Media for grids, mobile variants and video, and Illustration guidelines for making the files.
Image placeholders
Where a page needs an image that has not been drawn, it carries the brief instead of the picture:
<!-- image placeholder: a wallet presenting a Pass to an app · prompt: IMAGE-PROMPTS.md P1 -->That renders as a box at the right aspect ratio with the prompt inside it, so the gap is visible and the brief is already written. The number refers to an entry in content/IMAGE-PROMPTS.md.
Glossary terms
The first mention of a glossary term on a page is linked automatically. There is nothing to mark up, and it never happens inside a heading, a link or code.
If a term should not link, rephrase. See the Glossary for what is in the list.
Horizontal rules
--- draws one. Use it rarely; headings already separate things.
What is checked
npm run check fails on dead internal links, images not in the manifest, unresolved image prompts, em dashes, banned vocabulary, empty code spans, and a page that cannot be reached from the tree. It also measures colour contrast.
Recommendation
Run it before you open the pull request. It is the same check that runs there, and it takes seconds.
Related
Written from: components/guide/markdown.tsx, lib/content/remark-guide.ts.
Checklist
The rules on this page, in a form you can work through.
8 rules