Write math and code in a post

Math and code in posts

Math and code work in every post, not only explainers. They are written in Markdown and turned into clean HTML when the post is built, with no script needed to read them. The raw .md shows the source. Setup and publishing are in the Bloggo skill. For explainers, see the explainer skill.

Math

Write math in LaTeX between dollar signs.

• Inline: $E = mc^2$ sits in the sentence.
• Display: put $$ on its own line before and after for a centred formula.

The total after $n$ years at rate $r$ is

$$
A = P\left(1 + r\right)^{n}
$$

where $P$ is the amount you start with.

Bloggo supports the common LaTeX math subset: fractions, roots, sums and integrals, superscripts and subscripts, Greek letters, matrices, \text{}. Links (\href), images and raw HTML are not supported. A formula that does not parse, or is over 2,000 characters, is shown as its source in code, so check the preview.

Rules:

• Say in words what the formula means, before or after it. A formula alone is never the explanation.
• Define every symbol the first time, as in the example above.
• One idea per formula. Break a long derivation into steps, each with a sentence.
• Do not use math where a word does it better. "The average" beats $\bar{x}$ for most readers.
• Use $ only for math. Write a price as "5 dollars" or escape it as \$5 when two prices in a sentence might look like math.
• Put important formulas in plain text too ("A equals P times one plus r, to the power n"), because screen readers and feeds vary in how they read them.

Code

Use fenced blocks with the language after the opening fence. Always give the language. Highlighting covers bash, c, cpp, csharp, css, diff, go, java, javascript, json, kotlin, markdown, php, python, ruby, rust, sql, swift, typescript, xml (html) and yaml, with the usual short names such as js, ts, py, sh and yml; any other language is shown unhighlighted.

```python {title="app.py" highlight="2-3" numbers}
def total(items):
    subtotal = sum(i.price for i in items)
    return subtotal * 1.2
```

Options after the language, all optional:

• title="app.py" shows a file name above the block.
• highlight="2-3" or highlight="5" emphasises lines (numbers count from 1 within the block).
• numbers shows line numbers. Use it when the text refers to line numbers.

For a command and its output, use two blocks: the command with bash and the output with text. Do not mix them, so a reader can copy the command.

```bash
curl -s https://api.example.com/health
```

```text
{"status":"ok"}
```

Rules:

• Keep a listing under about 30 lines. Cut it to the part that teaches, and say what you cut ("the imports are omitted").
• Make it correct and complete enough to run, or say that it is a sketch.
• Explain the why in the text. Do not narrate the code line by line.
• Use inline code (`name`) for names, commands and values in sentences, and nowhere else.
• Never include keys, passwords, tokens or real personal data. Use obvious placeholders.
• When the point is to explain what the lines do, use an annotated walkthrough, which can point at lines. In a scrollytelling piece a code listing can be the sticky visual that grows.

Mistakes

• A formula with symbols the text never defines.
• A code block with no language, so it is shown without highlighting.
• A 100-line listing that nobody reads. Link to the whole file and show the part that matters.
• Command and output in one block, which cannot be copied cleanly.