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.
---
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.
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
- Copy the draft template into a new
.mdfile. - Set a title, description and date. Write the body.
- Run the local preview and read the rendered article.
- Set
draft: falsewhen the post is ready to be included in a deployment.
.\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.
| Content | Markdown | Treatment |
|---|---|---|
| Sections | ## Heading | Linked headings and a contents list |
| Code | Fenced code block | A scrollable panel with a copy button |
| Comparisons | A Markdown table | Aligned columns and quiet rules |
| Images | Image with a title | A 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: trueexcludes 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.