Markdown Conventions

Canonical reference for Markdown shape and formatting across every authored .md and .mdx artifact. The summary at CLAUDE.md Conventions is the inline declaration; this page is the standalone reference downstream contributors cite.

---

1. FlavorCopy Anchor Link

GitHub-Flavored Markdown (GFM) is the host flavor. Every artifact renders correctly on GitHub's web UI, in the Fumadocs documentation site, and in standard Markdown-aware editors.

2. Heading hierarchyCopy Anchor Link

One H1 per file. Subsequent headings descend monotonically (H2 → H3 → H4) without skipping levels. Sentence-case headings; no ALL-CAPS, no Title Case Across Every Word. The H1 carries the document's primary title. On a docs-site page the frontmatter title renders as the H1 and is the page's anchor in the docs-site nav, so the page body starts at H2.

3. Code blocksCopy Anchor Link

Fenced code blocks declare their language (```python, ```bash, ```yaml, ```json, ```mermaid). Untagged blocks suppress syntax highlighting and signal authoring drift; the markdownlint MD040 rule, configured in .markdownlint.json, enforces the language tag.

4. Internal linksCopy Anchor Link

Internal cross-references use site-root paths (e.g., [Authorship header](/docs/reference/authorship-header)). Bare repository-relative paths with a .md/.mdx extension (/docs/foo.md) and full URLs to the same repo (https://github.com/ahmed-g-gad/apothem/blob/main/...) are avoided for in-site links because they resist page renames and section reorganizations.

These /docs/... site-root paths — and the /<locale>/docs/... form for the non-default cohort locales — are resolved against the on-disk page set under site/content/docs/ by the link-check validator: /docs/a/b maps to site/content/docs/a/b.mdx or the folder index site/content/docs/a/b/index.mdx, and the locale form maps under the site/content/docs/<locale>/ subtree. A link to a removed or renamed route resolves to neither file and is reported as a dead route (a user-facing 404) by link-check, an advisory matcher that does not fail the run (see §6).

External links to mutable refs (main, master, latest, HEAD) are pinned to commit SHAs or release tags whenever the linked content's stability matters; volatile references are documented as such with a {/* volatile */} adjacent comment.

5. Authorship headerCopy Anchor Link

Every Markdown artifact (with the exceptions enumerated at src/apothem/schemas/header-exceptions.txt) carries the canonical authorship header, the single SPDX-License-Identifier: MIT line, in the comment variant of its filetype per Authorship header: an HTML comment on .md files and a {/* ... */} comment on .mdx files. Without frontmatter, the header line is line 1. With YAML frontmatter, the frontmatter stays at byte 0 and the header line follows the closing ---.

6. ValidatorsCopy Anchor Link

The pre-commit markdownlint hook in .pre-commit-config.yaml runs markdownlint-cli with the rule policy in .markdownlint.json and enforces the bulk of the rules in §§1–4. The Markdown Lint workflow runs the same hook in CI on every push to main and every pull request that touches Markdown, so CI lints with the version the hook pins. The policy turns off MD013 (line length), MD033 (inline HTML), and MD041 (first-line heading). It also turns off MD038, because the canonical option-label postfix (Recommended) keeps its leading space inside a code span, and MD060, because no table-column style accepts the compact-cell tables with a tight |---| delimiter row that the corpus uses. MD024 checks sibling headings only, so the Added, Changed, Fixed, and Security headings each release repeats in CHANGELOG.md pass. The reasons for each choice sit beside the hook. The hook skips the test-fixture trees tests/fixtures/, tests/conformity/, tests/conformity-scenarios/fixtures/, and tests/scripts/inject-header/fixtures/, whose bytes the tests set. It also skips plugins/claude-code/, which python scripts/dev/assemble_plugin_tree.py generates from src/apothem/: a command's numbered steps become one file each, so a step file's list starts at its step number. The src/apothem/ sources are linted, so a finding in plugin content is fixed there and the plugin tree regenerated.

The file-header-grep at src/apothem/conformity/file_header_grep.py checks §5. The link-check validator at src/apothem/conformity/link_check.py checks the §4 link-resolution discipline — it resolves relative links against the source file's directory and /docs/... (and /<locale>/docs/...) site routes against the site/content/docs/ page set, flagging any that resolve to no page on disk. Both are advisory per-Write matchers. They run in the pre-commit conformity-corpus-perwrite hook and in the Conformity workflow's corpus-perwrite-gate job at .github/workflows/conformity.yml, and in both places they report findings without failing the run. The CI quality job's python -m apothem.conformity.gate --all . --strict at .github/workflows/ci.yml covers the standalone validators only, so it runs neither of them.