The connectrader MDX content standard

MDX gives us a useful middle ground between hard-coded page copy and a full database-backed content management system. The format is readable. The files can be version controlled. The application can parse structured frontmatter. The body can render as normal document content.

That sounds simple because the format is simple. The quality comes from the standard around it.

MDX is content, not a hidden page builder

Our first rule is that the MDX file should describe the page content. It should not become a configuration language for margins, columns, card shadows, animation delays, and twenty layout variants. When layout behavior is complex, it belongs in React components and CSS.

That keeps the content portable and keeps responsive behavior in the layer designed to handle it. A writer should be able to open the file and understand what the page says without mentally executing a layout engine.

Frontmatter is the structured contract

The top of the file contains the fields the application needs to understand the document. A documentation file might include:

---
slug: "example-topic"
title: "Example Topic"
description: "A useful summary of what this page explains."
category: "Architecture"
order: 3
tags: ["Next.js", "performance"]
---

An article can require additional fields such as publication date, updated date, image, author, category, and reading time. A location can have a much richer model. The field set should reflect the content type. It should not be one giant universal schema for the entire site.

Read Frontmatter is an interface contract for the deeper reasoning.

Slugs are durable identifiers

A slug should be readable, lower case, and stable. We do not try to stuff every keyword into the URL. We also do not casually change slugs after a page has been published. Once a URL has search history, links, analytics, or customer bookmarks, changing it creates migration work.

Our loaders may derive a fallback slug from the filename, but explicit slugs are useful when the URL should remain stable even if the source filename changes.

Titles should say what the page is

The title is not a place for vague marketing language. A technical guide called "Why preview deployments are explicitly noindex" is useful because the reader knows what question the page will answer. A service title should identify the service. An article title should identify the subject.

Clarity helps both navigation and search.

Descriptions should distinguish the page

Descriptions are used in metadata, index cards, and sometimes page introductions. They should explain what is unique about the document. If twenty pages all have variations of "Learn more about our services," the field technically exists and functionally says nothing.

The body starts below the page title

The route template usually owns the H1. The MDX body generally begins with H2 sections. This gives the document one clear primary heading. Some of our article renderers also normalize body-level H1 elements to H2 so an imported document cannot accidentally create a second primary heading.

The important part is that the heading hierarchy belongs to the document structure, not the visual font size.

Paragraphs should contain complete reasoning

We prefer normal paragraphs. One sentence can be a paragraph when the thought genuinely deserves isolation. We do not use constant one-sentence stacking as a default writing style. Technical content becomes easier to follow when related reasoning stays together. This also prevents the artificial rhythm that makes otherwise useful writing feel machine-generated.

Lists need a reason to be lists

Lists are useful for:

• requirements
• steps
• options
• comparisons
• grouped examples

They are not a replacement for explanation. If the reader needs to understand why a decision exists, prose usually belongs around the list.

Images are resolved through a content policy

An MDX file should not have to understand the bundler. Different repos use slightly different strategies, but the pattern is consistent: content identifies the desired image, a loader or resolver translates that reference into a safe application value, and the component controls rendering.

This lets us combine static imports, public paths, fallbacks, responsive image behavior, and validation without forcing those details into editorial files. See Why our content systems resolve images.

Links are part of the information architecture

Documentation should link to related documentation. Articles should link to relevant services when the relationship is real. Service pages can link to proof. Location pages can link to nearby areas. We use descriptive anchor text so the link makes sense before the reader clicks it.

We avoid manufactured internal linking where every page points everywhere simply because somebody wants a larger link count.

The file should fail early when it is invalid

One of our production article systems runs build validation over required frontmatter, duplicate slugs, dates, image paths, route metadata, canonicals, and preview indexing infrastructure. That is where an MDX system becomes more than "Markdown files in a folder." The content is part of the build contract.

A malformed date should be found before deployment. A duplicate slug should be found before deployment. A missing required description should be found before deployment.

Editorial dates and technical dates are different

An article can have a publication date because the reader needs to know when it was published. It can have an explicit updated date when a revision is editorially meaningful. The sitemap may also have a Git-derived technical modification date. Those concepts should not be collapsed into one field merely because they all look like dates.

The standard scales because the files stay boring

This matters as the library grows. A hundred documents are manageable when each one is a readable file with predictable frontmatter and ordinary document structure. A hundred documents become painful when each one contains bespoke JSX, inline layout hacks, undocumented fields, and one-off image behavior.

Our MDX standard is intentionally conservative. The application can be sophisticated. The content source should remain easy to inspect, edit, diff, and move. That is what gives us the ability to build large indexed content libraries without creating a second application just to manage the pages.