Skip to content
mattdennis.dev
Back to Blog

How to Contribute a Blog Post to This Site

A format reference for AI agents writing blog posts for mattdennis.dev — frontmatter, structure, spacing, and everything you need to get it right the first time.

• Matt Dennis
ai web-dev

This post is for you, the agent. You’ve been asked to write a blog post for this site, and you need to know the exact format so the build doesn’t break and the result looks right. Everything you need is here.


The File

Blog posts live in src/content/blog/. Create a new Markdown file with a kebab-case filename:


src/content/blog/your-post-title.md

Use .md, not .mdx, unless you have a specific reason to embed React components. You almost certainly don’t.


Frontmatter

Every post starts with a YAML frontmatter block. Here’s the full template:


---
title: "Your Post Title Here"
description: "A one-sentence summary, 120-160 characters. This shows up in SEO meta tags and social previews."
pubDate: 2026-02-16
author: "Matt Dennis"
tags: ["tag-one", "tag-two"]
featured: false
---

Field by field:


  • title — The display headline. Rendered as the H1 on the page. Wrap it in quotes.
  • description — 120 to 160 characters. This is the SEO summary and the text that shows up in link previews on social platforms. Make it count.
  • pubDate — Publication date in YYYY-MM-DD format. No quotes needed.
  • author — Typically "Matt Dennis" unless otherwise specified.
  • tags — An array of lowercase strings. Use existing tags before inventing new ones.
  • featured — Boolean. Set to true only if the post should appear on the homepage. Default to false.

Existing Tags

Check these before creating new ones:


  • Space/engineering: apollo, space, engineering, computing, pyrotechnics
  • Tech: salesforce, architecture, web-dev, ai, vibecoding, tools, aws, automation
  • Music: music, production, steely-dan, donald-fagen
  • Other: healthcare

Post Structure

The content area begins immediately after the frontmatter closing ---. Follow this exact pattern:


---
[frontmatter fields]
---

<hr />

Your opening paragraph goes here.

<br />

Your second paragraph.

<br />

## [Section Title](#section-title)

Section content here.

<br />

More content.

<hr />

The critical rules:


  1. Start with <hr /> — A horizontal rule immediately after frontmatter. This is the visual separator before the content begins.
  2. End with <hr /> — Another horizontal rule as the final line of content.
  3. <br /> between every paragraph — Every single paragraph is separated by a <br /> tag on its own line, with blank lines above and below it. This creates the breathing room the site’s design relies on.
  4. No H1 — The title from frontmatter is automatically rendered as the H1. Your content starts at H2.

Headings

Use H2 (##) for major sections. Each H2 should include an anchor link in this format:


## [Section Title](#section-title)

The anchor slug is the section title in lowercase, with spaces replaced by hyphens and punctuation removed. Use H3 (###) and H4 (####) for subsections. These don’t need anchor links, but they can have them.


Paragraph Spacing

This is the most common mistake. Every paragraph must be separated by a <br /> tag. Not just a blank line — an actual <br /> element. Here’s what correct spacing looks like in the raw Markdown:


First paragraph text.

<br />

Second paragraph text.

<br />

Third paragraph text.

The blank lines above and below the <br /> are required. Without them, the Markdown parser may not treat the tag as a block element.


Markdown Syntax

Standard GitHub-flavored Markdown applies:


  • **bold text** for bold
  • _italic text_ for italics
  • `inline code` for inline code
  • [link text](https://example.com) for links
  • Fenced code blocks with language identifiers for syntax highlighting

\`\`\`typescript
const x: number = 42;
\`\`\`

For tables, use raw HTML rather than Markdown table syntax. For images, use <figure> tags. For keyboard shortcuts, use <kbd> tags.


A Minimal Complete Example

Here’s the smallest valid blog post:


---
title: "Your Title"
description: "A 120-160 character description for SEO and social previews."
pubDate: 2026-02-16
author: "Matt Dennis"
tags: ["web-dev"]
featured: false
---

<hr />

Opening paragraph that hooks the reader.

<br />

## [First Section](#first-section)

Content of the first section.

<br />

Another paragraph in this section.

<br />

## [Second Section](#second-section)

More content here.

<br />

A closing line that resonates.

<hr />

Voice and Tone

If you’re writing the content, not just formatting it, match the site’s voice:


  • Authoritative but conversational. Write like an engineer explaining something to a sharp colleague. Not a textbook. Not a tweet thread.
  • Direct sentences. No hedging. “It is” not “it could potentially be.”
  • Dry humor welcome. Understated, not forced.
  • Go deep on technical specifics. Numbers, names, measurements, formulas. Vagueness is not an option.
  • No corporate language. “Leveraging” and “innovative” are banned.
  • No exclamation marks.
  • Don’t start paragraphs with “It’s worth noting,” “Interestingly,” or “In fact.”
  • No “Conclusion” section. End with a resonant line — a callback, a reframe, something that recontextualizes what came before.

Validation

Before considering the post done, verify the build passes:


npm run build

If the build fails, the frontmatter schema is wrong or there’s a Markdown syntax issue. The error output will tell you which field is missing or malformed. Fix it and build again.


That’s the format. Follow it exactly and the post will render correctly, index properly, and look like it belongs.