Blog Writing
Overview
Write blog posts that match this blog's voice: second person, direct, instructional, culturally grounded with Anishinaabemowin greetings. Reference post: content/posts/laravel-boost-ddev.md. Full style guide: docs/blog-style.md.
Style Rules (Canonical Authority)
| Element |
Rule |
| Greeting |
Always open with "Ahnii!" (exclamation mark, own paragraph) |
| Farewell |
Always close with "Baamaapii" (no emoji, own paragraph) |
| Voice |
Second person, direct, instructional. Address reader as "you"/"your". Not corporate. |
| Concise |
Short sentences. One idea per paragraph. No filler or throat-clearing. |
| Scoped intro |
In the intro, state what the post covers in one sentence. Cover the relevant W's: What (what you'll learn), Why (why it matters or what problem it solves), Who (who it's for, if not obvious). How is the body. When/Where are rarely relevant for technical posts. Not all W's apply — use judgment. |
| Code blocks |
Always specify language tag. After each block, add 1-2 sentences explaining what it does or why. For error output, reformat for readability — don't carbon-copy terminal noise. |
| Links |
Link first mention of products, tools, or projects. Internal: use relref (e.g., {{< relref "post-slug" >}}), never root-relative paths (the /blog/ base path breaks them). External: full HTTPS URLs. |
| Headings |
H2 for main sections, H3 for variants/subsections. No time estimates. No "Wrapping Up" or "Conclusion". Use SEO-friendly headings with keywords (e.g., "Fix WSL Browser Hangs With BROWSER=echo" not "The Fix"). |
| Em dashes |
Use sparingly and on purpose. Heavy "—" usage reads as AI-written. Prefer periods (two short sentences), colons, or commas. One or two per post is enough; zero is fine. |
| Contrast constructions |
Don't keep reaching for "X is not Y, it is Z." Once can work. Repetition reads formulaic and AI-written. If the point lands better as a direct sentence, write the direct sentence. |
| Negative framing |
Avoid stacking "do not," "does not," "not enough," or repeated "instead of" moves when the direct sentence would be clearer. "Put the defaults in the repo" is better than "keep defaults in the repo instead of your head." |
| Sentence variety |
Mix short and medium sentences so the post has rhythm. Avoid sections where every sentence lands at the same length or every paragraph follows the same beat. |
| Filler and jargon |
Cut generic AI-sounding words such as "robust," "seamless," "transformative," "game-changing," and "momentum" unless the term is concrete and necessary. Say what the thing does. |
| Section transitions |
End each section with a sentence that creates a reason to read the next one. Open questions, unresolved tension, or a "but" that the next section resolves. Don't let the reader stop comfortably between sections. |
| No redundant explanation |
Don't re-explain a problem the intro already established. If the reader came here because they have the problem, get to the fix. |
| Diagrams |
When explaining flows, pipelines, or relationships between components, use a Mermaid diagram instead of (or alongside) prose. A ```mermaid code block renders natively. Use diagrams for: request/response flows, architecture layers, state machines, data pipelines. Don't use diagrams for: simple lists, single-step processes, or anything that's clearer as a sentence. |
| Explain before naming |
Before introducing a named concept (interface, class, pattern), explain what it does in plain language. "A domain router owns one slice of request handling" before showing DomainRouterInterface. The reader needs the "what" before the "how." |
| Show, don't describe |
If you're writing a sentence like "the handle() method routes to X, Y, and Z", put X/Y/Z in the code example instead. Prose that narrates what code does is redundant when the code is right there. Combine the description into the code block. |
| Back up claims with code |
Every behavioral claim ("you can add a new action without changing X") needs an example showing it. If you can't show it, reconsider whether the claim is accurate. |
| Prefer direct imperatives |
When you are teaching, prefer direct instructions over contrast setup. Write "Verify the workflow on a fresh shell" rather than "Do not trust the workflow because it looks tidy." |
Frontmatter (Required Fields)
---
title: "Post Title" # sentence case, descriptive
date: YYYY-MM-DD
categories: [] # lowercase, hyphenated for multi-word
tags: [] # max 4 tags
summary: "" # one sentence: outcome or audience
slug: "url-slug" # kebab-case
draft: true
---
For series posts, add: series: ["series-name"]
File Output
Write the primary post artifact as a Hugo leaf bundle:
- Primary file:
content/posts/{slug}/index.md
- Use the same
slug from frontmatter for the directory name
- Do not write standalone post files like
content/posts/{slug}.md
- Frontmatter comes first in the file.
Ahnii! is the first content paragraph after frontmatter, not before it.
Post Type: General
Use for standalone posts (tutorials, tools, project showcases).
Ahnii!
[Intro: what the thing is (link first mentions) + one sentence on scope]
## Prerequisites
- [Requirement 1]
- [Requirement 2]
## [Main Section]
[Content with code examples]
[After each code block: 1-2 sentences explaining what it does]
## [Additional Sections as needed]
[Use H3 for variants, e.g. "Standard Setup" / "WSL Setup"]
## [Verify / Follow-up section when relevant]
[e.g. "Verify It Works", "Keeping X Updated"]
Baamaapii
Post Type: Series Index
Use for the landing page of a multi-part series. Every series gets one index post at series_order: 0.
Additional frontmatter:
series: ["series-name"]
series_order: 0
Structure:
Ahnii!
[1-2 sentence intro: what the series covers + who it's for]
### 1. [Post Title]({{< relref "post-slug" >}})
[1-2 sentence description of what the post covers]
### 2. [Post Title]({{< relref "post-slug" >}})
[1-2 sentence description]
### 3. Post Title
[1-2 sentence description — plain text because the post is future-dated]
...
[Optional closing sentence, e.g. "Each post stands alone — start wherever you need."]
Baamaapii
TOC rules:
| Rule |
Detail |
| Format |
Numbered H3 headings, one per post in series_order |
| Published posts |
Use relref links: [Title]({{< relref "slug" >}}) |
| Future-dated posts |
Plain text only — relref fails without --buildFuture |
| Descriptions |
1-2 sentences per entry describing what the post covers |
| Maintenance |
Convert plain text to relref links as posts publish |
Post Type: Series
Use for posts in a multi-part series (e.g., PSR php-fig-standards series).
Ahnii!
> **Prerequisites:** [requirements]. **Recommended:** Read [Link](/slug/) first. **Pairs with:** [related posts].
[Intro: what this standard/topic is + one sentence on scope]
## What Problem Does [Topic] Solve?
[Why this matters — the "before" pain point]
## Core Interfaces / Core Concepts
### 1. [First Concept]
[Code with inline comments]
[1-2 sentences explaining the code]
### 2. [Second Concept]
[Code with inline comments]
[1-2 sentences explaining the code]
## Real-World Implementation
[Working code example — practical, not theoretical]
[Explanation of what the code does]
## Common Mistakes and Fixes
### 1. [Mistake]
[Bad code → Good code with comments explaining why]
### 2. [Mistake]
[Bad code → Good code]
## Framework Integration
### [Framework 1]
[Code example + explanation]
### [Framework 2]
[Code example + explanation]
## Try It Yourself
[Commands to run from companion repo or hands-on steps]
## What's Next
[Link to next post in series with brief description]
Baamaapii
Screenshots
When a post covers UI, web tools, or anything visual, use the Playwright MCP to capture screenshots.
When to Include Screenshots
- Documentation or dashboard walkthroughs
- Before/after UI changes
- Error messages in browser dev tools
- OAuth flows or login screens
- Any step where "what you should see" helps the reader
How to Capture
- Use
browser_navigate to load the page
- Use
browser_take_screenshot to capture:
filename: Save to static/images/posts/{slug}/ with descriptive namefullPage: true for full-page captures when neededelement + ref to screenshot a specific element (get ref from browser_snapshot)
In the Post
Note: The /blog/ prefix is required because the site's baseURL is https://jonesrussell.github.io/blog/. Without it, images break in both local dev and production.
Add a brief caption or follow with 1-2 sentences explaining what the reader should notice.
Social media artifact
After creating or updating a post, generate a companion markdown file with ready-to-paste copy for different platforms. The file lets you share the post with the canonical link in the body so Open Graph (OG) can fetch title, description, and image when the link is shared.
Where to put it
- Path:
docs/social/{slug}.md (same slug as the post).
- Create or overwrite this file whenever you create or substantially update a post.
Canonical URL
- Use the full post URL:
https://jonesrussell.github.io/blog/{slug}/.
- Include it in every platform block so OG does its job when the link is previewed.
File structure
Use this structure in the artifact. Keep platform copy concise; the link drives the preview.
# Social copy: [Post Title]
**Canonical URL:** https://jonesrussell.github.io/blog/{slug}/
## Facebook
[1–3 sentences hook + link. No strict limit.]
## X (Twitter)
[Short hook, under ~240 chars including URL. Put link at end.]
## LinkedIn
[Professional one-liner or short paragraph + link. Tone fits LinkedIn.]
Platform notes
- Facebook: Longer copy is fine. One or two sentences plus the link. Include hashtags. No character limit to target.
- X (Twitter): Stay under ~240 characters including the URL so it fits one tweet; put the link at the end.
- LinkedIn: One or two sentences, more professional tone; include the link. No hashtags on LinkedIn.
Always include the canonical URL in each block so the platform can unfurl it and OG works.
Accuracy Verification
After writing or updating a post, verify all claims before publishing. Run every check — do not skip items.
| Check |
How |
| Code blocks compile/run |
Verify syntax is correct. If referencing a real repo, read the actual source and confirm the code matches. |
| Tool/product names |
Verify tools exist and names are spelled correctly. |
| Links resolve |
Internal links: confirm a post with that slug exists. External links: confirm the URL is valid. |
| Behavioral claims |
"This does X" or "the output looks like this" — verify against actual behavior by running the command or reading the source. |
| Config/file references |
If the post says "add this to Taskfile.yml" or "your lefthook config", verify the file exists and the format matches the real project. |
| State claims |
If the post describes something as already implemented ("I wired X into Y"), verify it actually exists in the referenced repo. Do not present aspirational state as current state. |
Visual Components
The blog has six Hugo shortcodes for breaking up walls of text. Use them when they add information; never use them for decoration. Walls of decoration are worse than walls of text.
Spec and rules: docs/superpowers/specs/2026-04-06-blog-visual-components-design.md
| Shortcode |
Syntax |
Use when |
Don't use when |
callout |
{{</* callout type="info" */>}}body{{</* /callout */>}} (types: info, warning, tip, note, success) |
Asides, gotchas, version notes, prerequisites |
General emphasis, decorating prose |
steps |
{{</* steps */>}} containing {{</* step "Title" */>}}body{{</* /step */>}} |
Sequential processes with 3+ steps where each step has explanation |
Short flat lists, non-sequential items |
pullquote |
{{</* pullquote */>}}line{{</* /pullquote */>}} |
The post's killer line. Max one per post. |
Decoration, quoting other authors (use > instead) |
cta |
{{</* cta title="..." button="..." href="..." */>}}body{{</* /cta */>}} |
Single concrete action at a meaningful break. Max one per post. |
Vague "learn more" links, newsletter signup |
stats |
{{</* stats */>}} containing {{</* stat "N" "Label" */>}} |
Posts where metrics are central |
Posts without real metrics, single-stat scenarios |
compare |
{{</* compare */>}}{{</* before */>}}…{{</* /before */>}}{{</* after */>}}…{{</* /after */>}}{{</* /compare */>}} |
Old way vs new way framings, refactor before/after |
Arbitrary contrasts, three-way comparisons |
Universal rule: If a component doesn't add information, remove it.
Common Mistakes
| Mistake |
Fix |
| Adding emoji to farewell |
Farewell is "Baamaapii" — no emoji |
| First-person voice |
Use second person: "your project", "you can" — not "I found", "my setup" |
| No explanation after code blocks |
After every code block, add 1-2 sentences on what it does or why |
| Not linking first mentions |
Link products/tools/projects on first mention |
| Generic closing ("Wrapping Up", "Conclusion") |
No closing header — transition naturally to farewell |
| Time estimates in headings |
Don't add reading time to headings |
| More than 4 tags |
Pick the 4 most relevant; fewer is fine |
Using description field |
Use summary in frontmatter, not description |
| Filler in intro |
State what the post covers in one sentence. No throat-clearing. |
| Generic headings |
Use descriptive, keyword-rich headings. "Why CLI Tools Hang in WSL" not "The Problem". |
| Carbon-copy terminal output |
Reformat error output for readability. Break long lines, remove noise, keep the key details. |
| Too narrow scope |
If a fix applies broadly, generalize the post. Cover the pattern, not just one tool. |
| Overusing em dashes (—) |
Replace with periods (split into two sentences), colons, or commas. Heavy dash use reads as AI slop. |
| Fabricated code snippets |
When a post references real repos, verify every interface signature, method name, and class name against the actual source in ~/dev/. AI-generated code is frequently hallucinated. |
| Casual/clickbait phrasing |
Avoid phrases like "without losing your mind" or "you won't believe". Use direct, professional language. |
| Root-relative internal links |
Use relref, not /slug/. Root-relative paths don't account for the /blog/ base path and produce 404s. |
| Flat section transitions |
Don't end a section and start the next with no pull-through. End with tension, an open question, or a "but" that makes the next heading feel like the answer. |
| Re-explaining the problem after the intro |
If the intro establishes why the reader is here, don't spend the next section repeating it. Get to the fix. |
| Documentary announcing pattern |
Don't open sections with "Two files do most of the work" or "The template." Lead with what the reader needs to know or a question they need answered, not a table of contents for the section. |
| Adding components for visual interest rather than information |
Remove the component. Walls of decoration are worse than walls of text. |
| More than one pullquote or cta per post |
Pick the strongest one and delete the rest. Two CTAs means two purposes — split the post. |
| Wordy explanations of visual concepts |
If you're writing 3+ sentences to describe a flow, pipeline, or component relationship, replace the prose with a Mermaid diagram. Diagrams communicate structure faster than paragraphs. |
| Naming things without explaining them |
Don't drop a class/interface name as a section heading and jump straight to code. Open with 1-2 sentences explaining what it is and why the reader should care. |
| Narrating code instead of showing it |
"The method does A, B, and C" followed by a code block that shows A, B, and C. Delete the narration and let the code speak, or fold the explanation into the code as comments. |
| Unverified behavioral claims |
"You can't disable the last entity type without a force flag" sounds great but must exist in the actual source. Every claim about what code does must be verified. |
| Repeating "X is not Y, it is Z." style lines |
Keep the move if it earns emphasis once. If the draft keeps using that contrast shape, rewrite most of them as direct statements. |
| Flat sentence cadence |
If three or four sentences in a row land with the same rhythm, vary the length and structure. A blog post should sound intentional, not metronomic. |
| Generic AI-jargon filler |
Replace vague language like "robust," "seamless," "transformative," or "momentum" with the exact behavior, outcome, or tradeoff. |
1---2name: blog-writing3description: Use when creating new blog posts, drafting content, or writing articles for this Hugo blog. Triggers include requests to write, draft, or create a post.4---56# Blog Writing78## Overview910Write blog posts that match this blog's voice: second person, direct, instructional, culturally grounded with Anishinaabemowin greetings. Reference post: `content/posts/laravel-boost-ddev.md`. Full style guide: `docs/blog-style.md`.1112## Style Rules (Canonical Authority)1314| Element | Rule |15|---------|------|16| Greeting | Always open with "Ahnii!" (exclamation mark, own paragraph) |17| Farewell | Always close with "Baamaapii" (no emoji, own paragraph) |18| Voice | Second person, direct, instructional. Address reader as "you"/"your". Not corporate. |19| Concise | Short sentences. One idea per paragraph. No filler or throat-clearing. |20| Scoped intro | In the intro, state what the post covers in one sentence. Cover the relevant W's: **What** (what you'll learn), **Why** (why it matters or what problem it solves), **Who** (who it's for, if not obvious). **How** is the body. When/Where are rarely relevant for technical posts. Not all W's apply — use judgment. |21| Code blocks | Always specify language tag. After each block, add 1-2 sentences explaining what it does or why. For error output, reformat for readability — don't carbon-copy terminal noise. |22| Links | Link first mention of products, tools, or projects. Internal: use `relref` (e.g., `{{< relref "post-slug" >}}`), never root-relative paths (the `/blog/` base path breaks them). External: full HTTPS URLs. |23| Headings | H2 for main sections, H3 for variants/subsections. No time estimates. No "Wrapping Up" or "Conclusion". Use SEO-friendly headings with keywords (e.g., "Fix WSL Browser Hangs With BROWSER=echo" not "The Fix"). |24| Em dashes | Use sparingly and on purpose. Heavy "—" usage reads as AI-written. Prefer periods (two short sentences), colons, or commas. One or two per post is enough; zero is fine. |25| Contrast constructions | Don't keep reaching for "X is not Y, it is Z." Once can work. Repetition reads formulaic and AI-written. If the point lands better as a direct sentence, write the direct sentence. |26| Negative framing | Avoid stacking "do not," "does not," "not enough," or repeated "instead of" moves when the direct sentence would be clearer. "Put the defaults in the repo" is better than "keep defaults in the repo instead of your head." |27| Sentence variety | Mix short and medium sentences so the post has rhythm. Avoid sections where every sentence lands at the same length or every paragraph follows the same beat. |28| Filler and jargon | Cut generic AI-sounding words such as "robust," "seamless," "transformative," "game-changing," and "momentum" unless the term is concrete and necessary. Say what the thing does. |29| Section transitions | End each section with a sentence that creates a reason to read the next one. Open questions, unresolved tension, or a "but" that the next section resolves. Don't let the reader stop comfortably between sections. |30| No redundant explanation | Don't re-explain a problem the intro already established. If the reader came here because they have the problem, get to the fix. |31| Diagrams | When explaining flows, pipelines, or relationships between components, use a Mermaid diagram instead of (or alongside) prose. A ```` ```mermaid ```` code block renders natively. Use diagrams for: request/response flows, architecture layers, state machines, data pipelines. Don't use diagrams for: simple lists, single-step processes, or anything that's clearer as a sentence. |32| Explain before naming | Before introducing a named concept (interface, class, pattern), explain what it does in plain language. "A domain router owns one slice of request handling" before showing `DomainRouterInterface`. The reader needs the "what" before the "how." |33| Show, don't describe | If you're writing a sentence like "the handle() method routes to X, Y, and Z", put X/Y/Z in the code example instead. Prose that narrates what code does is redundant when the code is right there. Combine the description into the code block. |34| Back up claims with code | Every behavioral claim ("you can add a new action without changing X") needs an example showing it. If you can't show it, reconsider whether the claim is accurate. |35| Prefer direct imperatives | When you are teaching, prefer direct instructions over contrast setup. Write "Verify the workflow on a fresh shell" rather than "Do not trust the workflow because it looks tidy." |3637## Frontmatter (Required Fields)3839```yaml40---41title: "Post Title" # sentence case, descriptive42date: YYYY-MM-DD43categories: [] # lowercase, hyphenated for multi-word44tags: [] # max 4 tags45summary: "" # one sentence: outcome or audience46slug: "url-slug" # kebab-case47draft: true48---49```5051For series posts, add: `series: ["series-name"]`5253## File Output5455Write the primary post artifact as a Hugo leaf bundle:5657- Primary file: `content/posts/{slug}/index.md`58- Use the same `slug` from frontmatter for the directory name59- Do not write standalone post files like `content/posts/{slug}.md`60- Frontmatter comes first in the file. `Ahnii!` is the first content paragraph after frontmatter, not before it.6162## Post Type: General6364Use for standalone posts (tutorials, tools, project showcases).6566```67Ahnii!6869[Intro: what the thing is (link first mentions) + one sentence on scope]7071## Prerequisites7273- [Requirement 1]74- [Requirement 2]7576## [Main Section]7778[Content with code examples]79[After each code block: 1-2 sentences explaining what it does]8081## [Additional Sections as needed]8283[Use H3 for variants, e.g. "Standard Setup" / "WSL Setup"]8485## [Verify / Follow-up section when relevant]8687[e.g. "Verify It Works", "Keeping X Updated"]8889Baamaapii90```9192## Post Type: Series Index9394Use for the landing page of a multi-part series. Every series gets one index post at `series_order: 0`.9596**Additional frontmatter:**9798```yaml99series: ["series-name"]100series_order: 0101```102103**Structure:**104105```106Ahnii!107108[1-2 sentence intro: what the series covers + who it's for]109110### 1. [Post Title]({{< relref "post-slug" >}})111112[1-2 sentence description of what the post covers]113114### 2. [Post Title]({{< relref "post-slug" >}})115116[1-2 sentence description]117118### 3. Post Title119120[1-2 sentence description — plain text because the post is future-dated]121122...123124[Optional closing sentence, e.g. "Each post stands alone — start wherever you need."]125126Baamaapii127```128129**TOC rules:**130131| Rule | Detail |132|------|--------|133| Format | Numbered H3 headings, one per post in `series_order` |134| Published posts | Use `relref` links: `[Title]({{< relref "slug" >}})` |135| Future-dated posts | Plain text only — `relref` fails without `--buildFuture` |136| Descriptions | 1-2 sentences per entry describing what the post covers |137| Maintenance | Convert plain text to `relref` links as posts publish |138139## Post Type: Series140141Use for posts in a multi-part series (e.g., PSR php-fig-standards series).142143```144Ahnii!145146> **Prerequisites:** [requirements]. **Recommended:** Read [Link](/slug/) first. **Pairs with:** [related posts].147148[Intro: what this standard/topic is + one sentence on scope]149150## What Problem Does [Topic] Solve?151152[Why this matters — the "before" pain point]153154## Core Interfaces / Core Concepts155156### 1. [First Concept]157[Code with inline comments]158[1-2 sentences explaining the code]159160### 2. [Second Concept]161[Code with inline comments]162[1-2 sentences explaining the code]163164## Real-World Implementation165166[Working code example — practical, not theoretical]167[Explanation of what the code does]168169## Common Mistakes and Fixes170171### 1. [Mistake]172[Bad code → Good code with comments explaining why]173174### 2. [Mistake]175[Bad code → Good code]176177## Framework Integration178179### [Framework 1]180[Code example + explanation]181182### [Framework 2]183[Code example + explanation]184185## Try It Yourself186187[Commands to run from companion repo or hands-on steps]188189## What's Next190191[Link to next post in series with brief description]192193Baamaapii194```195196## Screenshots197198When a post covers UI, web tools, or anything visual, use the Playwright MCP to capture screenshots.199200### When to Include Screenshots201202- Documentation or dashboard walkthroughs203- Before/after UI changes204- Error messages in browser dev tools205- OAuth flows or login screens206- Any step where "what you should see" helps the reader207208### How to Capture2092101. Use `browser_navigate` to load the page2112. Use `browser_take_screenshot` to capture:212 - `filename`: Save to `static/images/posts/{slug}/` with descriptive name213 - `fullPage: true` for full-page captures when needed214 - `element` + `ref` to screenshot a specific element (get ref from `browser_snapshot`)215216### In the Post217218```markdown219220```221222Note: The `/blog/` prefix is required because the site's baseURL is `https://jonesrussell.github.io/blog/`. Without it, images break in both local dev and production.223224Add a brief caption or follow with 1-2 sentences explaining what the reader should notice.225226## Social media artifact227228After creating or updating a post, generate a **companion markdown file** with ready-to-paste copy for different platforms. The file lets you share the post with the canonical link in the body so Open Graph (OG) can fetch title, description, and image when the link is shared.229230### Where to put it231232- Path: `docs/social/{slug}.md` (same `slug` as the post).233- Create or overwrite this file whenever you create or substantially update a post.234235### Canonical URL236237- Use the full post URL: `https://jonesrussell.github.io/blog/{slug}/`.238- Include it in every platform block so OG does its job when the link is previewed.239240### File structure241242Use this structure in the artifact. Keep platform copy concise; the link drives the preview.243244```markdown245# Social copy: [Post Title]246247**Canonical URL:** https://jonesrussell.github.io/blog/{slug}/248249## Facebook250251[1–3 sentences hook + link. No strict limit.]252253## X (Twitter)254255[Short hook, under ~240 chars including URL. Put link at end.]256257## LinkedIn258259[Professional one-liner or short paragraph + link. Tone fits LinkedIn.]260```261262### Platform notes263264- **Facebook:** Longer copy is fine. One or two sentences plus the link. Include hashtags. No character limit to target.265- **X (Twitter):** Stay under ~240 characters including the URL so it fits one tweet; put the link at the end.266- **LinkedIn:** One or two sentences, more professional tone; include the link. No hashtags on LinkedIn.267268Always include the **canonical URL** in each block so the platform can unfurl it and OG works.269270## Accuracy Verification271272After writing or updating a post, verify all claims before publishing. Run every check — do not skip items.273274| Check | How |275|-------|-----|276| Code blocks compile/run | Verify syntax is correct. If referencing a real repo, read the actual source and confirm the code matches. |277| Tool/product names | Verify tools exist and names are spelled correctly. |278| Links resolve | Internal links: confirm a post with that slug exists. External links: confirm the URL is valid. |279| Behavioral claims | "This does X" or "the output looks like this" — verify against actual behavior by running the command or reading the source. |280| Config/file references | If the post says "add this to Taskfile.yml" or "your lefthook config", verify the file exists and the format matches the real project. |281| State claims | If the post describes something as already implemented ("I wired X into Y"), verify it actually exists in the referenced repo. Do not present aspirational state as current state. |282283## Visual Components284285The blog has six Hugo shortcodes for breaking up walls of text. Use them when they add information; never use them for decoration. Walls of decoration are worse than walls of text.286287Spec and rules: `docs/superpowers/specs/2026-04-06-blog-visual-components-design.md`288289| Shortcode | Syntax | Use when | Don't use when |290|-----------|--------|----------|----------------|291| `callout` | `{{</* callout type="info" */>}}body{{</* /callout */>}}` (types: info, warning, tip, note, success) | Asides, gotchas, version notes, prerequisites | General emphasis, decorating prose |292| `steps` | `{{</* steps */>}}` containing `{{</* step "Title" */>}}body{{</* /step */>}}` | Sequential processes with 3+ steps where each step has explanation | Short flat lists, non-sequential items |293| `pullquote` | `{{</* pullquote */>}}line{{</* /pullquote */>}}` | The post's killer line. **Max one per post.** | Decoration, quoting other authors (use `> ` instead) |294| `cta` | `{{</* cta title="..." button="..." href="..." */>}}body{{</* /cta */>}}` | Single concrete action at a meaningful break. **Max one per post.** | Vague "learn more" links, newsletter signup |295| `stats` | `{{</* stats */>}}` containing `{{</* stat "N" "Label" */>}}` | Posts where metrics are central | Posts without real metrics, single-stat scenarios |296| `compare` | `{{</* compare */>}}{{</* before */>}}…{{</* /before */>}}{{</* after */>}}…{{</* /after */>}}{{</* /compare */>}}` | Old way vs new way framings, refactor before/after | Arbitrary contrasts, three-way comparisons |297298**Universal rule:** If a component doesn't add information, remove it.299300## Common Mistakes301302| Mistake | Fix |303|---------|-----|304| Adding emoji to farewell | Farewell is "Baamaapii" — no emoji |305| First-person voice | Use second person: "your project", "you can" — not "I found", "my setup" |306| No explanation after code blocks | After every code block, add 1-2 sentences on what it does or why |307| Not linking first mentions | Link products/tools/projects on first mention |308| Generic closing ("Wrapping Up", "Conclusion") | No closing header — transition naturally to farewell |309| Time estimates in headings | Don't add reading time to headings |310| More than 4 tags | Pick the 4 most relevant; fewer is fine |311| Using `description` field | Use `summary` in frontmatter, not `description` |312| Filler in intro | State what the post covers in one sentence. No throat-clearing. |313| Generic headings | Use descriptive, keyword-rich headings. "Why CLI Tools Hang in WSL" not "The Problem". |314| Carbon-copy terminal output | Reformat error output for readability. Break long lines, remove noise, keep the key details. |315| Too narrow scope | If a fix applies broadly, generalize the post. Cover the pattern, not just one tool. |316| Overusing em dashes (—) | Replace with periods (split into two sentences), colons, or commas. Heavy dash use reads as AI slop. |317| Fabricated code snippets | When a post references real repos, verify every interface signature, method name, and class name against the actual source in `~/dev/`. AI-generated code is frequently hallucinated. |318| Casual/clickbait phrasing | Avoid phrases like "without losing your mind" or "you won't believe". Use direct, professional language. |319| Root-relative internal links | Use `relref`, not `/slug/`. Root-relative paths don't account for the `/blog/` base path and produce 404s. |320| Flat section transitions | Don't end a section and start the next with no pull-through. End with tension, an open question, or a "but" that makes the next heading feel like the answer. |321| Re-explaining the problem after the intro | If the intro establishes why the reader is here, don't spend the next section repeating it. Get to the fix. |322| Documentary announcing pattern | Don't open sections with "Two files do most of the work" or "The template." Lead with what the reader needs to know or a question they need answered, not a table of contents for the section. |323| Adding components for visual interest rather than information | Remove the component. Walls of decoration are worse than walls of text. |324| More than one pullquote or cta per post | Pick the strongest one and delete the rest. Two CTAs means two purposes — split the post. |325| Wordy explanations of visual concepts | If you're writing 3+ sentences to describe a flow, pipeline, or component relationship, replace the prose with a Mermaid diagram. Diagrams communicate structure faster than paragraphs. |326| Naming things without explaining them | Don't drop a class/interface name as a section heading and jump straight to code. Open with 1-2 sentences explaining what it is and why the reader should care. |327| Narrating code instead of showing it | "The method does A, B, and C" followed by a code block that shows A, B, and C. Delete the narration and let the code speak, or fold the explanation into the code as comments. |328| Unverified behavioral claims | "You can't disable the last entity type without a force flag" sounds great but must exist in the actual source. Every claim about what code does must be verified. |329| Repeating "X is not Y, it is Z." style lines | Keep the move if it earns emphasis once. If the draft keeps using that contrast shape, rewrite most of them as direct statements. |330| Flat sentence cadence | If three or four sentences in a row land with the same rhythm, vary the length and structure. A blog post should sound intentional, not metronomic. |331| Generic AI-jargon filler | Replace vague language like "robust," "seamless," "transformative," or "momentum" with the exact behavior, outcome, or tradeoff. |
jonesrussell