|
|
@@ -1,16 +1,74 @@
|
|
|
---
|
|
|
title: Hello, world
|
|
|
-summary: The first post, and a quick tour of what a post can contain.
|
|
|
+summary: The first post, and a guide to writing one — file names, the header block, and what Markdown works.
|
|
|
---
|
|
|
|
|
|
This site is a folder of Markdown files. Each file in `content/` becomes a
|
|
|
-post, and the newest one is listed first.
|
|
|
+post, and the newest one is listed first. This post explains how to write one.
|
|
|
|
|
|
-## What works
|
|
|
+## The file name
|
|
|
+
|
|
|
+Name each post `YYYY-MM-DD-slug.md`, for example `2026-10-24-hello-world.md`.
|
|
|
+
|
|
|
+- The **slug** is the part after the date. It becomes the post's address:
|
|
|
+ this file is served at `/posts/hello-world`.
|
|
|
+- Use lowercase letters, digits and hyphens only. A file with any other name
|
|
|
+ is skipped.
|
|
|
+- The date in the name is the post's date unless the header says otherwise.
|
|
|
+
|
|
|
+## The header block
|
|
|
+
|
|
|
+A post can start with an optional header block (often called *front matter*)
|
|
|
+between two `---` lines. This post's header is:
|
|
|
+
|
|
|
+```markdown
|
|
|
+---
|
|
|
+title: Hello, world
|
|
|
+summary: The first post, and a guide to writing one — file names, the header block, and what Markdown works.
|
|
|
+---
|
|
|
+```
|
|
|
+
|
|
|
+Each line is `key: value`. Four keys are recognised:
|
|
|
+
|
|
|
+| Key | What it does | If left out |
|
|
|
+|---|---|---|
|
|
|
+| `title` | The post's title, shown on the index page, at the top of the post and in the RSS feed | The first line of the post if it is a `# Heading` (that heading is then not repeated in the body); otherwise the slug |
|
|
|
+| `date` | The post's date, as `YYYY-MM-DD`. Posts are listed newest first | The date in the file name |
|
|
|
+| `summary` | One line shown under the title on the index page and used as the RSS description | Nothing is shown |
|
|
|
+| `draft` | Set to `true` to hide the post everywhere: index, post page and feed | `false` |
|
|
|
+
|
|
|
+Some details:
|
|
|
+
|
|
|
+- The block must be the very first thing in the file, and it must be closed
|
|
|
+ with a second `---` line.
|
|
|
+- Values can be wrapped in quotes, which are removed: `title: "Hello, world"`.
|
|
|
+- Lines starting with `#` inside the block are comments.
|
|
|
+- Keys other than the four above are ignored.
|
|
|
+- A post with a broken header, such as an unknown date format or a missing
|
|
|
+ closing `---`, is skipped and the problem is logged. The rest of the site is
|
|
|
+ unaffected.
|
|
|
+
|
|
|
+The header is optional. This is a complete post:
|
|
|
+
|
|
|
+```markdown
|
|
|
+# A short note
|
|
|
+
|
|
|
+Just a paragraph.
|
|
|
+```
|
|
|
+
|
|
|
+Its title is "A short note" and its date comes from the file name.
|
|
|
+
|
|
|
+## Publishing
|
|
|
+
|
|
|
+Posts are reviewed like code: add the file on a branch, open a pull request,
|
|
|
+and the post goes live once it is merged and deployed. To hold a post back
|
|
|
+after merging, set `draft: true`.
|
|
|
+
|
|
|
+## What Markdown works
|
|
|
|
|
|
- **Bold**, *italic*, ~~strikethrough~~ and `inline code`
|
|
|
- Links like https://posts.monoaf.com are linked automatically
|
|
|
-- Tables, task lists and fenced code blocks
|
|
|
+- Headings, lists, quotes, images, tables, task lists and fenced code blocks
|
|
|
|
|
|
| Feature | Supported |
|
|
|
|---|---|
|
Claude