Skip to main content

ADR 005: Use Markdown for All Artifacts

Status​

Accepted

Context​

The system generates multiple artifact types (SDD, TDD, ADR, C4, etc.). We need:

  • Human-readable output
  • Version control friendly
  • Easy to render (HTML, PDF)
  • Tooling ecosystem
  • Extensibility

Decision​

Use Markdown as the canonical format for all artifacts.

Consequences​

Positive​

  • Universal readability
  • Git-friendly (diffable)
  • Rich ecosystem (pandoc, mkdocs, etc.)
  • Embeddable diagrams (Mermaid)
  • Front matter metadata support
  • Convertible to any format

Negative​

  • No strict schema enforcement
  • Limited native table support
  • Rendering varies by parser

Artifact Schema​

All artifacts follow this structure:

---
id: ARTIFACT-001
type: sdd
title: Software Design Document
version: 1.0
date: 2026-02-05
status: draft
parent_id: VIDEO-001
---

# Title

## 1. Section
Content...

## 2. Section
Content...

Mermaid for Diagrams​

## Architecture

```mermaid
flowchart TD
    A[Input] --> B[Process]
    B --> C[Output]

## Alternatives Considered

| Alternative | Pros | Cons |
|-------------|------|------|
| LaTeX | Academic standard | Steep learning curve |
| reStructuredText | More structured | Less popular |
| AsciiDoc | More features | Smaller ecosystem |
| Word/Google Docs | User friendly | Binary, not VC-friendly |
| JSON/YAML | Machine readable | Not human readable |

## Rendering Pipeline

Markdown → Pandoc → PDF/HTML/Word ↓ Mermaid → SVG → Embedded ↓ Front Matter → Database index


## Notes
Standardize on GitHub Flavored Markdown (GFM) for maximum compatibility.