How an MDX file becomes a production page

MDX can look almost too simple from the outside. There is a file with frontmatter and Markdown. Then somehow there is a finished page with navigation, metadata, schema, responsive styles, related links, and a canonical URL. The value is in the pipeline between those two things.

Step 1: the content enters a known directory

Each content type has a home. Articles might live in src/content/blogs. Documentation lives in src/content/docs. Another project keeps services, locations, and other site content under an MDX content tree. The directory is part of the contract. The loader knows where to look, and the build does not need a manually maintained list for every file.

Step 2: the loader reads the file

A server-side library uses the filesystem to read the MDX source. gray-matter separates the frontmatter from the body. The loader then normalizes fields such as slugs, dates, categories, tags, image references, and last-modified values. This is the moment where raw editorial content becomes application data.

Step 3: the content is validated or normalized

Different repos do this with different levels of strictness. One production build has a dedicated SEO validation script that checks required frontmatter, duplicate slugs, valid dates, local image paths, metadata exports, canonical infrastructure, preview noindex handling, and expected route files. Other loaders normalize categories, resolve image references, apply intentional fallbacks, or reject malformed slugs.

The broader lesson is that a content file should fail early when it violates the system. A build error is much cheaper than discovering a broken production route after Google has crawled it.

Step 4: the route family discovers the valid slugs

For repeatable content, a dynamic route such as /docs/[slug] or /services/[slug] asks the content library for every known item. generateStaticParams() turns those slugs into build-time routes. That means the route list comes from the same source that contains the page content. There is less opportunity for the sitemap, navigation, and page system to disagree about what exists.

Step 5: metadata comes from the same object

The selected content item already has a title, description, slug, image, date, and other fields. The route uses those fields to generate the canonical URL, social metadata, article metadata, or other page-level tags. Several of our repos centralize this through metadata builder functions. That keeps canonical and social behavior consistent across otherwise different page types.

Step 6: the body renders through a controlled component layer

The MDX body does not own the entire page. The page template owns the H1, lead text, layout shell, navigation, related content, schema, and responsive behavior. The body is rendered inside a styled content container. Some article templates also remap MDX elements. For example, if an imported document contains an H1 in the body, the renderer can normalize it so the page still has exactly one primary heading.

That kind of rule is easier to enforce in a shared renderer than through manual editing alone.

Step 7: structured data is generated

A documentation page can become a TechArticle. A blog can become an Article or BlogPosting. A service route can emit Service schema and breadcrumbs. The schema uses the same normalized content object. That avoids the common failure mode where visible content changes but a copied JSON-LD block remains stale.

Step 8: the page joins the sitemap

The sitemap generator reads the content libraries and creates entries for each valid route. Modification dates can come from the source map generated from Git history. The result is a sitemap that reflects the repository instead of a manually edited XML list.

Step 9: the production build turns the source into an artifact

For static content, the finished page can be built ahead of time. The deployed artifact does not need to reread the MDX file from a CMS on every request. The visitor receives the output of the content pipeline. This is where the performance benefit appears.

Step 10: the repository remains the audit trail

If the page changes later, the content file changes. The commit records that change. A preview deployment can show the exact branch. The modification map can reflect the update. Content, code, deployment, and history stay connected. That is the real reason we like MDX for managed business sites.

The format itself is not magical. The pipeline is valuable because it gives us a human-readable authoring surface without giving up the discipline of an application build.