Writing

Markdown#

coppice reads GitHub-flavoured markdown: italics, bold, code, links, lists, quotations, tables, strikethrough, task lists, and bare addresses that become links. HTML passes through untouched, for anything markdown can't say. Quotes and dashes come out exactly as typed, so type the ones you mean: ’ “ ” – —.

Headings#

Start sections with ##, and go down a level at a time with ### and ####; the page's title is the only #. Each heading gets an id from its words, so ## Front matter can be linked to as #front-matter. A post with two or more ## headings gets a contents list, as each doc does in its sidebar.

Links#

Link to the site's own pages from its root, as /docs/settings/ or /docs/settings/#fonts, and to other sites in full. The build checks every link of the first kind, in every page, and stops at one that goes nowhere: a page, a picture or a section that isn't there. Links to other sites aren't checked.

Sidenotes#

Notes sit in the margin beside the line they belong to. A numbered note is {sn|…}, a margin note without a number {mn|…}:

The cycloid is the curve of fastest descent.{sn|Johann Bernoulli posed the problem in 1696.}

Markdown works inside a note, and the first } ends it. On wide screens notes stand in the right margin; on narrow ones a reader opens each with its number, or ⊕ for a margin note, by touch or keyboard. The feed puts each in parentheses after its line. Notes are left alone in code, so a post can show the syntax, as this one does; indented code blocks aren't skipped, so fence any code that shows a note.

Callouts#

A note, a tip or a warning the reader shouldn't miss goes in a callout: a quotation that starts with its kind, as on GitHub.

> [!NOTE]
> The feed links to the address in url, so set it before publishing.

The kinds are [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] and [!CAUTION]. Each is titled with its kind, from [words] in config.toml, so it's told apart by its words, not its colour.

Pictures#

Put pictures in static/images/ and show them with ![what it shows](/images/name.jpg). The words in brackets are read aloud in the picture's place, so say what it shows. For a caption, write the HTML:

<figure>
<img src="/images/name.jpg" alt="What it shows">
<figcaption>The caption, with its credit.</figcaption>
</figure>

The build gives every picture of the site's own its width and height, so the text doesn't jump about as pictures load. An SVG is shown inverted in dark mode, so a diagram drawn in black on a transparent background turns light. Many pictures together go in a gallery.

Mathematics#

Inline mathematics is text with a little HTML: x² is *x*<sup>2</sup>. Equations on their own lines are MathML, which browsers draw themselves:

<math display="block">
<mfrac><mn>1</mn><msqrt><mi>x</mi></msqrt></mfrac>
</math>

Keep <math display="block"> on its own line, leave no blank lines inside the equation, and keep it narrow enough for a phone, splitting a long one into the rows of an <mtable>. One too wide scrolls sideways rather than widening the page.

Code#

Fence code with three backticks and name its language, and the build highlights it in the colours of code in config.toml; nearly three hundred languages are known. A long line scrolls sideways inside its block, and each block has a Copy button, shown when it's pointed at, or always on a touch screen.

References#

Everything after a heading ## References is set at the references size, so a list of sources can be smaller than the text.