github-markdown

name

github-markdown

description

Wield the full power of GitHub-Flavored Markdown (GFM) and GitHub's rendering pipeline to design world-class documentation — alerts/admonitions, collapsible sections, tables, task lists, mermaid diagrams, math, footnotes, themed images, auto-anchors, and badges. Use whenever authoring a README, guide, or any markdown that renders on GitHub (and, with the noted caveats, on the Astro Starlight surface). The reference + procedure the documentation-engineer reaches for.

GitHub-Flavored Markdown — the full toolkit

GFM is more than bold and bullet points. Used with intent, it turns flat text into documentation that scans, explains, and demonstrates. This is the feature set and the discipline for using it. Every feature here is chosen because it makes a document clearer — never to decorate.

When to use

Authoring or overhauling anything markdown that renders on github.com (READMEs, /docs, issues, PRs, wikis) or on the Dossier docs site. Read the Portability section before writing docs that must render on both GitHub and Astro Starlight.

Procedure

1. Pick the job, then the feature. Decide what the reader needs to do or understand, then choose the smallest GFM move that delivers it. A caveat → an alert. Optional depth → <details>. A comparison → a table. A flow → mermaid.
2. Structure with headings. They become the on-page table of contents and the anchor targets. Never skip a level (# → ## → ###).
3. Make examples real. Fence every code block with a language hint; verify it runs.
4. Disclose progressively. Lead with the 80% path; hide depth behind <details>.
5. Check portability if the doc also ships on Starlight (see below), then preview.

---

The reference

Headings & automatic anchors

Every heading gets a slug: lowercase, spaces → hyphens, punctuation dropped. Link to one with [jump](#the-heading-text). This is how you build a manual table of contents and cross-link within a long page. GitHub also renders an auto-TOC from the heading button in the file header.

GitHub Alerts (admonitions)

Blockquotes with a typed marker render as colored callouts. Five types only:

> [!NOTE]
> Useful context the reader should know.

> [!TIP]
> A helpful, non-essential suggestion.

> [!IMPORTANT]
> Key information the reader must not miss.

> [!WARNING]
> Negative consequence if ignored — needs attention.

> [!CAUTION]
> Risk or danger of an action.

Use sparingly — a page where everything is a [!WARNING] has no warnings. One marker per blockquote; no nesting.

Collapsible sections

Native HTML, sanitized-safe. The blank line after </summary> is required for the inner markdown to render:

<details>
<summary>Show the full config</summary>

```ts
export default { /* … */ }

```

Use for: long output, optional deep-dives, FAQ entries, "click to expand" examples. Add open to <details open> to default-expand.

Tables (with alignment)

| Feature | GitHub | Starlight |
|:--------|:------:|----------:|
| Alerts  | native | `:::note` |

:--- left, :---: center, ---: right. Keep cells short; for anything multi-line or rich, use a list or <details> instead — tables are for scannable comparison.

Task lists

- [x] Shipped
- [ ] Pending

In issues/PRs they're interactive and roll up to a progress bar. Great for checklists and acceptance criteria.

Code: fences, languages, diff, suggestions

• Always hint the language for highlighting: ```ts, ```bash, ```jsonc.
• ```diff highlights +/- lines — ideal for showing a change.
• In a PR review, a ```suggestion block proposes a committable edit.
• Inline code for identifiers, paths, commands, and OKF ids/slugs.

Mermaid diagrams

Fenced ```mermaid blocks render natively on GitHub — flowcharts, sequence, class, state, gantt, ER:

```mermaid
flowchart LR
  ingest --> extract --> okf[(OKF repo)] --> serve

Reach for mermaid when a picture genuinely beats prose (a pipeline, a state machine, a
relationship graph). Don't diagram what a sentence says better.

### Math (LaTeX)
Inline `$a^2 + b^2 = c^2$` and block:

```markdown
$$
F1 = 2 \cdot \frac{P \cdot R}{P + R}
$$

Also ```math fenced blocks. Renders natively on GitHub.

Footnotes

Provenance is stamped at ingest.[^prov]

[^prov]: Every Source carries the originating file/URI; it flows onto every atom.

For asides and citations that would break the reading flow inline.

Themed images (light/dark)

Serve different art per color scheme. Two ways:

![Diagram](diagram-light.png#gh-light-mode-only)
![Diagram](diagram-dark.png#gh-dark-mode-only)

or the robust <picture>:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="diagram-dark.png">
  <img alt="Architecture diagram" src="diagram-light.png">
</picture>

Always set meaningful alt text — it's accessibility and the fallback.

Centering, badges, and README polish

• Center a hero/header with <div align="center"> … </div> (sanitized-allowed).
• Status badges via GitHub Actions: ![CI](…/actions/workflows/ci.yml/badge.svg), or shields.io for version, license, coverage.
• <kbd>Ctrl</kbd>+<kbd>C</kbd> for keystrokes; H<sub>2</sub>O, x<sup>2</sup> for sub/superscript.

Links, anchors, permalinks

• Relative links between repo files ([the model](../knowledge/model/index.md)) survive clone and rename better than absolute URLs — prefer them in-repo.
• Code permalinks: on a file, press y for the commit-pinned URL; append #L10-L20 to point at a line range that won't drift.
• Autolinks: bare URLs linkify; in issues/PRs, #123 and @user resolve in-repo.

Allowed inline HTML

GitHub sanitizes but permits a useful subset: <details>/<summary>, <picture>/ <source>/<img>, <kbd>, <sub>/<sup>, <div align>/<p align>, <a>, <table>, <br>. Not allowed: <script>, <style>, class/id/style attributes, most custom attributes. Don't reach for HTML when markdown does the job.

Emoji & misc

:rocket: shortcodes render; use for signposting (:warning:, :bulb:) only when it adds scanning value. ~~strikethrough~~ for retracted text. --- for a horizontal rule between major sections.

---

Portability — GitHub ↔ Astro Starlight

Docs that live on both the repo and the Dossier docs site need translation at a few seams (coordinate with the starlight-engineer):

Feature	GitHub	Astro Starlight
Admonitions	> [!NOTE] alerts	:::note / :::tip / :::caution / :::danger asides
Mermaid	native	needs a rehype/astro mermaid plugin
Math	native	needs remark-math + rehype-katex
<details>	native	native (works as-is)
Themed images (#gh-*-mode-only)	GitHub-specific anchor hack	use <picture> + prefers-color-scheme
Footnotes / tables / task lists	native	native

When a single source must serve both, prefer the portable form (<picture>, <details>, standard tables) and flag the divergent bits, or keep a Starlight-specific variant the site builds from.

Rules

• A feature must earn its place. If removing it loses no clarity, remove it.
• Verify before you publish. Run the commands, resolve the links, confirm the code.
• Single-source-of-truth. Link to the canonical fact; don't duplicate it into prose.
• Accessibility is not optional. Alt text, semantic heading order, descriptive link text, real table headers, language hints on every fence.

Output

Markdown that reads cleanly as raw text and renders as world-class documentation on its target surface — every GFM feature used on purpose, nothing decorative, nothing duplicated, every example true.