Content authoring guide

Best practices for everything under content/.

Writing style

  • No AI slop. Avoid throat-clearing openers, emphasis crutches, business jargon, fragment headers (“The classic.”, “Two flavors.”), meta-commentary (“notice that…”), and lazy extremes (“never”, “always”).
  • No em dashes or double hyphens anywhere in prose. Use commas, colons, or separate sentences (see stop-slop).
  • Active voice, direct statements, varied sentence rhythm.
  • Reference: https://github.com/hardikpandya/stop-slop

Blog posts (blog/)

Create each post as a page bundle (a folder with index.md) so images live beside the post:

content/blog/my-post/
  index.md
  cover.png        # thumbnail, referenced as: thumbnail: "cover.png"

Front matter:

title: "Post title"
date: 2026-06-11
draft: false
description: "One-sentence summary, no em dash."
author: "Spectre"          # an agent name; resolved via data/authors
thumbnail: "cover.png"     # optional; falls back to a branded rings cover
categories: ["Research"]   # drives the listing filter chips
tags: ["supply-chain", "npm"]

Without a thumbnail, the listing shows a branded blue rings cover automatically (layouts/partials/blog-cover.html).

Diagrams

Fenced ```mermaid blocks render as diagrams themed to the Tolmo palette. The runtime loads only on pages that contain one. Use classDef for brand emphasis (e.g. an orange “malicious” terminal node).

Thumbnails

Cover and social templates live in ../assets/images/thumbnails/:

posts/    thumb-01.svg … thumb-10.svg   blog post cover templates
social/   template-post-*.png, linkedin-cover-*.png   social / OG templates

To make a titled blog cover, add the post title as <text> to one of the ring templates (posts/thumb-10.svg is the clean concentric-rings layout) and rasterize it into the post folder:

rsvg-convert -w 1600 cover.svg -o content/blog/my-post/cover.png

Keep covers at the template’s 1747×1111 (≈16:10) aspect. The site-wide social share image is assets/images/og-default.png (see layouts/partials/head.html and the ogImage site param).