Sebastian KaiserA personal engineering notebook

The notebook Guide

Publishing from Org

A note in Emacs and a page on the web serve different purposes. The useful question is not whether they look identical, but whether the structure, examples, and connections that make the note useful survive the journey.

This guide connects two working examples in the notebook. Start with the publishing fixture to inspect individual features, then read the Rust article to see those features supporting an explanation.

Inspect the publishing surface

The Org-mode publishing showcase deliberately puts headings, tables, task states, inline formatting, and source blocks together. It is the place to look when asking a narrow question: does this part of an Org document still make sense after export?

The route here is Org → ox-hugo Markdown → Berlin’s semantic document → HTML. Each stage has a different responsibility. Emacs remains the authoring environment; the published page does not reproduce folding, agendas, or capture workflows. The showcase documents examples, not a promise of support for every Org feature.

Read an example in context

Processing JSON with Rust is a learning exercise rather than a publishing test. Read it for the relationship between the prose, the source listings, and the medal results. Code references let an explanation point to a precise part of a listing without turning the whole article into a wall of code.

The worked medal pipeline also makes a useful distinction visible: showing the steps of an execution is not the same as executing a program in the reader’s browser. Stored Org results can accompany source code; Berlin’s publishing export does not execute the code blocks again.

Keep the connections in the source

The links above are Org ID links. Their targets are document identities, not hand-maintained HTML filenames. Berlin resolves them against the published collection and derives backlinks to the passages that refer to each note.

That division keeps two different kinds of organisation separate. Tags gather material with shared labels. A guide chooses a route through that material and explains why each stop belongs. The explanation remains ordinary prose, so it can change as the notebook grows.

Read another author’s workflow

Dominik Honnef’s My org-roam workflows for taking notes and writing articles describes a broader system connecting notes, references, and web publication. His use of category notes is especially relevant here: a category can contain an explanation as well as collect links. It offers a useful comparison, not a description of the configuration used by this website.

Questions to explore next

These two questions are starting points for further investigation, not completed experiments. Each connects something already in the notebook to a small next step.

What would make a stored result reproducible?

The worked example in Processing JSON with Rust places a small input beside its extraction, counting, and ranking results. That makes the explanation inspectable. It does not, by itself, establish that another environment will produce the same result.

The uncertainty is what needs to accompany the stored output: the exact input, source listings, dependency lockfile, Rust toolchain, and execution command are a starting point. Is that enough to reproduce this particular example?

A small experiment would be to use a disposable copy of the example, record those inputs, and compare a fresh execution with the stored table. Then change one medal in the small input and regenerate the results. Record what changed and whether the explanation still matches. Run this explicitly during authoring; the publishing export should continue to use stored results.

The useful follow-up would be a short note containing the recorded setup, comparison, and any mismatch—not a claim of reproducibility before trying it.

Where should a guide end and a note begin?

This guide introduces both the publishing showcase and the Rust learning exercise. The uncertainty is how much orientation belongs here without repeating the explanations in those notes.

A small reading exercise would be to follow the links with two different questions: “Which Org features can I inspect?” and “How do code references support an explanation?” For each route, record the first place where context is missing or unnecessarily repeated. Put route-finding context in the guide and keep the technical explanation beside its example.

The result may be only a revised paragraph or a better link. A separate note is useful when there is an observation worth explaining, not just to fill out the collection.