Writing blog posts

Blog posts are formatted slightly differently to docs.

File name and folder structure

Blog posts are kept in the /blog folder. Each post is an index.mdx file kept in a folder with the publishing date and title of the post. For example:

blog/2023-05-25-announcing-xstate-v5-beta/index.mdx

The folder name is not currently used for the URL slug, but this format works well for maintainability and findability.

Frontmatter

• title: Blog post title
• description: One sentence description of the post. This will appear in search engine results, social media previews etc.
• tags: Formatted as an array. Try to use existing tags where possible.
• authors: Formatted as an array so it allows for multiple authors. Authors are pulled from the authors.yml file in /blog.
• slug: The blog URL slug
• image: The image that will appear in social media previews etc. Check out the how-to below.

Example:

---
title: Announcing XState v5 beta
description: We’re excited to announce the beta release of XState v5 and related packages after many years of development.
tags: [xstate, xstate v5, announcement, beta]
authors: [david]
slug: announcing-xstate-v5-beta
image: share.png
date: 2023-05-25
---

Share image

In the future, we’ll automate the creation of these images. For now we do them manually. If you’re confused or don’t have access to the Figma template, ask @LauraKalbag to generate one for you!

1. Create a new image using the Figma template.
2. Compress the image and save as share.png in the blog post’s folder.
3. Include image: share.png in the blog post’s frontmatter.

Truncate

The truncate shortcode tells the post where to truncate the blog post for display on the blog list page.

<!--truncate-->

Everything above the <!--truncate--> will be shown on the blog list page. Everything below the <!--truncate--> will only be shown on the blog post itself. Try to keep the content above <!--truncate--> no shorter than two sentences and no longer than a paragraph.

<!--truncate--> can be used inline inside a paragraph, or on its own line after a paragraph.