Markdown Report Writing

Provide expert guidance for writing professional, visually polished Markdown reports that render correctly on both GitHub and Obsidian.

Core Philosophy: Three-Layer Writing Model

When writing any Markdown report, think in three layers:

1. Content layer — Use CommonMark / GFM + Obsidian shared syntax for all headings, paragraphs, lists, images, tables, code blocks, footnotes, task lists, math ($\LaTeX$), and Mermaid diagrams. This is your foundation.
2. Enhancement layer — Add renderer-specific features only when necessary: GitHub <details> folding, relative links; Obsidian [[wikilink]], ![[embed]], Callout, cssclasses.
3. Build layer — For complex layouts, table of contents generation, site styling, and slide exports, delegate to Pandoc / Quarto / MkDocs / GitHub Pages.

This ensures your output is readable, portable, automatable, and version-controllable across all target environments.

Writing Principles

Follow these rules for every report: