MDX frontmatter fields and what they mean

Frontmatter is the structured header at the top of an MDX file. It gives the application information that should not be inferred from the body.

Core fields

slug controls the URL identifier for the content item. title is the human-readable page title. description is the concise summary used in page metadata and often in index cards. category groups related documents. order controls manual ordering inside a category when chronological sorting would be wrong.

Optional fields

Articles may also use date, displayDate, readTime, image, and tags. Portfolio entries may use outcome metrics, client industry, service categories, or image references. The field set should match the content type.

Why we do not infer everything

It is possible to derive titles from filenames and dates from Git history, but explicit frontmatter is easier to review and less fragile. We still use Git history for last-modified values because that field represents repository history rather than editorial meaning.

Validation matters

A content loader should provide safe defaults, but important fields should be treated as required by convention. A page without a useful title or description should be fixed at the content layer, not hidden by code.

Keep frontmatter boring

Frontmatter works best when it is predictable. We avoid turning it into an undocumented programming language. If a content model becomes complicated enough to require nested configuration everywhere, it may be time to move that behavior into code instead.

Different content types need different contracts

We do not force every MDX file into one universal frontmatter schema. An article, service, location, and technical document have different responsibilities. One article model in our repos includes title, slug, category, publication date, sorting date, reading time, image, excerpt, featured state, article type, author, meta title, meta description, keywords, social image, content-image references, a checklist, FAQs, and body content. That is a richer model because the article system uses those fields for category pages, metadata, schema, related content, and editorial presentation.

A simpler documentation page does not need most of those fields. Giving it fifty empty options would make the authoring experience worse.

Required and optional fields should be intentional

A title and description may be required because every page needs them. A custom social image can be optional if the page has a strong site-wide default. A custom meta title can be optional if the visible title already works well. Defaults are useful when they express a real policy. They are dangerous when they hide missing content.

For example, an article image can have a fallback during development, but a production content standard may still require the field so every article receives a deliberate asset.

Normalization belongs in the loader

Raw frontmatter often needs small cleanup before it becomes application data. Categories can be normalized so near-duplicates do not create separate archives. Dates can be converted to a consistent string representation. Tags can accept a string or array and become one predictable array. Filenames can provide a fallback slug.

The page component should not repeat those rules.

We validate fields that can break the system

A malformed date can break sorting. A duplicate slug can collide with another route. An image path can point outside the expected asset model. Those are good candidates for automated validation because the correct state is objective. The broader reasoning is in Frontmatter is an interface contract, not decoration. Frontmatter works best when it is treated like a small, documented API between editorial source and application code.