Back to Details

mdv-markdown-visualization

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MDV Markdown Data & Visualization

MDV Markdown数据与可视化

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.
由ara.so开发的Skill — 属于Daily 2026 Skills系列。
MDV是一款Markdown超集（
.mdv
文件），可在单一工作流中编写报告、仪表板和幻灯片，然后导出为独立的HTML或PDF文件。它在CommonMark基础上扩展了四项功能：YAML前置元数据、围栏式可视化块、用于布局的
:::
容器，以及自动生成的目录。

Installation & Setup

安装与设置

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

Render a file to HTML

将文件渲染为HTML

node packages/mdv-cli/dist/index.js render examples/09-full-report.mdv
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
node packages/mdv-cli/dist/index.js preview examples/09-full-report.mdv

Export to PDF

导出为PDF

node packages/mdv-cli/dist/index.js export --pdf examples/09-full-report.mdv
undefined
node packages/mdv-cli/dist/index.js export --pdf examples/09-full-report.mdv
undefined

CLI Commands

CLI命令

bash
undefined
bash
undefined

Render .mdv → self-contained HTML

将.mdv渲染为独立HTML

node packages/mdv-cli/dist/index.js render <file.mdv> node packages/mdv-cli/dist/index.js render <file.mdv> --out output.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>
node packages/mdv-cli/dist/index.js preview <file.mdv>

PDF export

PDF导出

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

File Structure

文件结构

.mdv project/
├── data/
│   ├── sales.csv
│   └── metrics.json
├── report.mdv
└── dashboard.mdv
.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
每个
.mdv
文件包含三个部分：
  1. YAML前置元数据 — 元信息、主题、命名样式、数据集引用
  2. Markdown主体 — 标准CommonMark文本内容
  3. 围栏块与容器 — 图表、统计数据、提示框、列布局

YAML Front-Matter

YAML前置元数据

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

可用主题

ThemeBest for
report
Long-form documents, articles
dashboard
KPI cards, dense data layouts
slides
Presentations, slide decks
minimal
Clean, unstyled output
主题适用场景
report
长篇文档、文章
dashboard
KPI卡片、密集数据布局
slides
演示文稿、幻灯片
minimal
简洁、无样式输出

Fenced Visualization Blocks

围栏式可视化块

Stat / KPI Cards

统计/KPI卡片

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).
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%

`stat`块会渲染一行KPI卡片。列包括：`label`（标签）、`value`（数值）、`delta`（变化量，可选）。

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
所有图表使用
```chart
语法，并在起始围栏行添加属性：
markdown
```chart type=bar x=region y=sales title="Sales by Region"

**图表属性：**

| 属性         | 取值/说明                                      |
|-------------|-----------------------------------------------------|
| `type`      | `bar`（柱状图）、`line`（折线图）、`area`（面积图）、`pie`（饼图）、`donut`（环形图）、`scatter`（散点图） |
| `data`      | 前置元数据中定义的命名数据集（例如`data=sales`） |
| `x`         | X轴对应的列名                              |
| `y`         | Y轴对应的列名                              |
| `series`    | 用于拆分多系列的列名           |
| `title`     | 图表标题字符串                                  |
| `yFormat`   | `currency`（货币）、`percent`（百分比）、`number`（数字）                     |
| `color`     | 单系列图表的十六进制或CSS颜色值           |
| `width`     | `full`（全屏）、`half`（半屏）、`third`（三分之一屏）（布局提示）               |
| `height`    | 像素高度数值                              |

**图表示例：**

```markdown

Bar chart from referenced dataset

基于引用数据集的柱状图

chart
undefined
chart
undefined

Line chart with multiple series

多系列折线图

chart
undefined
chart
undefined

Pie chart

饼图

chart
undefined
chart
undefined

Scatter plot

散点图

chart
undefined
undefined
chart
undefined
undefined

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
undefined
当未指定
data=
属性时，可在块体中直接写入CSV数据：
markdown
```chart type=bar x=quarter y=revenue title="Quarterly Revenue"
quarter, revenue
Q1, 206000
Q2, 241000
Q3, 198000
Q4, 312000
undefined

Tables

表格

Standard CommonMark tables work as-is. For data-sourced tables:
markdown
```table data=sales columns="region,revenue,growth" title="Regional Breakdown"
undefined
标准CommonMark表格可直接使用。如需基于数据生成表格：
markdown
```table data=sales columns="region,revenue,growth" title="Regional Breakdown"
undefined

:::
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.
markdown
::: toc
:::
插入基于文档标题自动生成的目录。

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
.
markdown
::: callout
这是一条重要提示，会渲染为高亮框。
:::

::: callout type=warning
请注意——这可能会产生副作用。
:::

::: callout type=danger
请勿在生产环境中运行此内容。
:::
提示框类型：
info
（默认）、
warning
（警告）、
danger
（危险）、
success
（成功）。

Column Layouts

列布局

markdown
::: columns
::: col
Left column content, charts, or stats here.
:::
::: col
Right column content.
:::
:::
markdown
::: columns
::: col
左侧列内容、图表或统计数据放在此处。
:::
::: col
右侧列内容。
:::
:::

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.
:::
应用前置元数据中定义的样式：
markdown
::: highlight
此段落使用前置元数据中定义的`highlight`命名样式。
:::

::: danger
使用`danger`命名样式渲染的严重警告。
:::

Complete Document Examples

完整文档示例

Report Document

报告文档

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

::: toc
:::
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
::: callout type=success 收入同比增长14%，超出200万美元目标。 :::
stat
label, value, delta
Total Revenue, $2.06M, +14%
New Customers, 1,238, +8%
NPS Score, 67, +4

Revenue Breakdown

收入细分

chart
undefined
::: columns ::: col
chart
undefined
::: ::: col
chart
undefined
::: :::
chart
undefined
::: columns ::: col
chart
undefined
::: ::: col
chart
undefined
::: :::

Data Table

数据表格

table
undefined
undefined
table
undefined
undefined

Dashboard Document

仪表板文档

markdown
---
title: Operations Dashboard
theme: dashboard
data:
  ops: ./data/ops.csv
  alerts: ./data/alerts.json
---
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
undefined
::: ::: col
chart
undefined
::: :::
chart
undefined
undefined
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
undefined
::: ::: col
chart
undefined
::: :::
chart
undefined
undefined

Slide Deck

幻灯片演示文稿

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

Vision

愿景

Our goal: ship faster, break less.
我们的目标：更快交付，更少故障。

Q1 Achievements

Q1成果

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

Revenue Growth

收入增长

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

Data Formats

数据格式

CSV (inline or file)

CSV（内联或文件）

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
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（文件引用）

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
json
[
  { "month": "Jan", "revenue": 180000, "region": "North" },
  { "month": "Feb", "revenue": 195000, "region": "North" },
  { "month": "Jan", "revenue": 120000, "region": "South" }
]
在前置元数据中引用：
yaml
data:
  sales: ./data/sales.csv
  metrics: ./data/metrics.json

VS Code Extension

VS Code扩展

Install the VS Code extension for side-by-side live preview:
bash
cd packages/mdv-vscode
npm install
npm run build
安装VS Code扩展以实现侧边实时预览：
bash
cd packages/mdv-vscode
npm install
npm run build

Then install the generated .vsix via VS Code Extensions panel → "Install from VSIX"

然后通过VS Code扩展面板 → "从VSIX安装" 安装生成的.vsix文件


Once installed:
- Open any `.mdv` file
- Press `Ctrl+Shift+P` → **MDV: Open Preview**
- Preview updates on every save

See `docs/vscode.md` and `docs/publishing-vscode-extension.md` for marketplace publishing.

安装完成后：
- 打开任意`.mdv`文件
- 按下`Ctrl+Shift+P` → **MDV: Open Preview**（MDV：打开预览）
- 预览会在每次保存时更新

查看`docs/vscode.md`和`docs/publishing-vscode-extension.md`了解市场发布相关内容。

Project Package Structure

项目包结构

packages/
├── mdv-core/        # Parser, renderer, chart engine (TypeScript)
├── mdv-cli/         # CLI: render, preview, export commands
└── mdv-vscode/      # VS Code extension with live preview
packages/
├── mdv-core/        # 解析器、渲染器、图表引擎（TypeScript）
├── mdv-cli/         # CLI：渲染、预览、导出命令
└── mdv-vscode/      # 带实时预览的VS Code扩展

Common Patterns

常见模式

Pattern: Dashboard with KPIs + Charts

模式：带KPI+图表的仪表板

markdown
---
title: Sales Dashboard
theme: dashboard
data:
  pipeline: ./data/pipeline.csv
---

```stat
label, value, delta
Pipeline, $4.2M, +22%
Deals Open, 94, +11
Win Rate, 31%, +3%
Avg Deal Size, $44.7K, +8%
chart
undefined
::: columns ::: col
chart
undefined
::: ::: col
chart
undefined
::: :::
undefined
markdown
---
title: Sales Dashboard
theme: dashboard
data:
  pipeline: ./data/pipeline.csv
---

```stat
label, value, delta
Pipeline, $4.2M, +22%
Deals Open, 94, +11
Win Rate, 31%, +3%
Avg Deal Size, $44.7K, +8%
chart
undefined
::: columns ::: col
chart
undefined
::: ::: col
chart
undefined
::: :::
undefined

Pattern: Callout + Inline Data Chart

模式：提示框+内联数据图表

markdown
::: callout type=warning
Revenue dipped in March due to seasonal effects.
:::

```chart type=area x=month y=revenue title="Revenue Trend"
month, revenue
Jan, 180000
Feb, 195000
Mar, 162000
Apr, 201000
May, 224000
undefined
markdown
::: callout type=warning
受季节性影响，3月份收入有所下降。
:::

```chart type=area x=month y=revenue title="Revenue Trend"
month, revenue
Jan, 180000
Feb, 195000
Mar, 162000
Apr, 201000
May, 224000
undefined

Pattern: Named Styles for Emphasis

模式：使用命名样式强调内容

yaml
---
styles:
  metric-good:
    background: "#f0fff4"
    border-left: "4px solid #38a169"
  metric-bad:
    background: "#fff5f5"
    border-left: "4px solid #e53e3e"
---
markdown
::: metric-good
**Churn** dropped to 1.8% this quarter — lowest in 3 years.
:::

::: metric-bad
**Support tickets** up 23% — investigate root cause.
:::
yaml
---
styles:
  metric-good:
    background: "#f0fff4"
    border-left: "4px solid #38a169"
  metric-bad:
    background: "#fff5f5"
    border-left: "4px solid #e53e3e"
---
markdown
::: metric-good
**客户流失率**本季度降至1.8%——为3年来最低水平。
:::

::: metric-bad
**支持工单**增加23%——需调查根本原因。
:::

Troubleshooting

故障排除

Build fails: Run 
npm install
from the repo root before 
npm run build
. All packages must build together.
Charts render blank: Ensure 
data=
references a dataset name defined in front-matter, and the CSV/JSON file path is correct relative to the 
.mdv
file.
PDF export fails: PDF export typically requires a headless browser (Puppeteer/Chromium). Ensure dependencies are installed: 
npm install
in 
packages/mdv-cli
.
Preview not updating: The 
preview
command watches for file saves. Ensure you're saving the 
.mdv
file (not just a data file). If a data file changed, re-save the 
.mdv
to trigger reload.
VS Code extension not showing preview: Confirm the extension built successfully (
npm run build
in 
packages/mdv-vscode
) and was installed from the 
.vsix
. Open a 
.mdv
file specifically — the preview command only activates on 
.mdv
files.
Inline CSV not parsing: Ensure column names have no leading/trailing spaces and that delimiter is a comma. The first non-empty line of an inline block is treated as the header row.
Theme not applying: Theme names are case-sensitive. Valid values: 
report
, 
dashboard
, 
slides
, 
minimal
.
构建失败： 在运行
npm run build
前，先从仓库根目录执行
npm install
。所有包必须一起构建。
图表渲染空白： 确保
data=
引用的数据集名称已在前置元数据中定义，且CSV/JSON文件路径相对于
.mdv
文件是正确的。
PDF导出失败： PDF导出通常需要无头浏览器（Puppeteer/Chromium）。确保已安装依赖：在
packages/mdv-cli
目录下执行
npm install
。
预览不更新： 
preview
命令会监听文件保存。确保你保存的是
.mdv
文件（而不仅仅是数据文件）。如果数据文件发生更改，重新保存
.mdv
文件以触发重载。
VS Code扩展不显示预览： 确认扩展已成功构建（在
packages/mdv-vscode
目录下执行
npm run build
），且已从
.vsix
文件安装。请打开特定的
.mdv
文件——预览命令仅对
.mdv
文件生效。
内联CSV解析失败： 确保列名没有前后空格，且分隔符为逗号。内联块的第一行非空行将被视为表头行。
主题未生效： 主题名称区分大小写。有效值：
report
、
dashboard
、
slides
、
minimal
。

Key Files for Contributors

贡献者关键文件

packages/mdv-core/src/
├── parser.ts        # CommonMark + MDV extensions parser
├── renderer.ts      # HTML renderer
├── chart.ts         # SVG chart engine
├── data.ts          # CSV/JSON data loader
└── theme.ts         # Theme & named style resolution

packages/mdv-cli/src/
└── index.ts         # CLI entry: render | preview | export

packages/mdv-vscode/src/
└── extension.ts     # VS Code extension + preview panel
packages/mdv-core/src/
├── parser.ts        # CommonMark + MDV扩展解析器
├── renderer.ts      # HTML渲染器
├── chart.ts         # SVG图表引擎
├── data.ts          # CSV/JSON数据加载器
└── theme.ts         # 主题与命名样式解析

packages/mdv-cli/src/
└── index.ts         # CLI入口：render | preview | export

packages/mdv-vscode/src/
└── extension.ts     # VS Code扩展 + 预览面板