Lab Article Style Guide

This is the reference page I can keep open whenever I write for the Lab. It collects the article structure, typography, callout boxes, attachment buttons, media blocks, and small conventions that make separate entries feel like parts of the same website.

Start from the article archetype

Create each entry as a leaf bundle so its future screenshots, documents, and videos can live beside the Markdown file:

hugo new content --kind lab writings/my-article/index.md

Replace writings with projects, library, or experiments. A useful bundle stays predictable:

my-article/
├── index.md
├── images/
│   ├── cover.webp
│   └── diagram.gif
├── files/
│   └── reference.pdf
└── media/
    └── demonstration.mp4

The minimum front matter is:

---
title: "A precise article title"
date: 2026-08-09
draft: true
layout: article
author: Luigi
description: "One useful sentence shown below the title and on Lab cards."
tags: [systems, documentation]
toc: true
mathjax: false
# image: "images/cover.webp"
# image_alt: "Describe the image for someone who cannot see it."
# image_caption: "Optional context or credit."
---

Keep draft: true until the entry is ready. The description should make sense outside the article because it also appears in the Lab feed.

Build a readable hierarchy

Use level-two headings for the main argument and level-three headings inside a long section. Level-five headings have a compact accented treatment that works well for repeated documents, reviews, or catalogue items.

Compact subsection example

This level is useful when several short items need stronger separation than bold text can provide. It should not replace the normal heading hierarchy.

Short paragraphs, lists, and tables create rhythm. A blockquote is reserved for the sentence that frames the problem:

A component earns its place when it makes the next decision easier to understand.

Write the source normally:

> A component earns its place when it makes the next decision easier to understand.

Callout boxes

There are four useful callout treatments. The title is customisable, and the body accepts Markdown.

Copy this pattern and change kind and title:

{{< callout kind="note" title="Context" >}}
The body can contain **Markdown**, links, or a short list.
{{< /callout >}}

Attachment buttons

Use the compact attachment for lecture notes, document lists, and places where the file belongs to a subsection:

{{< attachment compact="true" src="files/reference.pdf" title="Document title" meta="Selected pages for public viewing" >}}

Use the full-size attachment when the download is a primary action in the article:

{{< attachment src="files/reference.pdf" title="Document title" meta="Reference document · 2.4 MB" >}}

The file type is detected automatically and already appears in the square icon, so the subtitle does not need to repeat “PDF”. Add download="true" only when the browser should download instead of opening the file.

Tables and code

Tables work best for comparisons and exact mappings:

Fenced code blocks receive syntax highlighting when a language is specified:

def remaining_budget(baseline, committed, paid):
    return baseline - max(committed, paid)

Inline code such as route.maximumVoltage is for a field, command, path, or exact value—not for visual emphasis.

Images, GIFs, and screenshot spaces

Normal Markdown is enough for images and animated GIFs. Add a quoted title after the path when the image needs a visible caption:

![A concise, meaningful alternative description](images/interface.webp)
![A short animated workflow](images/workflow.gif "Optional caption")

For a site-wide image, start from the root:

Use a gallery for a sequence of related images. The page shows left and right controls; clicking the main image opens a full-screen viewer with arrows and previews. Each source line follows path | alternative text | optional caption:

← →

1 / 3

{{< gallery label="Interface walkthrough" >}}
images/overview.webp | Overview of the interface | Main workspace
images/detail.webp | Detail panel for one item | Editing technical properties
images/result.webp | Completed output | Final result
{{< /gallery >}}

When an article is ready before its screenshot, reserve the intended position visibly:

{{< screenshot-placeholder title="Main interface overview" note="What the future screenshot should demonstrate." caption="Optional figure caption." >}}

Embedded PDFs and video

Embed a PDF only when reading it inside the page is genuinely useful; otherwise prefer an attachment button:

{{< pdf src="files/reference.pdf" title="Reference document" >}}

Videos use a local file and can include a poster image and caption:

{{< video src="media/demo.mp4" poster="images/poster.webp" caption="A short demonstration." type="video/mp4" >}}

Keeping media inside the page bundle makes moving or archiving the article much safer.

Equations

Set mathjax: true in the front matter when an article needs mathematics. Inline notation uses \( C_{forecast} \) and a display equation uses:

$$ C_{forecast} = C_{paid} + C_{committed} + C_{remaining} + C_{contingency} $$

Do not enable MathJax on articles that do not use it.

Final publishing checklist

Before changing draft to false, check that:

• the description works on a Lab card;
• headings describe the argument rather than the layout;
• every image has useful alternative text;
• callouts contain actual decisions, context, or constraints;
• document labels do not repeat their file type;
• links and attachment paths resolve;
• screenshots do not expose private information;
• the conclusion adds limits, next steps, or a changed decision instead of repeating the introduction.