Dashdown Docs

Getting started

Install #

Dashdown is published to PyPI as the dashdown-md package, with a CLI entry point named dashdown. The fastest way to get going is to install the CLI globally with uv so dashdown works from any directory:

uv tool install dashdown-md      # `dashdown` on your PATH, usable anywhere

…or run it once without installing, or pin it to a single project:

# Run it ad-hoc, no install, in a throwaway env
uvx --from dashdown-md dashdown new my-dashboard

# …or add it to the current project's environment (pins the version)
uv add dashdown-md
uv run dashdown serve .

# …or with plain pip
pip install dashdown-md

Tip

For a connector or feature, install the matching extra (uv tool install 'dashdown-md[postgres]'). See Installation for every method, the full extras list, upgrading, and fixing a dashdown: command not found PATH issue.

Hacking on Dashdown itself #

Cloning the framework to develop it (not just use it):

uv sync                          # create the venv + install dev deps
uv run pytest tests/ -v          # run the test suite
uv run dashdown serve docs         # preview these docs

Scaffold a project #

dashdown new my-dashboard
cd my-dashboard
dashdown serve .

dashdown serve serves the dashboard at http://127.0.0.1:8000 and live-reloads when you edit a page.

Project layout #

A Dashdown project is a directory the CLI points at:

my-dashboard/
├── dashdown.yaml     # project config (title, auth, embed, branding, …)
├── sources.yaml      # data connectors
├── pages/            # one .md per route  →  pages/sales.md = /sales
│   └── index.md      # the home page  →  /
├── queries/          # optional shared query library (*.sql / *.dax)
├── components/        # optional project-local Python components
├── partials/         # optional Markdown includes
├── data/             # files for the csv/duckdb/excel connectors
└── assets/           # custom.css, logos, images

dashdown.yaml configures the whole dashboard (title, auth, branding, embedding, …) — see Configuration for every block.

Tip

There are two distinct domains: the framework (the dashdown package you install) and your project (the directory above). The CLI points the framework at one project.

These docs are a live project #

This documentation site is itself a Dashdown project — every page you're reading is a pages/*.md rendered by the pipeline it documents. Browse the source under docs/ for a complete, real-world project to learn from.

Next steps #

You have a project running. Where to go from here:

  • Writing pages — frontmatter, callouts, Mermaid, and includes.
  • Queries — :::query blocks, ${param} substitution, and the shared query library.
  • Components — charts, tables, counters, and pivots.
  • Connectors — connect CSVs, Postgres, BigQuery, Fabric, and more.
  • Configuration — every dashdown.yaml block in one place.
  • CLI reference — every dashdown command, including query (probe a connector with raw SQL) and metric (probe the semantic layer by metric + grouping) for testing connections and inspecting real data while you author.
Generated