mdv-markdown-visualization

What this skill does

# MDV Markdown Data & Visualization

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

MDV is a Markdown superset (`.mdv` files) for writing reports, dashboards, and slide decks in a single workflow, then exporting to self-contained HTML or PDF. It extends CommonMark with four additions: YAML front-matter, fenced visualization blocks, `:::` containers for layout, and auto-generated tables of contents.

## Installation & Setup

```bash
git clone https://github.com/drasimwagan/mdv mdv
cd mdv
npm install
npm run build

# Render a file to HTML
node packages/mdv-cli/dist/index.js render examples/09-full-report.mdv

# Live preview with auto-reload
node packages/mdv-cli/dist/index.js preview examples/09-full-report.mdv

# Export to PDF
node packages/mdv-cli/dist/index.js export --pdf examples/09-full-report.mdv
```

## CLI Commands

```bash
# Render .mdv → self-contained HTML
node packages/mdv-cli/dist/index.js render <file.mdv>
node packages/mdv-cli/dist/index.js render <file.mdv> --out output.html

# Live preview (opens browser, auto-reloads on save)
node packages/mdv-cli/dist/index.js preview <file.mdv>

# PDF export
node packages/mdv-cli/dist/index.js export --pdf <file.mdv>
node packages/mdv-cli/dist/index.js export --pdf <file.mdv> --out report.pdf
```

## File Structure

```
.mdv project/
├── data/
│   ├── sales.csv
│   └── metrics.json
├── report.mdv
└── dashboard.mdv
```

## Document Anatomy

Every `.mdv` file has three zones:

1. **YAML front-matter** — metadata, theme, named styles, dataset refs
2. **Markdown body** — standard CommonMark prose
3. **Fenced blocks & containers** — charts, stats, callouts, columns

## YAML Front-Matter

```yaml
---
title: Q1 Sales Report
author: Jane Smith
theme: report          # report | dashboard | slides | minimal
data:
  sales: ./data/sales.csv
  users: ./data/users.json
styles:
  highlight:
    background: "#fff3cd"
    border-left: "4px solid #ffc107"
  danger:
    background: "#fde8e8"
    border-left: "4px solid #e53e3e"
---
```

### Available Themes

| Theme       | Best for                        |
|-------------|----------------------------------|
| `report`    | Long-form documents, articles    |
| `dashboard` | KPI cards, dense data layouts    |
| `slides`    | Presentations, slide decks       |
| `minimal`   | Clean, unstyled output           |

## Fenced Visualization Blocks

### Stat / KPI Cards

```markdown
```stat
label, value, delta
Total revenue, $2.06M, +14%
New customers, 1,238, +8%
Churn rate, 2.1%, -0.3%
Active accounts, 9,842, +5%
```
```

The `stat` block renders a row of KPI cards. Columns: `label`, `value`, `delta` (optional).

### Charts

All charts use `` ```chart `` with attributes on the opening fence line:

```markdown
```chart type=bar x=region y=sales title="Sales by Region"
```
```

**Chart attributes:**

| Attribute   | Values / Notes                                      |
|-------------|-----------------------------------------------------|
| `type`      | `bar`, `line`, `area`, `pie`, `donut`, `scatter`   |
| `data`      | Named dataset from front-matter (e.g. `data=sales`)|
| `x`         | Column name for x-axis                              |
| `y`         | Column name for y-axis                              |
| `series`    | Column name to split into multiple series           |
| `title`     | Chart title string                                  |
| `yFormat`   | `currency`, `percent`, `number`                     |
| `color`     | Hex or CSS color for single-series charts           |
| `width`     | `full`, `half`, `third` (layout hint)               |
| `height`    | Pixel height as number                              |

**Chart examples:**

```markdown
# Bar chart from referenced dataset
```chart type=bar data=sales x=region y=revenue title="Revenue by Region"
```

# Line chart with multiple series
```chart type=line data=sales x=month y=revenue series=region yFormat=currency title="Monthly Revenue"
```

# Pie chart
```chart type=pie data=sales x=category y=count title="Deal Mix"
```

# Scatter plot
```chart type=scatter data=users x=age y=spend title="Age vs Spend"
```
```

### Inline Data in Chart Blocks

When no `data=` attribute is given, put CSV inline in the block body:

```markdown
```chart type=bar x=quarter y=revenue title="Quarterly Revenue"
quarter, revenue
Q1, 206000
Q2, 241000
Q3, 198000
Q4, 312000
```
```

### Tables

Standard CommonMark tables work as-is. For data-sourced tables:

```markdown
```table data=sales columns="region,revenue,growth" title="Regional Breakdown"
```
```

## `:::` Containers

Containers wrap content in styled or structural regions.

### Table of Contents

```markdown
::: toc
:::
```

Inserts an auto-generated TOC based on headings in the document.

### Callout / Alert Boxes

```markdown
::: callout
This is an important note rendered in a highlighted box.
:::

::: callout type=warning
Watch out — this may have side effects.
:::

::: callout type=danger
Do not run this in production.
:::
```

Callout types: `info` (default), `warning`, `danger`, `success`.

### Column Layouts

```markdown
::: columns
::: col
Left column content, charts, or stats here.
:::
::: col
Right column content.
:::
:::
```

### Named Style Containers

Apply styles defined in front-matter:

```markdown
::: highlight
This paragraph uses the `highlight` named style from front-matter.
:::

::: danger
Critical warning styled with the `danger` named style.
:::
```

## Complete Document Examples

### Report Document

```markdown
---
title: Q1 2026 Report
theme: report
data:
  sales: ./data/sales.csv
---

::: toc
:::

# Executive Summary

::: callout type=success
Revenue grew 14% YoY, exceeding the $2M target.
:::

```stat
label, value, delta
Total Revenue, $2.06M, +14%
New Customers, 1,238, +8%
NPS Score, 67, +4
```

# Revenue Breakdown

```chart type=line data=sales x=month y=revenue series=region yFormat=currency title="Monthly Revenue by Region"
```

::: columns
::: col
```chart type=bar data=sales x=region y=revenue title="By Region" width=full
```
:::
::: col
```chart type=pie data=sales x=category y=deals title="Deal Mix" width=full
```
:::
:::

# Data Table

```table data=sales columns="region,revenue,deals,growth" title="Full Breakdown"
```
```

### Dashboard Document

```markdown
---
title: Operations Dashboard
theme: dashboard
data:
  ops: ./data/ops.csv
  alerts: ./data/alerts.json
---

# Live Metrics

```stat
label, value, delta
Uptime, 99.97%, +0.02%
Avg Latency, 42ms, -8ms
Error Rate, 0.03%, -0.01%
Active Users, 14,203, +312
```

::: columns
::: col
```chart type=area data=ops x=time y=requests title="Request Volume" yFormat=number
```
:::
::: col
```chart type=line data=ops x=time y=latency_p99 title="P99 Latency (ms)"
```
:::
:::

```chart type=bar data=ops x=service y=errors title="Errors by Service" color=#e53e3e
```
```

### Slide Deck

```markdown
---
title: Product Roadmap 2026
theme: slides
---

# Vision

Our goal: ship faster, break less.

---

# Q1 Achievements

```stat
label, value, delta
Features shipped, 24, +6
Bugs closed, 187, -12%
Deploy frequency, 3.2/day, +40%
```

---

# Revenue Growth

```chart type=bar x=quarter y=arr title="ARR by Quarter" yFormat=currency
quarter, arr
Q1, 1200000
Q2, 1450000
Q3, 1780000
Q4, 2060000
```
```

## Data Formats

### CSV (inline or file)

```csv
region, revenue, growth, deals
North, 680000, 0.18, 142
South, 410000, 0.09, 87
East, 520000, 0.22, 113
West, 450000, 0.11, 98
```

### JSON (file reference)

```json
[
  { "month": "Jan", "revenue": 180000, "region": "North" },
  { "month": "Feb", "revenue": 195000, "region": "North" },
  { "month": "Jan", "revenue": 120000, "region": "South" }
]
```

Reference in front-matter:

```yaml
data:
  sales: ./data/sales.csv
  metrics: ./data/metrics.json
```

## VS Code Extension

Install the VS Code extension for side-by-side live preview:

```bash
cd packages/mdv-vscode
npm install
npm run build
# Then install the generated .vsix via VS Code Ext