Markdown for maintainable notes

Markdown gives technical documents a small, reviewable source format. Unlike formatting in a proprietary word processor, it is easy to diff alongside code and edit in tools such as Rider, VS Code, GitLab and GitHub. Some features such as callouts, Mermaid and embedded components depend on the renderer.

Useful patterns

# Inventory subsystem

## What it does

Validates item identity when clients reconnect.

## Example

```text
Request -> Validation -> Inventory update
```

[Related guide](./some-related-page.md)

Avoid nested triple backticks when copying this example directly. In actual documents, use a longer outer fence or separate smaller code samples.

Decide what belongs in a table

Tables help with compact comparisons such as configuration keys and defaults. Long tutorials are easier to follow using headings and short paragraphs instead of enormous tables. Code fences should name the language where possible to enable highlighting.

Links and source control

Prefer relative links for files within the same repository when those links need to work across forks; prefer absolute site paths for published Starlight navigation that supports redirects. Check links after moving files. For a multilingual site, update both language variants and verify examples in each.

Scope and readability

Keep headings descriptive, avoid giant unbroken paragraphs, and explain expected results after each command. Use one authoritative page for broad concepts and cross-link to it rather than maintaining conflicting copies.

See clear explanations and GitHub Markdown.