Site structure

Slugs and URLs

You can choose any slug for the page URL, but we want to avoid changing and breaking URLs in the future, so it’s best to choose a good slug from the beginning. Try to keep it simple and easy to read.

By default, Docusaurus uses the file name to determine the URL, but you can set a custom slug in a doc page’s frontmatter:

---
title: 'Docs page title'
slug: /my-slug
---

Versions

Docs pages (XState version 4) are stored in the /docs folder. XState version 5 docs are currently stored in the /versioned_docs/version-5 folder. In the future, we will make version 5 the current version, which will mean the version 5 docs are stored in the /docs folder, and version 4 docs will be stored in /versioned_docs/version-4.

Should I add my docs to version 4 or version 5?

• If your docs are for Stately Studio, add your docs to the /docs folder and copy them into the /versioned_docs/version-5 folder. This is because Stately Studio docs are not versioned and you want your docs to be included in the current docs and the V5 docs.
• If your docs are only for XState V4, only add them to the /docs folder. This is because your docs will go out of date with V5.
• If your docs are only for XState V5, only add them to the /versioned_docs/version-5 folder. This is because your docs are not relevant without V5.

Don’t forget to add your docs to the corresponding sidebar!

Internal links

As we are using Docusaurus versioning, the best way to link to other docs pages is using their .mdx file name. For example:

Find out [more about final states in XState](final-states.mdx) in the XState section of the docs.

The URLs will be resolved during the build process. In the case of two files with the same name in /docs and /versioned_docs/version-5, the link will resolve to the doc in the same version folder.

Folder structure and file names

We use a flat folder structure inside the /docs and /versioned_docs/version-5 folders as the file structure determines the URL structure, and reorganizing pages could result in broken URLs in the future.

File names should be simple, short but readable, and hyphen-separated.

Sidebars

We use the docs sidebar to organize pages into useful categories.

• The /docs sidebar is in sidebars.js.
• The /versioned_docs/version-5 sidebar is in versioned_sidebars/version-5-sidebars.json.