| 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
- 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.
- Structure with headings. They become the on-page table of contents and the
anchor targets. Never skip a level (
# → ## → ###).
- Make examples real. Fence every code block with a language hint; verify it runs.
- Disclose progressively. Lead with the 80% path; hide depth behind
<details>.
- 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:
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:
,
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.
