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.

You can change the slug from blog to something else find out how

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"
---

The simplest, and easiest, way to write posts is to use the CLI

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

Prop	What it's for
`title`	`<h1>`, `<title>`, structured data
`date`	Any displayed dates & structured data
`show_child_posts`	`boolean` 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
---

Frontmatter is configured via the file: contentLayer.config.ts.

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
---

To configure the author props, simply edit the root config file

Props

Prop	What it's for
`title`	`<h1>`, `<title>`, structured data
`date`	Any displayed dates & structured data
`description`	`<meta name="description">`, `<Opener>`, structured data
`featured_image`	Featured 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.