The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
title: Developing Metabase documentation
Developing Metabase documentation
Notes on writing docs for Metabase.
Linting markdown links
You can check for broken links in the docs directory by running:
bun run docs-lint-links
This command uses Markdown link check to vet links in all of the markdown files in the docs directory. We recommend writing the command's output to a file. E.g.,
touch ~/links-to-fix.txt && bun run docs-lint-links > ~/links-to-fix.txt
Alternatively, if you just want to check the in-product links (the pages passed to useDocsUrl and getDocsUrl) to make sure they link to actual documents and headings:
bun run lint-docs-links
You can view both commands in the package.json file under scripts.
Preview docs as you write them
You'll need Bun and a checkout of the private metabase-dot-com repo at ~/metabase-dot-com. Then run:
./bin/mage docs-preview
Your browser opens http://localhost:4000/docs/latest/, and your edits show up as you save them. Only /docs/latest/ pages work.
To preview a worktree or another checkout, pass its path. If metabase-dot-com is somewhere else, pass --site DIR or set METABASE_DOT_COM_DIR.
Regenerate docs built from source
Some docs pages are generated from the source code. A scheduled GitHub workflow regenerates them every weekday and opens a PR with any changes.
To regenerate them yourself, first install the prerequisites for building Metabase: Java, the Clojure CLI, Node.js, and Bun. You don't need to install Babashka, since ./bin/mage installs it for you. Then install the frontend dependencies:
bun install
Then run:
./bin/mage docs-generate
To regenerate one group of pages, pass its suite name. For example:
./bin/mage docs-generate backend
To list the suites, run ./bin/mage docs-generate -h. If any suite fails, the last line of output lists it.
Updating API docs
To update an API endpoint description, you'll need to edit the comment in the source code for that endpoint.
To bring your changes into docs/latest/api-documentation, you'll need to open a separate PR. Check out a new branch from the current release branch, and run:
clojure -M:ee:doc api-documentation
Style guide
Ancient style guide that needs an update.