Markdown Report Writing

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:

1. Shared syntax first — Build the body with syntax that works on both GitHub and Obsidian (headings, links, images, tables, code blocks, footnotes, task lists, Mermaid, math).
2. Relative paths for all assets — Place images, diagrams, and attachments in assets/ and reference them with relative paths.
3. Enhance per target — After the core is solid, add renderer-specific enhancements:
   • GitHub: relative links, section anchors, <details>, Mermaid
   • Obsidian: wikilink, embed, callout, cssclasses
   • Web/PDF/Slides: delegate to Pandoc / Quarto / MkDocs
4. Don't nest Markdown in HTML — GitHub strips custom HTML attributes; Obsidian won't parse Markdown inside HTML blocks. Use Markdown tables for side-by-side layouts instead of <div> flexboxes.
5. Mermaid first for diagrams — GitHub and Obsidian both render Mermaid natively. For complex UML, generate PlantUML SVG first, then embed.
6. Every figure needs alt text and a caption — Every code block must declare its language.
7. Every long document must have: executive summary, table of contents (or equivalent navigation), figures with captions, and a conclusion / next-steps section.

Quality Checklist

After generating any report, verify:

• All code blocks have language identifiers
• All images have alt text and captions
• All links use relative paths (no absolute paths to local files)
• Table of contents is present (for documents with 3+ sections)
• Mermaid diagrams render correctly
• Footnotes are properly paired (marker + definition)
• No complex Markdown trapped inside HTML blocks

Standard Document Skeleton

Start every report with this upgradeable structure:

---
title: Project Name
author: Team / Agent Name
date: YYYY-MM-DD
tags: [tag1, tag2]
---

# Project Name

> One-line summary: what problem this solves and what the conclusion is.

## Executive Summary

3-6 sentences covering background, approach, results, and conclusions.

## Background

Problem statement, context, and boundaries.

## Methods / Approach

Solution design, workflow, data, experimental conditions.

## Results

- Key finding A
- Key finding B
- Key finding C

## Conclusion / Next Steps

## Appendix & References

- [Raw data](./data/raw.csv)
- [Diagrams](./assets/fig-overview.svg)
- [Supplementary docs](./docs/appendix.md)

Layout & Typesetting Techniques

Images and Figures

Always provide alt text. Use SVG for diagrams, PNG/WebP for screenshots:

![System architecture diagram](./assets/fig-system-architecture.svg)
*Figure: Overall system architecture.*

[View full-size SVG](./assets/fig-system-architecture.svg)

Side-by-Side Layout (Cross-Platform Safe)

Use two-column Markdown tables as your grid system — this is the only approach that works reliably on both GitHub and Obsidian:

| Overview | Key Points |
|---|---|
| ![System overview](./assets/fig-overview.svg) | - 4 modules<br>- 12 interfaces<br>- Risk: data sync |

Avoid <div style="display:flex"> — styles get stripped on GitHub and block Markdown parsing on Obsidian.

Tables

Always use standard Markdown tables. Escape | inside cells with \|:

| Metric | Value | Notes |
|:--|--:|:--|
| Accuracy | 92.4% | Main model |
| Link to doc | [Appendix](./docs/appendix.md) | See details |

Code Blocks

Always declare the language for syntax highlighting:

```python
def evaluate(x: float) -> float:
    return x ** 2 + 1

### Mermaid Diagrams

Use fenced code blocks — both GitHub and Obsidian render them natively:

```md
```mermaid
flowchart LR
    Data[Data Input] --> Clean[Cleaning]
    Clean --> Analyze[Analysis]
    Analyze --> Report[Report Output]

### Math Expressions

Both GitHub and Obsidian support $\LaTeX$ via MathJax:

```md
Inline: $E = mc^2$

Block:
$$
\operatorname{F1} = \frac{2PR}{P+R}
$$

Task Lists and Collapsible Sections

- [x] Requirements confirmed
- [x] Data collected
- [ ] Charts reviewed
- [ ] Document published

<details>
<summary>Click to expand technical details</summary>

Keep content here plain text or simple HTML.
Avoid complex Markdown (lists, tables, formulas) inside
if the target includes Obsidian.

</details>

Footnotes

Use for citations, terminology, and data sources:

There is a term that needs explanation[^term].

[^term]: This is where the explanation or citation goes.

Report Templates

1. Project Report

Use when reporting project status, milestones, architecture decisions, risks, and next steps.

Required sections: Executive Summary → Background → Scope → Architecture & Design → Current Progress → Risks & Mitigation → Conclusion & Next Steps → Appendix.

Include: a system architecture diagram (Mermaid), a progress table with status per task, a risk matrix table, and a task checklist for next steps.