FIX: [ERROR] Error while parsing Markdown front matter

This can happen if you use special characters in front matter values (try using double quotes around that value). ???

At work we have an internal docs site that runs on an Azure static web app. The site uses Docusaurus. Docusaurus is an open-source documentation framework that makes it easy to create, maintain, and deploy documentation websites.

I’m not going to explain how the Docusaurus backend works.

Docusaurus explained in their docs, what the front matter is:

The front matter is used to provide additional metadata for your doc page. Front matter is optional—Docusaurus will be able to infer all necessary metadata without the front matter. For example, the doc tags feature introduced below requires using front matter. For all possible fields, see the API documentation.

Mine was looking like this:

---
title: Admin Accounts
sidebar_label: Admin Accounts
toc_max_heading_level: 2
pagination_prev: null
pagination_next: null
tags:
Admin Accounts
---

Can you spot the error? I got the below error while uploading to our docs site via a Github action.

[ERROR] Error while parsing Markdown front matter
This can happen if you use special characters in front matter values (try using double quotes around that value).

This was while the action was trying to deploy to an Azure static website.

Let me explain how you can fix this!

Let me start by saying that I don’t work much with Github actions (because we use Azure DevOps mostly) and certainly not with Docusaurus.
And since I’m not a fan of documentation, I don’t know much about a front matter or markdown either.

Fortunately, Docusaurus has a docs page to set up a docs page, which also explains the front matter and what you can define in the metadata fields.

Start by opening this link:
https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs

Here you’ll see the metadata fields you can define. I’ve got the following fields in mine:

• title
• sidebar_label
• toc_max_heading_level
• pagination_prev
• pagination_next
• tags

So, I’ll start with the title. As you can see in the docs, the title is of type string. with this explanation:
The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons…). Automatically added at the top of your doc if it does not contain any Markdown title.

which means that ‘Admin Accounts’ as a title should not be an issue.

sidebar_label is practically the same as the title and has a fallback to the title when this is not stated in the metadata field.
What’s funny is that I didn’t even have to fill it in, because it’s both the same text, but I only see this now that I’m writing the blog.

That basically says enough about my knowledge of this.

toc_max_heading_level, is of type number or aka integer, so with the number 2 this cannot be the issue.

pagination_next, pagination_prev, is either a string or a null value, without the null in mine, it will show the next page as if it’s the next step of your documentation, since this is not the case, null is correct here.

This leads me to think that something is wrong with my tag, but what?
The tag field is an array of tags (tag[]), so how do we define an array in the front matter?
The front matter is YAML, so we need to look up how you declare an array in YAML.
luckily Docusaurus has a link to w3schools.io where tags in YAML are explained. Apparently I’m missing the hyphen in front of my tag.

Reading that my front matter should look like this:

---
title: Admin Accounts
sidebar_label: Admin Accounts
toc_max_heading_level: 2
pagination_prev: null
pagination_next: null
tags:
- Admin Accounts
---

So in short it comes down to that something is wrong with your front matter, which is at the top of the page.

That you can use the defined metadata fields to see what should be in the fields, and how to write this down in the correct syntax, which is YAML.