Adding a new article

Articles live in _src/content_a.py through _src/content_d.py. Add new ones to whichever file is smallest, or create content_e.py and import it in build.py.

The article object

make_article(
    slug="how-to-do-something",
    title="How to Do Something",              # H1
    meta_title="How to Do Something | ...",   # <title>
    meta_desc="140-160 characters.",
    card_desc="One line for cards and search.",
    category="brick-breaker-guides",          # one of six category slugs
    primary="primary keyword",                # ONE search intent
    secondary=["variation", "variation"],
    image_alt="Descriptive alt text for the featured image",
    intro="<p>...</p>",                       # HTML, before the TOC
    body=[
        ("First H2 heading", "<p>HTML for this section</p>"),
        ("Second H2 heading", "<p>...</p>"),
    ],
    insight="Editor's note paragraph - plain text.",
    faq=[("Question?", "Answer.")],
    takeaways=["...", "..."],
    refs=[("https://example.com", "Source label")],
    conclusion="<p>...</p>",
    cta=("/games/some-game/", "Play Some Game"),
    related_games=["slug"],
    related_articles=["slug"],
    published="2026-09-20",                   # optional, defaults to LAUNCH_DATE
    updated="2026-09-20",                     # optional, defaults to published
    pillar=False,                             # True only for cornerstone articles
)

What the builder does for you

• Generates the table of contents from your H2 headings, with anchor IDs.
• Counts words and calculates reading time.
• Generates a 1200x630 featured WebP image from the title and category.
• Builds Article, BreadcrumbList and FAQPage JSON-LD.
• Writes canonical, Open Graph and Twitter Card tags.
• Adds the article to its category page, the author page, the search index, data/articles.json, the XML sitemap and the HTML sitemap.
• Places exactly one in-content ad slot after the third section.

Writing rules for this site

1. One search intent per article. If a new article would answer the same question as an existing one, expand the existing one instead.
2. Be specific. Real numbers from the engine, named games, worked examples.
3. Never invent statistics. If no reliable figure exists, drop the claim.
4. Attribute contested history. "Wozniak has said..." not "it is a fact that...".
5. Link naturally. Two to five internal links inside the prose, plus the related blocks the builder adds.
6. Only change updated when content actually changed.

Images

The builder generates a branded featured image automatically. To use your own, save a 1200x630 WebP at assets/images/articles/<slug>.webp before building - existing files are never overwritten unless you pass --images.

Filenames must be descriptive (brick-breaker-strategy-guide.webp, never image1.webp), and image_alt must describe the image rather than repeat the title.

Promoting a brief to an article

The fifty briefs in the content plan each contain the intent, angle, outline, must-cover points, internal links and target game. Turn one into an article object, write the sections named in the outline, delete the brief from _src/briefs.py, and rebuild.

Rebuild

py _src/build.py --check