Create Your First Article

Creating a new article in Compass is intentionally simple: give it its own folder, add a slug-matched .mdx file, and fill in a few frontmatter fields.

Start with a folder

Each article lives in its own directory inside src/content/docs/<category>.

For example, to create an article in the start-here category:

src/content/docs/start-here/create-your-first-article/
`-- create-your-first-article.mdx

Using one folder per article keeps related screenshots, diagrams, and assets close to the content that uses them.

Add the frontmatter

Every article should begin with frontmatter like this:

---
title: "Create Your First Article"
description: "Add a new Compass article with the right folder structure, frontmatter, and optional images."
category: "start-here"
order: 4
updatedAt: 2026-06-05
---

These fields control:

• the page title
• category placement
• sort order inside the category
• preview text used across the docs UI

Write the article body

After the frontmatter, add your headings, paragraphs, code samples, and links.

Compass supports plain Markdown and MDX, so you can mix standard prose with registered components such as:

• Callout
• Accordion
• Tabs
• Steps

Add images when needed

If the article needs screenshots, keep them beside the .mdx file:

src/content/docs/start-here/create-your-first-article/
|-- create-your-first-article.mdx
`-- example-screenshot.png

Then reference the image with a relative path:

![Example screenshot](./example-screenshot.png)

Preview before publishing

After creating the article, run:

npm run dev

Then verify that:

• the article appears in the correct category
• the title and description read well
• links resolve correctly
• images load as expected

If you want the article to appear earlier in a category list, lower its order value.

Once you are comfortable adding pages, the next useful step is learning how to reshape category labels and routes. Continue with Rename and Restructure Categories.