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: /blog/2023-05-25-announcing-xstate-v5-beta/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: /blog/[folder-name]/share.png in the blog post’s frontmatter. For example: /blog/2023-05-25-announcing-xstate-v5-beta/share.png. The folder name in the file structure should be used, not the slug!

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.