Writing conventions

Frontmatter

Every page needs at least a title. Everything else is optional.

---
title: Running a simulation
description: Shown in search results and social previews.
sidebar:
  order: 2          # position within its sidebar group
  label: Running    # shorter label for the nav, if the title is long
  badge: New        # or { text: 'Draft', variant: 'caution' }
tableOfContents:
  maxHeadingLevel: 3
---

Set draft: true to keep a page out of production builds while still seeing it in npm run dev.

Code blocks

Code blocks are rendered by Expressive Code — titles, line highlighting, diffs and a copy button all come for free.

```cpp title="src/router.cc" {4-6}
void Router::handleMessage(cMessage *msg) {
    ...
}
```

Use ins={…} / del={…} for diff markers, and frame="terminal" for shell sessions.

Math

Inline math uses single dollars, display math uses double. KaTeX renders it at build time, so there’s no client-side cost:

The delivery ratio is $d = n_{\text{recv}} / n_{\text{sent}}$.

$$
T_{\text{contact}} = \sum_{i=1}^{N} \frac{L_i}{R_i} + \tau_i
$$

Diagrams

Fenced mermaid blocks become diagrams, and follow the site’s light/dark theme automatically:

```mermaid
graph LR
    A[Source] -->|bundle| B[Relay]
    B -->|custody| C[Destination]
```

Components

Import Starlight’s components in .mdx files (they don’t work in plain .md):

import { Tabs, TabItem, Steps, FileTree, Aside } from '@astrojs/starlight/components';

Tabs for per-platform instructions, Steps for ordered setup, FileTree for directory layouts, Card/LinkCard/CardGrid for landing pages.

Asides work in plain Markdown too, no import needed:

:::caution[Version drift]
The v5.7 and v6.4 toolchains are not interchangeable.
:::

Available flavours: note, tip, caution, danger.

Links

Use root-relative links between pages, with a trailing slash:

See [running a simulation](/projects/my-project/running/).

The build validates every internal link and fails on a broken one, so a typo here is caught before it ships.