Mdv Markdown Visualization

MDV Markdown Data & Visualization

Skill by 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

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

# 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

---
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

Fenced Visualization Blocks

Stat / KPI Cards

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:

Chart attributes:

Chart examples:

# Bar chart from referenced dataset

# Line chart with multiple series

# Pie chart

# Scatter plot

Inline Data in Chart Blocks

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

quarter, revenue Q1, 206000 Q2, 241000 Q3, 198000 Q4, 312000

Tables

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

::: Containers

Containers wrap content in styled or structural regions.

Table of Contents

::: toc
:::

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

Callout / Alert Boxes

::: 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

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

Named Style Containers

Apply styles defined in front-matter:

::: 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

---
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.
:::

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

# Revenue Breakdown

::: columns
::: col

:::
::: col

:::
:::

# Data Table

Dashboard Document

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

# Live Metrics

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

:::
::: col

:::
:::

Slide Deck

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

# Vision

Our goal: ship faster, break less.

---

# Q1 Achievements

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

---

# Revenue Growth

quarter, arr Q1, 1200000 Q2, 1450000 Q3, 1780000 Q4, 2060000

Data Formats

CSV (inline or file)

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)

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

Reference in front-matter:

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

VS Code Extension

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

cd packages/mdv-vscode
npm install
npm run build