Write Your First Article

Every article in Compass lives in its own folder with a slug-matched .mdx entry file. Once you add one document and connect it to a category, the homepage, sidebar, and article route all update automatically.

Start with frontmatter

Use frontmatter to define how the article is listed:

---
title: "Deploy Compass"
description: "Publish your docs site to your hosting platform."
category: "compass-docs"
tags: ["deployment", "hosting"]
status: "published"
author: "Docs Team"
editUrl: "https://github.com/your-org/your-repo/edit/main/src/content/docs/compass-docs/deploy-compass/deploy-compass.mdx"
heroImage: "./deploy-hero.png"
redirectFrom:
  - "/getting-started/compass-docs/publish-docs"
order: 5
updatedAt: 2026-06-03
---

The required fields are still title and category, but the optional fields above unlock a lot of useful workflow metadata:

• tags let you group related docs or prepare future search filters
• status helps call out drafts, deprecated guides, or archived content
• author shows who owns the article metadata
• editUrl powers an “Edit this page” link at the bottom of the article
• heroImage renders a header image from the article folder through Astro’s image pipeline
• redirectFrom keeps old doc links working after a rename or move
• hideFromSearch: true keeps a page out of the generated search index

Add the body content

Below the frontmatter, write normal Markdown or MDX content:

## Publish checklist

<Checklist>
  <ChecklistItem>Confirm `siteUrl`</ChecklistItem>
  <ChecklistItem>Run `npm run build`</ChecklistItem>
  <ChecklistItem>Verify links and metadata</ChecklistItem>
</Checklist>

Start with the article folder

Create the article inside the folder for its category slug:

src/content/docs/compass-docs/release-workflow/
|-- release-workflow.mdx
|-- approval-flow.png
`-- dashboard-overview.png

Compass uses this structure for all articles so routes stay predictable and images can live right beside the content that uses them.

Where it shows up

Once saved, the article will appear in:

• the category page for its category
• the sidebar for that section
• the direct article route generated from the article filename

MDX when you need more than Markdown

Most docs can stay plain Markdown, but MDX is helpful when you want:

• custom components
• richer callouts
• buttons, steps, tabs, or accordions
• embedded demos or previews

If you want a closer look at the available building blocks, continue with Register MDX Components.