1 files changed, 103 insertions, 0 deletions
diff --git a/prompts/skills/blog-writing-style/references/gemtext-conventions.md b/prompts/skills/blog-writing-style/references/gemtext-conventions.md
new file mode 100644
index 0000000..6c2178c
--- /dev/null
+++ b/prompts/skills/blog-writing-style/references/gemtext-conventions.md
@@ -0,0 +1,103 @@
+# foo.zone Gemtext Authoring Conventions
+
+Shared conventions for foo.zone blog content. Used by `compose-blog-post`,
+`update-blog-post`, and `blog-writing-style`. Follow these for any `.gmi.tpl`
+(or standalone `.gmi`) authoring or editing.
+
+## File rules
+
+- **Only write or modify `.gmi.tpl` template files** under
+  `~/git/foo.zone-content/gemtext/gemfeed/`.
+- **Never modify a `.gmi` file that has a `.gmi.tpl` counterpart** — those are
+  generated by Gemtexter from the template.
+- Standalone `.gmi` files (no `.tpl`) are usually older posts outside the
+  target window and generally don't need changes.
+- The gemfeed index is `index.gmi.tpl` (edit the template, never `index.gmi`).
+
+## Gemtext format constraints
+
+Gemtext (`.gmi` / `.gmi.tpl`) does **not** support Markdown bold (`**text**`) or
+italic (`*text*`). Gemtexter will not render these. Never use `**...**` or
+`*...*` for emphasis. Instead, rely on sentence structure, word choice, or
+`backticks` for inline emphasis.
+
+- Sections: `##` and `###` (no `#` except the title).
+- Code blocks: triple backticks; list blocks with `*` or `-`.
+- No HTML; plain gemtext only.
+
+## Post structure (in order)
+
+1. `# Title` (first line)
+2. `> Published at YYYY-MM-DDTHH:MM:SS+02:00` (ISO 8601 with timezone)
+3. Optional: ASCII art in a fenced code block (triple backticks) — only if it
+   fits the topic (diagram, device, logo).
+4. Short intro paragraph(s)
+5. First image (if any) and/or main product/external links
+6. **Table of Contents** (see below)
+7. Body with `##` and `###` sections
+8. Optional: "Other related posts:" with `=> ./YYYY-MM-DD-slug.gmi YYYY-MM-DD Title` lines
+9. `E-Mail your comments to \`paul@nospam.buetow.org\` :-)`
+10. `=> ../ Back to the main site` (last line)
+
+## Table of Contents
+
+Add a hand-written TOC after the intro/first image, before the first `##`:
+
+- Heading: `## Table of Contents` then a blank line
+- List with `* ⇢` and indentation by section level:
+  - `* ⇢ Post title` (one arrow = document title)
+  - `* ⇢ ⇢ Section name` (two arrows = each `##` section)
+  - `* ⇢ ⇢ ⇢ Subsection name` (three arrows = each `###` subsection)
+- List every `##` and `###` in the same order as in the body.
+
+## Links
+
+- External: `=> URL Description`
+- Internal/images: `=> ./path Description`
+- **Inline project links.** When the body first mentions an external tool,
+  project, or library by name (e.g. eBPF, libbpf, ClickHouse), add a
+  `=> URL Description` line immediately after that paragraph rather than
+  waiting for a bottom-of-post link block. Bottom blocks are reserved for
+  source repos and related posts.
+
+## Images and diagrams
+
+- Store images in a subfolder under the gemfeed (e.g. `gemfeed/slug-name/`).
+  Reference them as `=> ./slug-name/filename.jpg Description`.
+- Resize large images for web (longest side ~1200px, JPEG quality 85) so the
+  post stays fast to load.
+- **Image density.** Prose-heavy posts with long `##` sections benefit from at
+  least one image or diagram per major section. Walls of text without visual
+  anchors feel dense; when a section runs to several screens of prose, propose
+  a diagram or screenshot to break it up.
+- **ASCII diagrams.** Use a fenced code block (triple backticks). Use Unicode
+  box-drawing characters — `─`, `│`, `▼`, `▶`, `┼`, `┌`, `└`, `┐`, `┘` — for
+  cleaner output than `|` / `-` / `+`.
+  - For two-section comparison diagrams (e.g. kernel vs userspace, before vs
+    after), place a vertical `│` divider at a single fixed column on every
+    row, rather than relying on whitespace alone to separate the sides.
+  - After drafting a multi-column diagram, verify the divider column is
+    identical on every line (e.g. with a small `awk` check) before accepting
+    it. Misaligned dividers are the most common rendering bug.
+  - Anchor labels above content: each section header should sit visually over
+    the column it describes, not floating off to one side.
+
+## Multi-part series
+
+When a post is part of a series (Part 1 / Part 2 / Part 3 …):
+
+- Cross-link to siblings near the top (right after the intro paragraph) and
+  again at the bottom, using the dated filename:
+  `=> ./YYYY-MM-DD-slug-part-N.gmi Part N: short subtitle`.
+- **Shared hero image.** Use the same hero image at the same position
+  (typically immediately after the intro) in every part. Store hero and other
+  shared assets in one subfolder, e.g. `gemfeed/series-slug/`.
+- **Drafts.** Unpublished parts can live as `DRAFT-slug-part-N.gmi.tpl`; their
+  cross-references use `=> ./DRAFT-slug-part-N.gmi`. Promoting a draft to a
+  dated post requires (a) renaming the `.gmi.tpl` and removing the stale
+  generated `.gmi`, then (b) updating every `=> ./DRAFT-…` or
+  `=> ./old-date-…` reference in every OTHER `.gmi.tpl` in the series to point
+  at the new filename. Search with `grep -rn "old-filename" gemtext/` to catch
+  them all.
+- The dated filename controls gemfeed ordering. Fix the filename first, then
+  propagate to references — never the other way around.
+\ No newline at end of file