Writing documentation

This page demonstrates the components available for writing readable, visually distinct documentation.

Standard Markdown still works

Plain .md files support tables, images, links, code blocks, lists, and Starlight asides. You only need .mdx when embedding custom components.

REFERENCEInformation panel

Use a note panel for important context or definitions that should be easy to find later.

KEY IDEAConcept panel

Purple accents highlight key ideas and mental models without relying on color alone.

BEST PRACTICERecommended practice

Green highlights practical recommendations and successful patterns.

WATCH OUTImportant limitation

Amber signals limitations, assumptions, or situations where extra care is needed.

Where the files go

Text | Project folders

src/content/docs/       Markdown and MDX pages
src/components/         Reusable interactive Astro components
src/assets/             Images referenced by documentation
public/                 Favicons, background images, downloads
src/styles/custom.css   Global visual theme

Code examples

Always set the language and add a short label. Starlight will show a header above the code so readers know what they are looking at.

For example, a C# code fence can use csharp title="C# | Example.cs", while a shell command can use bash title="Bash | Terminal".

Writing a new page

Create src/content/docs/example.md with frontmatter:

Markdown | example.md

---
title: Example page
description: What this page teaches.
---

## The main idea

Explain one concept clearly, then demonstrate it.

Commit and merge to main. GitLab builds and deploys the result automatically.