Skip to content

Commit 976879f

Browse files
authored
Add blog post authoring section to README (#338)
1 parent c5465a3 commit 976879f

1 file changed

Lines changed: 59 additions & 0 deletions

File tree

README.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,65 @@ static/ # images, CSS, and other static assets
7676
- Blog post frontmatter uses `tags` as an array: `tags: [tag1, tag2]`.
7777
- Admonitions use MyST syntax: `:::{note}`, `:::{tip}`, `:::{important}`.
7878

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. `![Alt text](my-image.png)` 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:
118+
119+
| File | What to add |
120+
| ---------------- | ----------------------------------------------------------------------------------- |
121+
| `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+
79138
## Linting and formatting
80139

81140
This project uses [pre-commit](https://pre-commit.com) with:

0 commit comments

Comments
 (0)