SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场mdv-markdown-visualization

mdv-markdown-visualization

写作与研究

查看项目

更新于 10-15 09:12

技能介绍

用途

MDV 是 Markdown 的超集，使用 .mdv 文件，面向报告、Dashboard 与幻灯片三种文档形态。它的目标是在同一个工作流中完成写作、嵌入图表与 KPI 数据，并导出为自包含的 HTML 或 PDF。

主要能力

MDV 在 CommonMark 之上扩展了四项内容：

  • YAML front-matter：存放元数据、主题、命名样式和数据引用。
  • 围栏式可视化代码块：包括 stat（KPI 卡片）、chart（图表）、table（数据表）等。
  • ::: 容器：用于布局与结构，如目录、提示框、列布局以及引用 front-matter 中定义的命名样式。
  • 自动生成的目录。

主题

front-matter 中的 theme 可选值为 report（长文文档、文章）、dashboard（KPI 卡片、密集数据布局）、slides（演示幻灯片）、minimal（干净的无样式输出）。

stat 块

stat 块渲染一行 KPI 卡片，列为 label、value、delta（可选）。

chart 块

图表使用围栏 chart 加属性描述，支持的属性包括：type（bar、line、area、pie、donut、scatter）、data（引用 front-matter 中命名的数据集）、x、y、series、title、yFormat（currency、percent、number）、color、width（full、half、third）、height（像素数值）。当未给出 data= 属性时，可以在代码块正文中直接写内联 CSV。

table 块

标准 CommonMark 表格可直接使用；数据来源表格可用 table 块加 data、columns、title 属性。

::: 容器

支持的容器包括：toc（依据标题自动生成目录）、callout（提示框，类型有 info 默认、warning、danger、success）、columns 与 col（列布局），以及引用 front-matter 中定义的命名样式容器。

使用方式

安装与构建：

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

渲染为 HTML：

node packages/mdv-cli/dist/index.js render examples/09-full-report.mdv

实时预览（自动重载）：

node packages/mdv-cli/dist/index.js preview examples/09-full-report.mdv

导出 PDF：

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

CLI 命令说明：

  • render <file.mdv>：渲染为自包含 HTML；可加 --out output.html 指定输出文件。
  • preview <file.mdv>：打开浏览器并实时预览，保存时自动重载。
  • export --pdf <file.mdv>：导出 PDF；可加 --out report.pdf 指定输出文件。

VS Code 扩展

cd packages/mdv-vscode npm install npm run build

然后通过 VS Code 扩展面板的 "Install from VSIX" 安装生成的 .vsix。安装后打开任意 .mdv 文件，按 Ctrl+Shift+P → MDV: Open Preview，预览会在每次保存时更新。

文档结构

每个 .mdv 文件包含三个区域：YAML front-matter（元数据、主题、命名样式、数据集引用）、Markdown 正文（标准 CommonMark 散文），以及围栏代码块与容器（图表、统计、提示框、列）。

数据格式

支持 CSV（内联或文件）与 JSON（文件引用）。在 front-matter 中通过 data 键引用，例如：

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

项目包结构

packages/ ├── mdv-core/ # 解析器、渲染器、图表引擎（TypeScript） ├── mdv-cli/ # CLI：render、preview、export 命令 └── mdv-vscode/ # 带实时预览的 VS Code 扩展

适用场景

  • 长篇报告：使用 report 主题，配合 toc、callout、stat 与 chart 组织叙述与数据。
  • Dashboard：使用 dashboard 主题，密集排列 KPI 卡片与图表。
  • 幻灯片：使用 slides 主题，以 --- 分隔幻灯片页面，嵌入统计与图表。

限制与注意事项

  • 构建需在仓库根目录先执行 npm install 再 npm run build，所有包需一起构建。
  • 图表空白通常是因为 data= 未引用 front-matter 中定义的数据集名，或 CSV/JSON 文件路径相对 .mdv 文件不正确。
  • PDF 导出通常依赖无头浏览器（Puppeteer/Chromium），需在 packages/mdv-cli 中安装依赖。
  • 预览只监视文件保存；数据文件变更后需重新保存 .mdv 才触发重载。
  • 主题名大小写敏感，有效值为 report、dashboard、slides、minimal。
  • 内联 CSV 解析要求列名无前后空格、分隔符为逗号，首个非空行视为表头。
  • 关于收费、价格与平台支持情况，资料中暂未提供。

贡献者关键文件

packages/mdv-core/src/ 下包括 parser.ts、renderer.ts、chart.ts、data.ts、theme.ts；packages/mdv-cli/src/ 下为 index.ts；packages/mdv-vscode/src/ 下为 extension.ts。