dataform-docs

Generate beautiful, interactive documentation for your Dataform projects with dependency graphs, pipeline isolation, and auto-zoom functionality.

Features

✨ Interactive Dependency Graph - Visualize your entire data pipeline with hierarchical DAG layout 🔍 Pipeline Isolation - Focus on specific models and their dependencies 🎯 Auto-zoom - Automatically zoom to isolated pipelines for better visibility 📊 Column Definitions - View table schemas and column descriptions 🔗 Deep Linking - Share direct links to specific models with full URL state management 🌐 Base Path Support - Deploy under custom paths for proxy/subdirectory hosting 🚀 Fast & Static - Generates self-contained HTML that can be hosted anywhere

Demo

🌟 View Live Demo - Interactive climbing database documentation

Requirements

• Node.js 16 or higher
• Dataform CLI - Automatically installed as a dependency for optimal column extraction and compilation

Quick Start

The easiest way to use dataform-docs is with npx (no installation required):

# From your Dataform project directory
npx dataform-docs generate
npx dataform-docs serve

Open http://localhost:4200 to view your documentation.

Installation

Global Installation (Recommended)

npm install -g dataform-docs

Then from any Dataform project:

dataform-docs generate
dataform-docs serve

Local Installation

npm install --save-dev dataform-docs

Add to your package.json scripts:

{
  "scripts": {
    "docs:generate": "dataform-docs generate",
    "docs:serve": "dataform-docs serve",
    "docs": "dataform-docs generate && dataform-docs serve"
  }
}

Usage

Generate Documentation

dataform-docs generate [options]

Options:
  -p, --project <path>    Path to Dataform project (default: current directory)
  -o, --output <path>     Output directory for documentation (default: ./dataform-docs)
  -b, --base-path <path>  Base path for serving the documentation (e.g., /dataform/docs/)
  --no-compile            Skip SQL compilation

Serve Documentation

dataform-docs serve [options]

Options:
  -p, --port <number>     Port to serve on (default: 4200)
  -d, --dir <path>        Directory to serve (default: ./dataform-docs)
  -b, --base-path <path>  Base path for routing (e.g., /dataform/docs/)
  --open                  Open browser automatically

Base Path Support

Use base paths when deploying under custom URL paths or proxy configurations:

Local Development with Base Path

# Generate with base path
dataform-docs generate -b /my-project/docs/

# Serve with base path
dataform-docs serve -b /my-project/docs/
# Opens http://localhost:4200/my-project/docs/

Common Deployment Scenarios

GitHub Pages with Project Path

# For https://username.github.io/project-name/dataform/
dataform-docs generate -o ./docs -b /project-name/dataform/

Proxy/Subdirectory Hosting

# For https://company.com/internal/dataform-docs/
dataform-docs generate -b /internal/dataform-docs/
dataform-docs serve -b /internal/dataform-docs/

Docker/Kubernetes with Ingress

# For ingress path /api/v1/dataform/
dataform-docs generate -b /api/v1/dataform/

Deploy to GitHub Pages

# Generate docs with GitHub Pages base path
dataform-docs generate -o ./docs -b /your-repo-name/

# Commit and push
git add docs
git commit -m "Update documentation"
git push

# Enable GitHub Pages from /docs folder in repository settings

Requirements

• Node.js 16.0.0 or higher
• A Dataform project with dataform.json configuration

License

MIT