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 title and category. The optional fields add useful workflow metadata:

• description becomes the lede under the title, the meta description, and the fallback search excerpt
• order sets the article’s position within its category
• updatedAt shows a last updated date and adds the article to the homepage’s recently updated list and the RSS feed
• tags and author are indexed as search metadata; they are not shown on the page
• status controls the article lifecycle. Use published or deprecated for visible pages, and draft or archived for pages that should not publish. Deprecated pages show a Deprecated badge.
• editUrl overrides the “Edit this page” link, which Compass otherwise generates from editBaseUrl in src/config/site.ts
• 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
• relatedLinks adds cards under a “Continue with” heading at the end of the article
• hideFromSearch: true keeps a page out of search, popular articles, the recently updated list, RSS, and llms.txt

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, and the article count on the homepage card
• the sidebar for that section
• the direct article route generated from the article filename
• search, after the next npm run build
• the previous and next links of its neighbors in the category
• llms.txt, and the RSS feed and recently updated list when it has an updatedAt

Articles marked draft or archived are intentionally left out of those public surfaces.

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