Intro

Static Site Generators (SSG’s) like Gatsby, Astro, 11ty and Docusaurus (among others) are great for transforming your Markdown files into web pages. But there are a couple things that can trip you up while transferring your files between these generators. Let’s work out how to configure our Markdown files library for maximum compatibility between static site generators.

Frontmatter

First it’s important to understand what Frontmatter is and how it works. Every static site generator uses it, and it’s not technically part of the Markdown standard.

Frontmatter is the metadata that you want to associate with a Markdown file. It’s placed in the head of the file and is denoted by ---

Here is an example of Frontmatter.

---
title: "React: Modals With Portals"
date: "2020-10-16T07:04:03.284Z"
description: "Modals can be surprisingly tricky in React, but there is a good way to make them using Portals."
categories: ["Web Development"]
tags: ["React", "Modal", "Portals", "Twitch Clone"]
featuredImage: ../../assets/react-logo.png
---

This is actually something called YAML. It is described as “a human-friendly data serialization language for all programming languages.”. YAML is used in many contexts, however within Markdown files and static site generators it is used to provide meta data for the file. It’s important to understand a couple things. This is not Markdown, and it has a pretty loose official syntax. Not all variations of this syntax are compatible with all SSG’s out of the box.

Additional Frontmatter Formats

Just a quick note, there are other frontmatter formats that some SSG’s support. Such as TOML. YAML is just the most common.

Dates

One of the things I discovered while trying to transfer my markdown files to other SSG’s is that they didn’t like how my timestamp was formatted. Here is the YAML specification for timestamps:

Timestamp Language-Independent Type for YAML™ Version 1.1

This format works in Gatsby

date: "2023-03-14T00:00:00.000Z"

But if you try to use this format in Astro it will literally crash your build. Astro prefers

date: "2023-03-14"

Docusaurus will take the full date… but only if it’s not wrapped in a string

date: 2023-03-14T00:00:00.000Z

You can customize how frontmatter is formatted in Astro, but that’s not really the point. It should parse valid YAML out of the box, and it doesn’t. If you want to avoid headaches in the future, consider using the simpler format. Gatsby appears to have no problem parsing either of these formats or many others.

Categories and Tags (arrays)

It’s common in frontmatter to include arrays of tags and categories. Technically the following are both valid YAML formats for arrays

tags: ["Markdown", "Gatsby", "Astro", "11ty", "Docusaurus"]
tags:
 - Markdown
 - Gatsby
 - Astro
 - 11ty
 - Docusaurus

But several SSG’s will only accept the latter

tags:
 - Markdown
 - Gatsby
 - Astro
 - 11ty
 - Docusaurus

So consider using that format. Gatsby works with both.

Relative Link Paths (images)

Consider the following file structure.

blog
├── post-title-one
│   ├── index.md
│   ├── 1.png
│   └── 2.png
└── post-title-2
    ├── index.md
    ├── 1.jpg
    ├── 2.jpg
    └── 3.jpg

Note that we are packaging the images with our Markdown files and we can then reference them with relative links in the document like so

![image description](1.png)

This is in my opinion the ideal format for markdown documents, and I would argue this is the defacto standard. This works with the built in Markdown preview of VSCode, this works on Github, it works with Gatsby.

It does not however work with some SSG’s like Astro. If you really want to ensure maximum compatibility you may want to consider hosting all your images in something like an S3 bucket and using absolute path links to images in your Markdown files. Although this comes with a whole host of other downsides and feels a bit like giving in to terrorists.