Writing blog posts with MDX

Learn how to organize posts with categories, understand MDX's versatility, and manage frontmatter for effective content organization, available in Focus, our Next.js Blogging template.

What is MDX?

If you're not familiar with MDX, checkout the MDX docs.

In a nutshell, MDX combines the simplicity of Markdown with the power of JSX, creating an intuitive and flexible writing experience. Whether you're familiar with Markdown or new to content authoring, MDX is accessible and efficient, surpassing HTML, JSON, JavaScript, or JSX.

MDX files consist of three main parts: frontmatter, markdown, and JSX.

The beauty of this is that you don't need to hook up external resources to publish blog posts, all you have to do is add files and deploy!

Directory structure

The root of the blog is located here: src/data/blog. Blog posts can be organised into categories (by adding directories), or have a flat structure. Categories not only aid organization, and scalability, but also aid SEO by grouping related content, whereas a flat structure may be enough for a simple blog.

Here's a snapshot of how it looks:

blog/
├─ category/
│  ├─ index.mdx
│  ├─ post.mdx
│  ├─ category/
│     ├─ index.mdx
│     ├─ post.mdx
├─ index.mdx

When you unzip Focus you'll see example content structure like this to give you an idea about how to structure your own blog.

Categories

A category is a directory nested within the /blog directory, and at the minimum require an index.mdx file. The name of the category comes from the name of the directory.

index.mdx files are the files for category root pages, and have frontmatter specifically tailored for that level in the hierarchy.

---
title: "A title"
date: 2025-11-15
description: "A description"
---

Props

Posts

Each post within a category has frontmatter but with more properties, tailored to the specific needs of blog posts.

Here’s an example:

---
title: "About categories and posts"
date: 2025-11-17
description: "Learn how to display the child posts or child categories on a blog page."
featured_image:
  src: https://images.unsplash.com/photo-1522832712787-3fbd36c9fe2d
  alt: "Peekaboo"
---

Props

Authorship

The default author for all posts is configured in src/data/authors/default.mdx.

---
name: Randy Smith
avatarSrc: /avatars/13.png
profileImageSrc: /portraits/randy.png
subTitle: Digital craftsman
company: Focus
aboutPage: /about
email: address@yoursite.com
twitter: https://twitter.com/Twitter
linkedin: https://www.linkedin.com
github: https://github.com
---

I'm a passionate software engineer with experience across the full stack, always seeking new challenges and opportunities to create meaningful impact through technology.

To add more authors add a new file in src/data/authors name the file the name of the author, e.g. Mike Johnson would be mike-johnson.mdx

---
name: Mike Johnson
avatarSrc: /avatars/12.png
profileImageSrc: /portraits/mike.png
subTitle: Maker of things
company: Focus
aboutPage: https://twitter.com/Twitter
email: address@yoursite.com
twitter: https://twitter.com/Twitter
linkedin: https://www.linkedin.com
github: https://github.com
---

I'm Randy's faithful sidekick, always willing to help get him out of a sticky situation that involves code.

Reference the new author in a post like so:

---
title: ...
date: ...
featured_image: ...
description: ...
authors: ["mike-johnson", "default"]
---

What's really cool about configuring author's like this is that the files can be re-used on other pages that need to display more of the author info, such as author bios or about us pages.