Show HN: MDV – a Markdown superset for docs, dashboards,...

Show HN: MDV – a Markdown superset for docs, dashboards, and slides with data

Q: How can I embed a CSV file in an MDV document for data analysis?

Use the {{ data('path/to/file.csv') }} directive inside a mdv-table or mdv-chart block. MDV parses the CSV, infers column types, and makes the data available to any downstream visualization.

Q: Is it possible to version‑control MDV reports alongside code in Git?

Absolutely. Because MDV files are plain‑text .mdv, they work seamlessly with Git, enabling diff‑friendly reviews, branch testing, and automated rendering via CI pipelines.

Q: How do I convert an MDV file into a PDF for executive distribution?

After rendering to HTML (mdv render report.mdv --output docs.html), pipe the output through a headless browser like Puppeteer or use Pandoc: pandoc docs.html -o report.pdf. This preserves charts and layout for printable reports.

84 % of data analysts say the biggest bottleneck in their workflow is moving from raw data to a polished report. MDV eliminates that bottleneck by letting you write one Markdown‑style file that instantly becomes a data‑driven document, an interactive dashboard, and a slide deck—all without leaving your favorite editor. Imagine pulling a CSV from your BI tool, adding a few MDV blocks, and publishing a live‑updating analytics report in minutes.

What Is MDV and How Does It Extend Markdown?

Markdown was born to make prose readable in plain text. It’s great for writing docs, but it falls flat when you need to embed live data or visual stories. MDV builds on that foundation by adding a handful of custom code fences and inline directives that bring data, charts, and layout controls into the same file. Think of it as Markdown with a data overlay.

Here’s the low‑down:

mdv-table – Pull a CSV or JSON and render it as a sortable, searchable table.
mdv-chart – Define a Vega‑Lite spec in JSON; MDV auto‑generates the chart and wires it to your data.
mdv-slide – Wrap a section in a slide block so the same file can be turned into a Reveal.js deck.

Because the source is plain text, you can version‑control it, run it through CI, and publish to multiple outputs with a single command line. That’s why I think MDV is a game‑changer for analysts who want to keep everything in one place.

Setting Up MDV – A Quick Start Walkthrough

First thing you’ll do is install the CLI. If you’re on Node, it’s a one‑liner:

npm i -g mdv

Need Docker? No worries; a ready‑made image is available. Once you’ve got MDV, create a folder for your project.

mkdir my-report
cd my-report
touch report.mdv

Open report.mdv and paste this starter content. It pulls a CSV, builds a bar chart, and sets up a slide deck.

---
title: "Quarterly Sales Analysis"
author: "Data Team"
date: "{{ new Date().toLocaleDateString() }}"
---

# Overview
Our sales grew **{{ data('data/sales.csv').sum('revenue') | currency }}** this quarter.

## mdv-filter
{
  "type": "select",
  "field": "region",
  "label": "Region"
}
:::

## mdv-chart
{
  "type": "bar",
  "data": "{{ data('data/sales.csv') }}",
  "x": "month",
  "y": "revenue",
  "color": "region"
}
:::

# Slide Deck
## mdv-slide
# Title Slide
## mdv-slide
# Revenue by Region
{{ chart('mdv-chart') }}
:::

Save the file, then run these commands:

mdv render report.mdv --output docs.html
mdv render report.mdv --output dash.html
mdv render report.mdv --output slides.html

Open each file in your browser. You’ll see a static doc, an interactive dashboard, and a slide deck—all derived from the same source. Pretty cool, right?

Turning Raw Data into Interactive Visualizations

Data binding in MDV is as simple as a template tag. {{ data('sales.csv') }} pulls the file, infers types, and returns a JavaScript object you can reference elsewhere in your document. If you need a specific column, write {{ data('sales.csv').revenue }} and MDV will embed the array.

Next, charts. MDV ships with Vega‑Lite under the hood, so you can write a JSON spec that looks familiar. If you’re new to Vega, the MDV docs include a cheat sheet that covers the most common chart types:

Bar and column charts for comparisons.
Line graphs for trends over time.
Pie and donut for proportional slices.
Heat maps to surface correlations.

Live filtering is a breeze. Add an mdv-filter block with the type you need—select, slider, date range—and MDV automatically wires it to every chart that references the filtered field. That means your dashboards update in real time as you tweak the controls, all without writing a single line of JavaScript.

Why MDV Matters for Data Analysis and Business Decision‑Making

Speed to insight is the single most valuable metric in analytics. When I was stuck in a cycle of pulling data, building a spreadsheet, then hand‑copying charts into PowerPoint, I realized the friction was killing my output. MDV cuts that friction dramatically.

Think about version control. Markdown files are diff‑friendly. You can see line‑by‑line changes, review them on Pull Requests, and roll back if something breaks. In contrast, binary PDFs or proprietary dashboard files are a nightmare for collaboration. MDV keeps everything in the realm of plain text, which means you can push updates, merge branches, and even roll back to a previous analysis state with Git.

Cost is another angle. Most BI tools come with hefty licensing fees and require dedicated infrastructure. MDV, on the other hand, runs on top of Node and uses open‑source libraries like Vega‑Lite. You only pay for the compute you run—so if you host the rendering on a cheap cloud function, the bill stays minimal.

Actionable Takeaways & Next Steps

Pick a pilot. Take a weekly report you hand‑craft in Excel or PowerPoint. Re‑create it in MDV. Measure the time saved.
Automate. Hook MDV into your CI workflow. For instance, a GitHub Actions job could run mdv render on every push to the main branch and deploy the output to a static site.
Explore the ecosystem. The MDV GitHub repo has a growing library of templates: sales dashboards, marketing funnels, finance statements, and even executive decks. Fork one, tweak it, and share your changes back.
Join the community. MDV has a Discord channel where analysts, developers, and designers collaborate on new features and share use cases. Drop by and say hi.

Sound familiar? You’ve probably already been doing some of these things in separate tools. MDV simply stitches them together, so you can focus on insight instead of tooling.

Frequently Asked Questions

How can I embed a CSV file in an MDV document for data analysis?

Use the {{ data('path/to/file.csv') }} directive inside a mdv-table or mdv-chart block. MDV parses the CSV, infers column types, and makes the data available to any downstream visualization.

Can MDV generate interactive dashboards without writing JavaScript?

Yes. MDV’s chart blocks automatically generate Vega‑Lite specifications, and filter blocks add interactivity out‑of‑the‑box, so analysts can build fully interactive dashboards using only Markdown syntax.

What’s the difference between MDV and traditional Markdown for reporting?

Traditional Markdown renders static text and images, while MDV adds data‑aware blocks, live charts, and slide‑deck capabilities, turning a single source file into a multi‑format analytics product.

Is it possible to version‑control MDV reports alongside code in Git?

Absolutely. Because MDV files are plain‑text .mdv, they work seamlessly with Git, enabling diff‑friendly reviews, branch testing, and automated rendering via CI pipelines.

How do I convert an MDV file into a PDF for executive distribution?

After rendering to HTML (mdv render report.mdv --output docs.html), pipe the output through a headless browser like Puppeteer or use Pandoc: pandoc docs.html -o report.pdf. This preserves charts and layout for printable reports.

Code & Crumbs

Search This Blog