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.
SCS integration (brief / article markers)
When content is authored through the SCS (SEO Content System) pipeline, a single Markdown file carries two halves separated by HTML comments:
<!-- scs:brief -->
## 1. Decision
... (brief: audience, SERP, outline, sources, QA handoff)
<!-- scs:article -->
## Overview
... (the published article body)
<!-- scs:brief -->…<!-- scs:article -->is the brief (research/audit trail, never published).- Everything after
<!-- scs:article -->is the article thatsync.pyconverts to Gutenberg blocks. - Only the article half is sent to WordPress; the brief stays local.
- The markers must not appear in the published body.
sync.py/wp-sync-bridge.phpconsume the article half only. - SCS front matter is a superset of the ID86 contract (
title,description,category,tags,content_type,status,date,slug) plus nestedscs.identity.*context. The ID86 sync pipeline treats the standard fields as the publication contract and ignores the nestedscs:block. scs.recordis a generated, read-only mirror of all CSV records and related registries for that PID. It lets editors read the content and its supporting data in one Markdown file. CSV remains authoritative; SCS refreshes the mirror on sync.- The record stays in front matter and is not part of the article body sent to WordPress.
See Content Sync Pipeline and the SCS Front Matter & Markers cheatsheet for the full mapping.
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: # required: YAML list, max 5
- "cheatsheet"
- "git"
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
---
Use the SCS canonical block-list form for lists: put tags: on its own line,
then write each quoted tag as an indented - "tag" item. Do not use inline
bracket lists such as tags: [cheatsheet, git] in SCS Markdown.
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