Writing blog posts with MDX

Learn how to organize posts with categories, understand MDX's versatility, and manage frontmatter for effective content organization with ZippyStarter.

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.

Directory structure

The root of the blog is located at: src/content/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 clone ZippyStarter you'll see some example content to give you an idea about how to structure your blog.

Categories

Categories are optional, but recommended.

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.

A flag: show_child_posts can be used to display either the child posts, or sub-categories, of that category.

---
title: "A title"
date: 2023-11-15
show_child_posts: true
description: "A description"
---

If you look at line 4 you'll see that child post visibility is enabled by default (if the file is generated with the CLI). Change the value to false to show child categories instead of the child posts.

Take a look at the following visual references:

Props

PropWhat it's for
title<h1>, <title>, structured data
dateAny displayed dates & structured data
show_child_postsboolean to display child categories or child posts
description<meta name="description">, <Opener>, structured data

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: 2023-11-17
description: "Learn how to display the child posts or child categories on a blog page."
featured_image:
  url: https://images.unsplash.com/photo-1522832712787-3fbd36c9fe2d
  alt: "Peekaboo"
  width: 1232
  height: 620
author:
  name: Morgan Feeney
  avatar: /authors/morgan.webp
---

Authorship

The props to declare yourself as the Author are highlighted:

---
title: "About categories and posts"
date: 2023-11-17
description: "Learn how to display the child posts or child categories on a blog page."
featured_image:
  url: https://images.unsplash.com/photo-1522832712787-3fbd36c9fe2d
  alt: "Peekaboo"
  width: 1232
  height: 620
author:
  name: Morgan Feeney
  avatar: /authors/morgan.webp
---

Props

PropWhat it's for
title<h1>, <title>, structured data
dateAny displayed dates & structured data
description<meta name="description">, <Opener>, structured data
featured_imageFeatured image on blog posts, blog cards, opengraph data, twitter cards
author<Author> & structured data

You can add the default author to the root config file, so that when you generate a post, the author fields are autogenerated.