Dashdown Documentation

Dashdown turns Markdown files — with embedded SQL and component tags — into interactive analytics dashboards. No JavaScript to write, no frontend toolchain. You write .md, point the CLI at the folder, and get a live dashboard.

These docs are themselves a Dashdown project. Every page here is a pages/*.md file rendered by the very pipeline it describes, and the chart below is a live query against a CSV. Read the source under docs/.

A page is just Markdown + SQL + components #

:::query name=downloads_by_month connector=main
SELECT month, SUM(downloads) AS downloads
FROM downloads GROUP BY month ORDER BY month
:::

<LineChart data={downloads_by_month} x="month" y="downloads" title="Downloads" />

That snippet renders this — real widgets, drawn in your browser from the query result (here via the shared queries/downloads_by_month.sql):

Try the search #

Press / anywhere, or click the box above, and type — for example connector, pdf, or injection. Results rank pages and jump straight to the matching section. It is a built-in component, <SiteSearch />, backed by an index of every page; it works the same on the live server and in a static export.

AI ready #

Dashdown is built to be authored with a coding agent. dashdown new scaffolds a tool-agnostic AGENTS.md guide (plus a Claude Code skill) into every project, the CLI exposes its own catalog so an agent checks facts instead of guessing, and the whole manual ships as llms.txt for any model to read. See Coding agents →.

Point an agent straight at a task:

• Query JSON / nested data — read local or remote JSON in SQL: unnest() arrays, struct fields, 1-indexed lists, quoting reserved words, and the quoted-string ${param} rule.
• Write a custom data-driven component — the data-async-component placeholder contract, the /_dashdown/api/data shape (rows are arrays), self-init JS, and reading the baked snapshot in a static build.
• Export dynamic detail pages — the static_paths frontmatter that pre-renders one page (and one snapshot) per record, plus how ${param} reaches data.

Where to go next #

• Installation — install the CLI globally, uvx, extras, PATH.
• Getting started — install, scaffold, run.
• Examples — real demo dashboards, live and cloneable.
• Configuration — every dashdown.yaml block in one place.
• Writing pages — frontmatter, callouts, Mermaid, includes.
• Detail pages — drill-down sub pages with clickable table rows.
• Components — charts, tables, counters, pivots.
• Formatting — number, currency, percent & date display; project-wide locale.
• Filters & parameters — dropdowns, search, date ranges.
• Queries — the shared library, params, injection safety.
• Python queries — define a query as Python (forecasts, ML, cross-connector joins).
• Real-time data — live-streaming queries that repaint as data changes.
• Connectors — CSV, Postgres, BigQuery, Fabric, and more.
• AI — LLM commentary in your dashboard (<Ask />) + building with coding agents.
• Full-text search — how <SiteSearch /> works.
• Exporting — static builds, PDF, CSV.
• Embedding — drop a page into another site.
• Authentication — password-protect a dashboard.
• Extending — write your own components and connectors.
• CLI reference — every dashdown command from the terminal.

---