Markdown, MDX, and frontmatter explained for non-technical content teams

If you manage a website built on a modern framework, you have probably run into three words that sound technical but matter to everyone who touches content: Markdown, MDX, and frontmatter. Understanding Markdown MDX frontmatter is the difference between feeling locked out of your own site and confidently shipping a blog post, a landing page, or a case study. The good news is that none of it is as intimidating as it looks. Each piece solves a specific problem, and together they explain why so many fast, durable websites store their content as plain text files instead of inside a database.

This guide is written for non-technical content teams, marketers, and the agencies who serve them. We will define each term in plain language, walk through a real example, explain why these formats power Git-backed sites, and show how Acrosite lets you work with all of it without ever opening a code editor.

What Markdown is, in plain language

Markdown is a way of writing formatted text using simple symbols instead of buttons. Where a word processor hides formatting behind a toolbar, Markdown puts it right in the text in a way that stays readable.

A few of the most common patterns:

• # Title and ## Subtitle create headings, where more hash marks mean a smaller heading.
• **bold** makes text bold and *italic* makes it italic.
• - item starts a bulleted list, and 1. item starts a numbered one.
• [link text](https://example.com) creates a link.

That is most of what you need for everyday writing. The appeal is durability. A Markdown file is just text, so it opens anywhere, never gets trapped in a proprietary format, and reads cleanly even before it is converted into a styled web page. When your build process runs, it turns those symbols into proper HTML, so a reader sees a polished heading while the underlying file stays simple and portable.

For content teams, the practical takeaway is that Markdown keeps writing focused. There are fewer formatting options to fuss over, which tends to produce more consistent articles across a team.

What MDX adds on top

MDX is Markdown with one extra ability: it can include reusable components inside the text. Think of a component as a pre-built block your developers have created once, such as a call-to-action box, a pricing comparison, a video embed, or a styled callout.

In plain Markdown, you can only use the standard formatting symbols. In MDX, a writer can drop in a named block, and the site renders the developer-designed version of that block in its correct place. This means a marketing page can mix normal prose with branded, interactive elements while still living in a single, readable text file.

The key idea is that MDX does not replace Markdown. It is a superset: everything you know about Markdown still applies, and components are an optional addition for the pages that need them.

What frontmatter is, with a concrete example

Frontmatter is the small block of structured information at the very top of a content file. It is not the article itself; it is the data about the article. The title, the publish date, the author, the description used in search results, the cover image, and any tags all live here. This metadata block is what your site reads to build listing pages, set SEO tags, and organize content.

Frontmatter is usually written in a format called YAML, fenced between two lines of three dashes. Here is a realistic example for a blog post:

---
title: "How We Cut Build Times in Half"
description: "A practical look at the changes that made our static site faster to ship."
date: 2026-06-06
author: "Jordan Avery"
tags: ["performance", "engineering"]
draft: false
coverImage: "/images/build-times.jpg"
---

Your article body starts here, written in normal Markdown.

Everything between the dashes is frontmatter. Everything after the closing dashes is the content. The field names, such as title or date, are decided by how your website is built, so two different sites may expect slightly different fields. That is exactly the kind of detail that trips up non-technical editors who would otherwise be perfectly capable of writing the post.

If a required field is missing or misspelled, or a date is formatted incorrectly, the page can fail to build or display wrong. This is the most common source of frustration in Git-backed content work, and it is the part Acrosite is designed to take off your plate.

Why these formats power Git-backed sites

Git-backed sites store content as Markdown or MDX files inside a version-controlled repository, usually on GitHub. This approach has earned its popularity for a few durable reasons:

1. Content lives with the code, so a site can be rebuilt exactly from its repository with no separate database to back up or restore.
2. Every change is tracked. You can see who changed what, when, and why, and you can roll back a mistake.
3. Plain text files are fast to build into static pages, which makes the published site quick and resilient.
4. There is no vendor lock-in. Your content is portable text you fully own.

Acrosite is built around this model and works well with Next.js and other Git-backed and static frameworks. Your content is committed to your own repository on the branch and path you configure, so you keep complete ownership while gaining a friendlier way to manage it. If you want the deeper rationale, our overview of how Git-backed publishing keeps content in your repo covers the ownership benefits in detail.

The catch with raw Git-backed workflows is the human cost. Asking a marketer or a client to open GitHub, find the right folder, edit YAML by hand, and avoid breaking the syntax is a recipe for errors and bottlenecks. That gap between the technical format and the people creating content is precisely what a publishing layer should close.

How Acrosite handles Markdown, MDX, and frontmatter for you

Acrosite sits between your team and the repository. People write and publish through a clean dashboard, and Acrosite produces correct Markdown or MDX files with valid frontmatter behind the scenes. You get the durability of Git-backed content without asking anyone to learn YAML.

Here is how the pieces map to the format you just learned:

• Posts, Pages, and Custom Content Types define what you are creating. Posts are your blog, Pages are standalone pages, and Custom Content Types model anything unique, such as case studies, team profiles, or release notes.
• Custom Fields become your frontmatter. When you define typed fields, such as text, rich text, an image, or an SEO field, on a content type, Acrosite renders them as proper form inputs and writes them into the frontmatter block correctly. A date field stays a valid date; a required field cannot be left blank.
• Content Items are the individual entries you fill in, which become the body and metadata of each file.

Because Acrosite controls the output, the frontmatter is consistent every time. There is no guessing at field names, no broken indentation, and no malformed dates. Writers see friendly form fields and a content editor; the repository receives clean, valid files.

The publishing flow keeps the rest of the process equally safe:

1. A writer drafts a Content Item, which stays private in the app until it is published.
2. The draft can move through internal review or go to a client. Client Reviewers see only the content assigned to them, can comment and Approve or Request Changes, and have no GitHub access. Your team tracks everything through the Review Queue.
3. On publish, Acrosite validates the content and commits the Markdown or MDX file, with frontmatter, to your connected repository on the configured branch and path. With Scheduled publishing, an approved draft is held in the app and committed only at the chosen time, so nothing lands early.
4. After the commit, a configured deployment trigger asks your hosting provider to rebuild, and you get Deployment visibility into the result.
5. Publish Logs record each attempt's steps, such as validated content, committed to GitHub, commit SHA saved, and deployment triggered, without ever exposing tokens or raw provider payloads.

If you want to see how this connects to your hosting provider end to end, the GitHub publishing overview walks through the commit-and-deploy path, and the features page maps the whole workflow.

A simple mental model

Markdown is how the words are formatted. MDX adds optional building blocks. Frontmatter is the structured data about each piece. Git stores it all as files you own. Acrosite is the friendly front door that lets non-technical people write, review, and publish into that system without touching the raw syntax.

Putting it into practice

A good way to start is to look at the content you already publish and decide where each piece fits. Your articles are Posts. Your evergreen marketing pages are Pages. Anything with a repeating shape, like a portfolio entry, becomes a Custom Content Type with its own Custom Fields. Once those types are defined, the frontmatter takes care of itself, because every field a writer fills in lands in the file correctly.

From there, your editorial process lives in the dashboard. Drafts stay private, reviews route through the Review Queue or out to Client Reviewers, and publishing commits clean files to your repo on your schedule. You can browse ready-made starting points on the templates page if you would rather not model everything from scratch.

The result is a content operation where the format does its job quietly in the background. Markdown, MDX, and frontmatter stop being barriers and become the dependable plumbing of a fast, owned, version-controlled website.