Markdown Authoring Cheatsheet
The golden authoring contract. Always write body content starting at ## (H2) — the template renders the title as H1.
Initial output is Gutenberg blocks. Before publication, the sync pipeline converts Markdown into serialized WordPress blocks (
core/heading,core/table,core/list,kevinbatdorf/code-block-pro,opshell/admonition, …). After publication, edit those blocks directly in Gutenberg; published posts are protected from Markdown overwrite. See Gutenberg Block Reference for the exact formats.
Element Map
| Element | Markdown | Notes |
|---|---|---|
| H2 section | ## Heading | First heading in body must be H2 |
| H3 | ### Heading | Subsection |
| H4 | #### Heading | Rare; keep depth shallow |
| Bold | **text** | |
| Italic | *text* | |
| Inline code | `code` | |
| Strikethrough | ~~text~~ | |
| Link | [text](url) | |
| Unordered list | - item | |
| Ordered list | 1. item | |
| Code block | ```lang | Fenced, language tag required (Shiki highlights) |
| Table | pipe table with header | |
| Blockquote | > text | |
| Admonition | :::note|tip|info|warning|danger | Optional custom title: :::note Title |
| Footnote | [^1] + definition | |
| Image |  | |
| Horizontal rule | --- |
Admonitions
:::note
Documentation posts do not require a featured image.
:::
:::tip
Use the tip block for best-practice recommendations.
:::
:::warning
Call out gotchas and foot-guns.
:::
:::danger
Reserve for destructive or irreversible actions.
:::
Code Blocks
```bash
git status
print("hello")
Rendered by **Code Block Pro / Shiki** (`github-dark` theme) with a copy button. Unknown languages fall back to plaintext. Use real language tags — never invent them.
## Tables
```markdown
| Task | Command |
| --- | --- |
| Stage | `git add .` |
Wide tables scroll horizontally. Keep cells concise. The separator must match the header column count exactly — a mismatch renders the whole block as literal text.
Frontmatter (date-only standard)
---
id: git-cheat-sheet # required: stable doc identifier
title: Git Quick Reference # required: post title
description: Essential Git # required: excerpt / meta description
category: code # required: must == top-level folder
tags: [cheatsheet, git] # required: YAML list, max 5
status: publish # optional: publish | draft, default publish
date: 2026-07-20 # optional: date only (YYYY-MM-DD)
slug: git-cheat-sheet # optional: URL slug, defaults to filename stem
template: reference # optional: post template name
---
Structural fields (id, category, slug, status) are never edited by hand — status is CSV-controlled.
Verify After Authoring
# Dry-run validates every doc without touching WordPress
tools/sync-docs.sh --dry-run
# Full sync
tools/sync-docs.sh