Parse it with gray-matter:

For static generation, read the file system at build time and pass frontmatter to generateMetadata to automatically populate the document's <title> and <meta description> from the MDX file. The metadata and the content come from the same source of truth.

---

Remote MDX from a CMS

When your MDX content lives in a database or headless CMS rather than the filesystem, use next-mdx-remote/rsc to render it server-side:

One hard requirement for remote MDX: never render untrusted MDX. MDX compiles to JavaScript that executes in your server process. If a user can submit arbitrary MDX content that gets rendered without sanitization, they can execute arbitrary code on your server. For user-generated content, either strip JSX from the MDX before rendering (use a remark plugin to block JSX nodes), or use a sandboxed evaluation environment. For CMS content authored by your own team, this is less of a concern.

---

Syntax Highlighting with rehype-pretty-code

Syntax highlighting in MDX should happen at build time on the server, not in the browser with PrismJS or highlight.js. Server-side highlighting means zero client JavaScript, accurate colors in every rendering context, and consistent output across themes.

rehype-pretty-code with Shiki is the current best-in-class solution:

With theme set to an object with dark and light keys, Shiki outputs CSS custom properties that respond to your site's color scheme. Set keepBackground: false and apply your own background in the pre component mapping in mdx-components.tsx to have full design control.

Code blocks in MDX then support language annotations, line highlighting, and word highlighting out of the box:

The {3-5} highlights lines 3 through 5. The /config/ highlights every occurrence of the word "config". These features are purely declarative in your MDX content — no extra components needed.

---

A Complete MDX Docs Page with Table of Contents

Pulling it all together — a docs page that extracts headings for a Table of Contents, renders with custom components, and exposes frontmatter as metadata:

rehype-slug automatically adds id attributes to all headings in the MDX output. Your TOC component reads the heading IDs and renders anchor links. The headings array is extracted during the getDocPage call using a remark plugin that walks the AST before rendering.

---

View Transitions API in Next.js 15

The View Transitions API is a browser feature that animates elements between two DOM states — typically two page navigations. When you navigate from /blog to /blog/post-title, the browser can smoothly animate shared elements (a card expanding into a full-width hero, a thumbnail becoming a full image) instead of cutting abruptly.

Enable it in next.config.ts:

With this enabled, Next.js wraps client-side navigations in document.startViewTransition(). The default effect is a cross-fade between the old and new page. For most navigation this looks clean and modern with no additional work.

For element-level transitions — animating a specific card from the list into the detail page — use the view-transition-name CSS property to mark matching elements with the same name:

When the names match across two pages, the browser animates the element from its position on the old page to its position on the new page. The effect is the card expanding into the full detail page — a navigation metaphor that's immediately intuitive to users.

---

Controlling View Transition Animations with CSS

The @view-transition rule and ::view-transition-* pseudo-elements let you customize the animation behavior:

Two constraints worth knowing upfront. View Transitions are same-origin only — you can't animate across domains or subdomains. And there's no streaming overlap: the browser waits for the new page's content to be ready before starting the animation. In a streaming Server Component architecture where content loads incrementally, the transition starts when the initial shell arrives, not when all the data is fetched. For pages with slow data, this means the animation plays and then the content loads. Design your loading states with this in mind.

---

Content-First Architecture

For applications where content is the product — documentation, developer portals, knowledge bases — the architectural decisions around content storage and retrieval matter more than framework configuration.

File-based content (MDX in your repository) scales well up to a few thousand pages. The entire content corpus can be read at build time, search indexes can be pre-built, and static generation produces fast pages with no database dependency. The tradeoff is that every content update requires a deployment. For documentation that updates alongside code releases, this is a feature. For documentation that needs to be updated independently, it's a constraint.

For larger catalogs or content that updates independently of deployments, a hybrid approach works well: store content in a headless CMS, cache it aggressively in Next.js with tag-based revalidation, and trigger revalidation via webhook when content is published. The Next.js app stays statically optimal most of the time, and content updates propagate within seconds of publication via revalidateTag.

The filesystem conventions that work well for file-based content systems: a content/ directory at the project root (not inside src/ or app/), subdirectories per content type (content/docs/, content/blog/, content/changelog/), frontmatter for all metadata, and a thin abstraction layer in src/lib/ that reads and parses files. Keep the abstraction thin — content pipelines that become complex black boxes are painful to debug. The content is just files; the code that reads it should be obvious.

---