Publishing from plain text

A small publishing system. Markdown goes in; readable, static pages come out.

Example post · Not a Duskfields research result.

On this page

A post should be easy to write, easy to review and easy to keep. This one begins as a Markdown file in the same repository as the website. There is no editor account, content database or rendering service between the file and the page you are reading.

This is an example article, not a research announcement. It doubles as a short guide to the publishing system.

One file per post

Each article lives in site/posts/. The filename becomes its address: publishing-from-plain-text.md produces /posts/publishing-from-plain-text/.

The small block at the top supplies the title, description and publication date. The rest is ordinary Markdown.

yaml
---
title: A useful result
description: What we tried, what changed, and what remains uncertain.
date: 2026-09-23
author: Duskfields
category: Research
draft: true
---

Start with the thing the reader needs to know.

## The experiment

Describe the setup, then the result.

The title appears once, at the top of the page. Start sections with ##, and use ### when a section needs a little more structure.

The page is built once

The generator reads the metadata, renders the Markdown and places the article inside a shared layout. The blog index is built from the same collection of posts, ordered by date.

A Markdown file passes through the static build to produce an article page and a blog index.
One source file feeds both the article and its entry in the blog.

Nothing needs to interpret Markdown when somebody opens a post. Their browser receives HTML, styles and, where useful, a small enhancement such as the code-copy button.

The published page should still be a useful document when JavaScript is unavailable.

That is why the article, its images and its section links are all present in the generated HTML. The optional JavaScript highlights the current section and makes code easier to copy; it does not provide the content.

A short publishing loop

  1. Copy the draft template into a new .md file.
  2. Set a title, description and date. Write the body.
  3. Run the local preview and read the rendered article.
  4. Set draft: false when the post is ready to be included in a deployment.
powershell
.\build.cmd dev

While the preview is running, changes to the post rebuild its HTML. To generate the static pages without starting a server, run build.cmd site.

Formatting should do a job

The page gives different kinds of information different treatments. A quote should read differently from a command. A comparison should be a table when that makes it easier to understand.

ContentMarkdownTreatment
Sections## HeadingLinked headings and a contents list
CodeFenced code blockA scrollable panel with a copy button
ComparisonsA Markdown tableAligned columns and quiet rules
ImagesImage with a titleA responsive figure and caption

Long code lines and wide tables scroll inside their own containers instead of making the whole page wider. The reading column stays at a comfortable width on larger displays and uses the available space on a phone.

Use emphasis for the part that matters. Keep links descriptive, give images useful alt text, and put the explanation close to the thing it explains.

Keep the source, not the output

The generated blog directory is disposable. Edit the Markdown or the shared templates, not the HTML they produce.

  • draft: true excludes a post from the index and generated article pages.
  • Renaming or removing a source removes its old generated page on the next build.
  • Images live under /assets/; missing images fail the build.
  • Raw HTML in a post is displayed as text, not executed.

The mission page and careers pages remain part of the same static website. Publishing a post does not add a server process or change how the site is hosted.


This sample can be replaced or removed. The publishing system does not depend on it.

Keep reading