Overview

This blueprint walks you through building a content-driven static website using MDX files and Next.js App Router—no database or CMS required.

It is designed for:

developers who want to publish content without managing a CMS
teams building documentation sites, blogs, or marketing pages
anyone who prefers version-controlled content in markdown files
builders experimenting with AI coding agents who want a simple, repeatable setup

The focus is on simplicity and maintainability—your content lives in files, not a database.

What You'll Build

By the end of this blueprint, you'll have:

A Next.js website with dynamic MDX page rendering
A content directory structure for organizing MDX files
Dynamic routes that automatically generate pages from MDX files
Frontmatter support for metadata (title, description, dates, etc.)
Syntax highlighting for code blocks
A clean, styled content layout ready for customization

How to Use This Blueprint

This blueprint is meant to be followed step by step using an AI coding agent such as Cursor.

Important rules:

Follow the sequence as written
Do not skip verification steps
Ignore agent suggestions that expand scope

The goal is to finish with something working, not perfect.

Pre-requisites

Accounts & Tools

Node.js (LTS recommended)
pnpm, npm, or yarn
An AI-enabled code editor (Cursor recommended)
A Vercel account (for deployment, optional)
A GitHub account/repo (recommended for deployments)

Add Documentation as Agent Context (Strongly Recommended)

Keep these docs open or add them as context in your editor:

Next.js App Router: https://nextjs.org/docs/app
MDX: https://mdxjs.com
next-mdx-remote: https://github.com/hashicorp/next-mdx-remote
gray-matter: https://github.com/jonschlinkert/gray-matter
Cursor: Adding Your Own Documentation: https://cursor.com/docs/context/mentions#adding-your-own-documentationcu

Prompt 0 — Agent Working Agreement

You are my senior full-stack engineer working inside this repo.

Rules:
- Keep scope minimal and shippable.
- Prefer boring defaults.
- Do not add dependencies unless necessary; ask first.
- Make small, reviewable changes.
- Explain which files you touched.
- Stop after completing each task.
- Follow the blueprint sequence. Do not jump ahead.

Verification:

Agent acknowledges the working agreement

Prompt 1 — Initialize Next.js Project (Manual)

Goal: Set up a fresh Next.js project with TypeScript and Tailwind CSS.

Manual steps:

Create a new Next.js project:

npx create-next-app@latest mdx-website --typescript --tailwind --app --no-src-dir

Choose defaults for all prompts (or customize as needed)
Navigate into the project:
```
cd mdx-website
```
Start the dev server to verify:
```
npm run dev
```
Open http://localhost:3000 and confirm the Next.js welcome page loads

Verification:

Next.js project created successfully
Dev server runs without errors
Welcome page loads in browser

Prompt 2 — Install MDX Dependencies (Agent)

Goal: Install packages needed for MDX rendering and frontmatter parsing.

Install the following npm packages:
- next-mdx-remote
- gray-matter
- rehype-highlight (for syntax highlighting)
- highlight.js (peer dependency for rehype-highlight)

Use npm, pnpm, or yarn based on what the project uses.

After installation, verify package.json includes these dependencies.

Stop after packages are installed and package.json is updated.

Verification:

next-mdx-remote installed
gray-matter installed
rehype-highlight installed
highlight.js installed
package.json shows all dependencies

Prompt 3 — Create Content Directory Structure (Agent)

Goal: Set up a content directory and create sample MDX files.

Create the following directory structure:
- content/
  - pages/
    - about.mdx
    - contact.mdx
  - posts/
    - hello-world.mdx
    - getting-started.mdx

Create sample MDX files with frontmatter:

For content/pages/about.mdx:
---
title: "About"
description: "Learn more about us"
---

# About

This is the about page.

For content/posts/hello-world.mdx:
---
title: "Hello World"
description: "My first post"
date: "2026-01-10"
---

# Hello World

Welcome to my first post!

For content/posts/getting-started.mdx:
---
title: "Getting Started"
description: "A guide to getting started"
date: "2026-01-09"
---

# Getting Started

Here's how to get started.

Stop after all directories and files are created.

Verification:

content/pages/ directory exists
content/posts/ directory exists
Sample MDX files created with frontmatter
Frontmatter includes title, description, and date fields

Prompt 4 — Create Content Loading Utilities (Agent)

Goal: Build TypeScript utilities to load and parse MDX files with frontmatter.

Create lib/content.ts with the following functionality:

1. Define a ContentFrontmatter interface:
   - title: string
   - description?: string
   - date?: string
   - slug: string (derived from filename)

2. Define a ContentItem interface that extends ContentFrontmatter:
   - content: string (the MDX content without frontmatter)

3. Create functions:
   - getContentFiles(type: "pages" | "posts"): string[] - returns array of slugs
   - getContentBySlug(type: "pages" | "posts", slug: string): ContentItem | null
   - getAllContent(type: "pages" | "posts"): ContentItem[]

Use gray-matter to parse frontmatter.
Read files from the content directory using Node.js fs.
Handle errors gracefully (return null if file doesn't exist).

Stop after lib/content.ts is created and TypeScript compiles without errors.

Verification:

lib/content.ts created
TypeScript interfaces defined
Functions implemented for loading content
No TypeScript errors
Can import and use functions in a test file

Prompt 5 — Create MDX Rendering Component (Agent)

Goal: Build a reusable component to render MDX content.

Create components/mdx-content.tsx:

1. Import MDXRemote from 'next-mdx-remote/rsc
2. Import rehypeHighlight for syntax highlighting
3. Create an MDXContent component that:
   - Accepts a source prop (string of MDX content)
   - Uses MDXRemote to render the content
   - Configures rehypeHighlight plugin
   - Applies basic styling classes for typography

4. Export the component

Use the App Router pattern (this is a Server Component).

Stop after the component is created and can be imported without errors.

Verification:

components/mdx-content.tsx created
MDXRemote configured correctly
Syntax highlighting plugin added
Component exports successfully
No TypeScript or import errors

Prompt 6 — Create Dynamic Page Routes (Agent)

Goal: Build dynamic routes that render MDX files as pages.

Create app/pages/[slug]/page.tsx:

1. Use generateStaticParams to generate static params from content/pages/
2. Create a Page component that:
   - Gets the slug from params
   - Loads the page content using getContentBySlug
   - Renders 404 if not found
   - Renders the page title and MDXContent

3. Export metadata function for SEO:
   - Use title and description from frontmatter
   - Fallback to slug if title missing

Stop after /pages/[slug] route works and renders an MDX page.

Verification:

app/pages/[slug]/page.tsx created
generateStaticParams implemented
Page renders MDX content correctly
404 handling works for missing pages
Metadata is generated correctly
Can navigate to /pages/about and see content

Prompt 7 — Create Posts Index and Detail Pages (Agent)

Goal: Build a posts listing page and individual post pages.

Create two files:

1. app/posts/page.tsx:
   - Lists all posts from content/posts/
   - Shows title, description, and date
   - Links to individual post pages
   - Sorts by date (newest first)

2. app/posts/[slug]/page.tsx:
   - Similar to pages/[slug] but for posts
   - Includes date in the rendered output
   - Links back to /posts

Stop after both /posts and /posts/[slug] routes work correctly.

Verification:

app/posts/page.tsx created and lists posts
app/posts/[slug]/page.tsx created and renders posts
Posts are sorted by date (newest first)
Links between pages work correctly
Dates are formatted and displayed

Prompt 8 — Add Basic Styling and Layout (Agent)

Goal: Improve the visual design with consistent typography and layout.

Update the MDX content rendering to include better styling:

1. Update components/mdx-content.tsx to add Tailwind classes:
   - Style headings (h1, h2, h3)
   - Style paragraphs, lists, code blocks
   - Style links
   - Add spacing between elements

2. Create a simple layout wrapper or update existing layout:
   - Add a header with navigation
   - Add a footer
   - Center content with max-width

3. Style the posts index page:
   - Card-based layout for post previews
   - Hover effects
   - Readable typography

Stop after the site looks polished and readable.

Verification:

MDX content has proper typography styling
Headings, paragraphs, and lists are styled
Code blocks have syntax highlighting and styling
Navigation header exists
Posts index has a clean card layout
Overall design is consistent and readable

Prompt 9 — Add Homepage with Content Preview (Agent)

Goal: Create an engaging homepage that showcases content.

Update app/page.tsx to:

1. Display a hero section with site title and description
2. Show a preview of recent posts (latest 3-5)
3. Link to /posts to see all posts
4. Add a call-to-action or welcome message

Use the content loading utilities to fetch posts.
Style with Tailwind CSS to match the rest of the site.

Stop after the homepage looks good and displays recent posts.

Verification:

Homepage has a hero section
Recent posts are displayed
Links to /posts work
Design is consistent with the rest of the site
Content loads correctly

Optional Prompts (Nice-to-have)

Prompt 10 — Add Search Functionality

Implement a simple client-side search for posts:

1. Add a search input component
2. Filter posts by title/description on the posts index page
3. Use React state to manage search query
4. Highlight matching terms (optional)

Stop after search works on the posts page.

Prompt 11 — Add RSS Feed

Create an RSS feed for posts:

1. Create app/feed.xml/route.ts
2. Generate RSS XML from all posts
3. Include title, description, date, and link for each post
4. Set proper Content-Type header

Stop after /feed.xml returns valid RSS.

Prompt 12 — Add Sitemap

Create a sitemap.xml:

1. Create app/sitemap.ts (Next.js sitemap API)
2. Include all pages and posts
3. Set proper lastModified dates

Stop after /sitemap.xml is generated correctly.

Known Pitfalls

MDX files must have valid frontmatter (YAML between --- markers)
File names become slugs—use kebab-case for consistency
next-mdx-remote requires Server Components in App Router
Syntax highlighting requires both rehype-highlight and highlight.js
Static generation requires all MDX files to be present at build time

Definition of Done

Next.js project runs locally without errors
MDX files in content/ directory are loaded correctly
Dynamic routes /pages/[slug] and /posts/[slug] work
Posts index page lists all posts
Homepage displays recent posts
Content renders with proper styling
Syntax highlighting works in code blocks
Site is ready for deployment

Changelog

v1.0 — Initial release