You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+59Lines changed: 59 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -76,6 +76,65 @@ static/ # images, CSS, and other static assets
76
76
- Blog post frontmatter uses `tags` as an array: `tags: [tag1, tag2]`.
77
77
- Admonitions use MyST syntax: `:::{note}`, `:::{tip}`, `:::{important}`.
78
78
79
+
## Writing a blog post
80
+
81
+
Blog posts live in `posts/`. Each post is a folder containing an `index.md` plus any images it uses. Adding a post involves creating the post itself and then registering it in a few places so it appears in the site's navigation, blog index, and news feed.
82
+
83
+
### 1. Create the post
84
+
85
+
Make a folder named with the post's URL slug and add an `index.md`:
86
+
87
+
```text
88
+
posts/my-post-slug/index.md
89
+
```
90
+
91
+
Start it with frontmatter:
92
+
93
+
```yaml
94
+
---
95
+
date: 2026-06-16
96
+
title: "Your Post Title"
97
+
description: "One-sentence summary used on the blog card and in the Atom feed."
98
+
author: Author Name
99
+
tags: [tag1, tag2] # optional
100
+
---
101
+
```
102
+
103
+
-`date` (required) drives the newest-first ordering everywhere. Use `YYYY-MM-DD`.
104
+
-`title` and `description` (required) are reused on the blog index card and in the Atom feed.
105
+
- For multiple authors, use a list instead of `author`:
106
+
107
+
```yaml
108
+
authors:
109
+
- First Author
110
+
- Second Author
111
+
```
112
+
113
+
- Put images in the same folder as the post and reference them by filename (e.g. `` or a `:::{figure}` directive). Include descriptive alt text, which both markdownlint and pa11y-ci check for.
114
+
115
+
### 2. Register the post
116
+
117
+
Update these three files so the post is linked from the rest of the site:
| `posts/index.md` | A `:::{card}` block linking to `/posts/my-post-slug`, newest-first. |
122
+
| `myst.yml` | A `- file: posts/my-post-slug/index.md` entry under the Blog section, newest-first. |
123
+
| `news.md` | A short heading and a line linking to the post (only if it's newsworthy). |
124
+
125
+
Copy an existing entry in each file and adjust the title, link, and date.
126
+
127
+
### 3. What updates automatically
128
+
129
+
You do **not** need to touch these; they regenerate from post frontmatter at build time:
130
+
131
+
- **Atom feed** (`scripts/generate-feed.js`, run during `make html`): picks up any `posts/*/index.md` that has a `date` and `title`.
132
+
- **Sitemap**: MyST generates `_build/html/sitemap.xml` on build.
133
+
134
+
### 4. Preview and check
135
+
136
+
Run `make serve` and confirm the post renders, appears on the blog index, and is linked from the sidebar nav. `make html` followed by the link and accessibility checks (see below) catches broken links and missing alt text before you open a PR.
137
+
79
138
## Linting and formatting
80
139
81
140
This project uses [pre-commit](https://pre-commit.com) with:
0 commit comments