Writing and formatting ✏️

This post exists to be looked at while writing another one. It covers the formatting that works here and nothing else.

Ordinary things

Bold, italic, inline code, struck through, and links, which pick up the accent colour. Lists work as you would expect:

• Unordered items
• With a second line
  • And a nested one

1. Ordered items
2. Count themselves

A blockquote sits in from the measure with a rule beside it, for when someone else said it better.

Emoji

Type one straight into the text, or write its shortcode and let the server resolve it: :rocket: becomes 🚀, and :tada: becomes 🎉. Shortcodes exist for the times a file is being edited over SSH, where reaching for the emoji picker is not an option. They work in the title, summary and tagline as well as the body.

A shortcode inside backticks or a fenced block is left alone, which is how the examples in this post survive. A name nobody recognises, like :not_an_emoji:, stays spelled out rather than quietly disappearing.

One thing to know when editing a file by hand: a shortcode in the frontmatter has to be quoted, because a bare colon means something else to YAML. Write title: "Writing and formatting :pencil2:". Saving from the admin adds the quotes by itself.

Code

Fenced blocks are highlighted, and follow the page between light and dark:

def publish(path: Path) -> None:
    """Publishing is moving a file. That is the whole deployment."""
    shutil.copy(path, DATA_DIR / "content" / "en" / "blog" / path.name)

Images

A plain image becomes a figure. Add a title in quotes and it becomes the caption:

![A view of the rack](/media/posts/this-post/rack.jpg "The rack, mid-rebuild")

An image can break out of the reading column when it needs the room:

:::full-bleed
![Wide architecture diagram](/media/posts/this-post/diagram.png)
:::

Several images become a grid rather than a vertical stack:

:::gallery{cols=3}
![Before](/media/posts/this-post/before.jpg)
![During](/media/posts/this-post/during.jpg)
![After](/media/posts/this-post/after.jpg)
:::

Every image on the page opens full-screen when clicked, and every one of them is delivered at a size that suits the screen asking for it.

What upload does to a photograph

This is the part worth knowing. When an image is uploaded through the admin it is re-encoded, and the re-encode is what makes it safe to publish:

Step	What happens
Guard	Dimensions are checked before the file is decoded
Resize	Capped at the width chosen at upload time
Strip	All EXIF, IPTC and XMP discarded — including GPS coordinates
Derive	AVIF and WebP at several widths, plus one fallback
Record	Dimensions saved beside the file, so nothing shifts while loading

A photograph taken on a phone knows exactly where it was taken. Publishing it untouched publishes that. Nothing uploaded here keeps its metadata, there is no setting to change that, and the original file is discarded once the variants exist.