wehub-resource-sync
31 lines
1.7 KiB
Markdown
31 lines
1.7 KiB
Markdown
# Explainer Markdown Rendering
|
|
|
|
How an explainer renders as markdown — the fallback format when intake resolved `output:md`. Load at compose time (Phase 4), not earlier. Content rules match the HTML reference; only the presentation medium differs.
|
|
|
|
## Hard invariants
|
|
|
|
- **YAML frontmatter carries the metadata:** `title`, `date`, `input_shape` (concept / diff / idea / recap), `subject`, and `unverified: true` when Phase 2 fell back to model knowledge. Field names are stable — a future library layer indexes them.
|
|
- **Pure markdown.** No HTML elements, no `<details>`, no inline styles.
|
|
- **Display-only.** No exercise or quiz content in the artifact; the check-in lives in the session.
|
|
- **Repo-relative paths** for any file reference; never absolute paths.
|
|
|
|
## Show-n-tell in markdown
|
|
|
|
Markdown's visual affordances are narrower than HTML's — compensate, don't skip:
|
|
|
|
| Material | Show |
|
|
|----------|------|
|
|
| Architecture, relationships, boundaries | Fenced `mermaid` block (`flowchart TB`) |
|
|
| Code behavior, a diff's mechanics | Fenced code block per hunk with a one-line *why* comment above each |
|
|
| A process, lifecycle, or state change | `mermaid` state/sequence diagram or a numbered list |
|
|
| A window of work (recap) | Date-ordered list, each entry: what changed and why it mattered |
|
|
| A comparison or trade-off | Pipe-delimited table, prose verdict underneath |
|
|
|
|
Never hand-draw box-drawing/ASCII diagrams — mermaid or prose. Diagrams complement prose; a reader who skips them still gets the full explanation in text.
|
|
|
|
## Reading ergonomics
|
|
|
|
- Lead each section with the point, then the mechanism, then the caveat.
|
|
- Dense is good; long is not — one sitting's read.
|
|
- Real code from the grounding evidence where it exists; language-tagged fences always.
|