Content Authoring

Blog and docs pages are MDX files: Markdown with JSX component support. File-based, git-versioned, no CMS required.

Blog posts

1. Create the MDX file

Drop an MDX file into content/blogs/:

---
title: "How we shipped our landing page in a weekend"
date: "2026-04-18"
author: "Your Name"
---

# How we shipped our landing page in a weekend

Last Friday, we decided to rebuild our marketing site. By Sunday evening,
we were live. Here's what we learned.

## The stack

- Next.js 16
- Tailwind v4
- MDX for content

...rest of post...

2. Register it in src/config/blog.ts

export const BLOG_POSTS = [
  {
    slug: "how-we-shipped-in-a-weekend",
    title: "How we shipped our landing page in a weekend",
    description: "A 700-word retrospective on rebuilding a marketing site fast.",
    date: "2026-04-18",
    category: "Case studies",
    readTime: "5 min read",
    featured: false,
    author: {
      name: "Your Name",
      role: "Founder",
    },
  },
  // ...
];

The slug must match the filename (without .mdx). URL: /blog/how-we-shipped-in-a-weekend.

3. That's it

The blog route auto-reads the MDX, renders it through next-mdx-remote, and wires:

  • SEO metadata (title, description, OG card)
  • JSON-LD BlogPosting schema
  • Breadcrumbs
  • Share button
  • RSS feed inclusion
  • Sitemap entry

Docs pages

Docs follow the same pattern.

1. Create the MDX

Drop into content/docs/:

# Your Doc Title

Write markdown. Headings become the table of contents. Tables, code blocks,
and lists all render through the shared MDX component map.

2. Register in src/config/docs.ts

{
  slug: "your-doc",
  title: "Your Doc Title",
  description: "What this doc covers in one sentence.",
  category: "getting-started",
},

The DOCS_CATEGORIES map controls sidebar grouping. URL: /docs/your-doc.

MDX features

  • GFM tables: Pipe-delimited markdown tables work
  • Code highlighting: Triple-backtick blocks with language identifiers
  • JSX components: Import and use React components directly in MDX
  • Optimized links: Internal links auto-use next/link with prefetch
  • Optimized images: <img src="/path.png" /> renders through next/image

Frontmatter

Blog posts support frontmatter between --- delimiters at the top of the file. The renderer strips it before MDX parsing. Docs don't use frontmatter: metadata lives in src/config/docs.ts.

Drafts

There's no built-in draft system. For now:

  • Option A: Prefix filename with _ and don't add to BLOG_POSTS: the MDX file exists but isn't listed or routed.
  • Option B: Set date in the future: sort order puts it at the bottom.
  • Option C: Add a draft: true field to BLOG_POSTS and filter it out of the list UI.

Next

  • SEO: metadata + OG images + JSON-LD
  • Deployment: ship to production