Stop Wrestling with BI Tools! Evidence Makes Reports from SQL + Markdown

What if I told you that your entire BI workflow is broken? Not slightly inefficient. Not "could be better." Fundamentally, irreversibly broken.

You've been there. Staring at yet another drag-and-drop dashboard builder, clicking through endless menus, watching the spinning wheel of death while your "simple" visualization takes twelve clicks and three submenus to create. You've felt the soul-crushing moment when your carefully crafted dashboard breaks because someone renamed a column. You've experienced the version control nightmare of trying to figure out who changed what and when in a tool that treats "history" as a premium feature.

Here's the dirty secret the BI industry doesn't want you to know: the future of business intelligence isn't more buttons—it's more code.

Enter Evidence, the open-source project that's making waves across the data engineering community. This isn't another dashboard builder. This is business intelligence as code—a radical reimagining of how we create, share, and maintain data reports. Generate fast, interactive data visualizations using nothing but SQL and markdown. Version control your entire analytics pipeline. Deploy anywhere. And never click "add chart" again.

The data world is paying attention. With thousands of GitHub stars and a thriving Slack community, Evidence represents a fundamental shift in how technical teams approach BI. Ready to understand why top developers are abandoning traditional tools? Let's dive deep.

What is Evidence?

Evidence is an open-source, code-based alternative to drag-and-drop business intelligence tools that transforms how technical teams build and share data products. Created by the team at Evidence Dev, this project emerged from a simple but powerful observation: modern data teams already work in code—why should their reporting tools force them into graphical interfaces?

The philosophy behind Evidence is elegantly straightforward. Instead of wrestling with proprietary BI platforms that lock your logic behind click-based interfaces, Evidence lets you define entire analytics applications using two technologies you already know: SQL for data transformation and markdown for presentation. The result? A static website generated from your code, fully version-controllable, endlessly customizable, and deployable anywhere.

What makes Evidence particularly compelling right now is the convergence of several industry trends. The "analytics engineering" movement, pioneered by tools like dbt, has trained a generation of data professionals to think in code-first workflows. Git-based collaboration has become non-negotiable for serious technical teams. And the frustration with traditional BI's pricing models, vendor lock-in, and collaboration limitations has reached a breaking point.

Evidence rides this wave perfectly. It integrates seamlessly with modern data stacks—Snowflake, BigQuery, Postgres, DuckDB, and more—while outputting clean, fast static sites. The project has attracted attention from data leaders at major organizations who see it as the missing piece between the data warehouse and the end user. No more "throw it over the wall to the BI team." No more maintaining logic in two places. Just pure, auditable, beautiful code.

The project also offers Evidence Studio, a new faster way to build data products with SQL, markdown, and AI—bridging the gap between pure code and guided experiences for teams that want the best of both worlds.

Key Features That Make Evidence Irresistible

Evidence packs a surprising amount of power into its deceptively simple approach. Let's break down the capabilities that make developers genuinely excited:

SQL-Native Query Execution Evidence runs SQL statements directly inside your markdown files against connected data sources. No abstraction layers. No proprietary query languages hiding your logic. Just pure SQL against your actual database, with results flowing directly into your visualizations. This means you can leverage every optimization, window function, and CTE your database supports.

Markdown-Driven Content Creation The entire presentation layer uses standard markdown enhanced with Evidence's component system. Headers, paragraphs, links—everything you expect—plus specialized components for charts, tables, and data displays. The learning curve is essentially zero if you've ever written documentation or a README.

Templated Page Generation This is where Evidence gets seriously powerful. Create a single markdown template and generate hundreds of pages automatically based on query results. Imagine building a personalized dashboard for every customer, every product, every region—without copying and pasting a single widget. The templating system uses loops and conditional logic to control what displays dynamically.

Component-Based Visualizations Evidence includes a rich library of pre-built visualization components—LineCharts, BarCharts, DataTables, Value displays, and more. These aren't static images; they're interactive, responsive, and customizable through simple props. Need a bespoke visualization? The component architecture supports custom Svelte components for unlimited flexibility.

Full Programmatic Control Loops and If/Else statements embedded in your markdown give you complete control over the user experience. Show different content based on data conditions. Generate dynamic headers. Create complex, context-aware reports that adapt to the underlying data automatically.

Modern Deployment Options Evidence outputs static sites, making deployment trivial on Netlify, Vercel, GitHub Pages, or any static hosting platform. Self-host for maximum control, or use managed services for zero-maintenance deployments. Your entire analytics site becomes just another artifact in your CI/CD pipeline.

Real-World Use Cases Where Evidence Dominates

Still wondering if Evidence fits your workflow? These concrete scenarios demonstrate where it truly shines:

Embedded Analytics for SaaS Products Need to provide analytics dashboards to your customers without building a custom frontend? Evidence generates white-labelable static sites you can iframe or proxy behind your authentication. Version control each customer's logic, customize per-tenant with templating, and deploy updates with git pushes. Traditional BI tools make this nearly impossible; Evidence makes it elegant.

Internal Data Documentation Every data team struggles with documentation that stays current. With Evidence, your documentation is your queries. Create living data dictionaries where column definitions sit alongside real-time data samples. Build metric trees that show actual values, not just formulas. When the data updates, the documentation updates automatically—no manual refresh required.

Investor and Executive Reporting Board decks with stale screenshots are embarrassing. Evidence lets you build always-current executive summaries that refresh on schedule. Embed them directly in Notion, Slack, or your intranet. When the CEO asks "what's our current MRR?" the answer is already live, not "I'll get back to you after I refresh the dashboard."

Multi-Tenant Analytics at Scale Using templated pages, generate personalized analytics portals for hundreds of clients from a single codebase. Each sees only their data, with consistent branding and layout. Update the template once, and every client's experience improves immediately. Compare this to maintaining hundreds of dashboard copies in traditional BI tools—a maintenance nightmare Evidence eliminates entirely.

Data Quality and Observability Reports Build automated data quality dashboards that run dbt tests, Great Expectations validations, or custom SQL checks, then publish beautiful reports of pass/fail status. Schedule these to run with your pipelines, creating permanent audit trails of data health over time.

Step-by-Step Installation & Setup Guide

Getting started with Evidence is refreshingly straightforward. The project offers multiple installation paths depending on your preferences.

Method 1: VS Code Extension (Recommended for Beginners)

The fastest path to your first Evidence project:

Install the Extension: Download the Evidence VSCode Extension from the marketplace
Create New Project: Open the Command Palette (F1 or Cmd+Shift+P) and type Evidence: New Evidence Project
Launch Development Server: Click the Start Evidence button that appears in VS Code's bottom status bar

That's it. Your browser opens to a live development environment with hot reloading.

Method 2: Command Line Installation

For developers who prefer terminal workflows:

# Create a new Evidence project using npx
npx degit evidence-dev/template my-evidence-project

# Navigate into your project
cd my-evidence-project

# Install dependencies
npm install

# Start the development server
npm run dev

Method 3: Docker Deployment

For containerized environments or teams wanting reproducible setups:

# Pull and run the Evidence Docker image
docker run -v $(pwd):/evidence/projects -p 3000:3000 evidence-dev/evidence

Configuration Steps

After installation, configure your data sources in evidence.config.yaml:

# evidence.config.yaml - Define your database connections
connections:
  my_postgres_db:
    type: postgres
    host: localhost
    port: 5432
    database: analytics
    user: ${POSTGRES_USER}      # Use environment variables for secrets
    password: ${POSTGRES_PASSWORD}
  
  my_bigquery_project:
    type: bigquery
    project_id: my-gcp-project
    key_file: /path/to/service-account.json

Environment variables keep credentials secure and support different configs across development, staging, and production environments.

Production Build and Deployment

When ready to deploy:

# Generate optimized static site
npm run build

# Output lands in /build directory, ready for any static host
# Deploy to Netlify
netlify deploy --build --prod

# Or deploy to Vercel
vercel --prod

The static output means zero server maintenance, instant global CDN distribution, and effortless scaling.

REAL Code Examples from the Repository

Evidence's power becomes clear when you see actual implementation. Here are concrete patterns drawn from the project's documentation and typical usage.

Example 1: Basic Query and Chart

The foundation of every Evidence report: write SQL, get results, visualize immediately.

# Sales Performance Dashboard

## Monthly Revenue Trend

First, we query our data warehouse for aggregated monthly metrics:

```sql sales_by_month
SELECT
    DATE_TRUNC('month', order_date) as month,
    SUM(revenue) as total_revenue,
    COUNT(DISTINCT customer_id) as unique_customers
FROM orders
WHERE order_date >= '2023-01-01'
GROUP BY 1
ORDER BY 1

Then render an interactive line chart with a single component:

Key insight: {sales_by_month[0].unique_customers} customers drove our latest month's performance.


Notice how the SQL block is named (`sales_by_month`) and referenced directly in the component. No data pipelines to configure. No extract-transform-load steps. The query executes at build time, and results feed straight into the visualization.

### Example 2: Templated Pages for Dynamic Content Generation

This is where Evidence's efficiency becomes **insane** for scale operations:

```markdown
---
sources:
    - orders: orders.sql
---

# Customer Detail: {params.customer_id}

```sql customer_metrics
SELECT *
FROM ${orders}
WHERE customer_id = '${params.customer_id}'


Save this as `[customer_id].md` and Evidence automatically generates pages for every customer in your dataset. The `params.customer_id` captures from the URL path. One template, infinite personalized reports. Compare to building individual dashboards per customer in legacy BI tools—this pattern alone can save **hundreds of hours**.

### Example 3: Conditional Display with If/Else Logic

Create context-aware reports that adapt to data conditions:

```markdown
# Operational Health Report

```sql system_status
SELECT 
    service_name,
    status,
    error_rate,
    last_deployed
FROM infrastructure_health
ORDER BY error_rate DESC

{#if system_status[0].error_rate > 0.05}

⚠️ CRITICAL ALERT: {system_status[0].service_name} showing elevated errors!

{:else}

✅ All Systems Operational

Current error rate: {(system_status[0].error_rate * 100).toFixed(2)}% — well within acceptable thresholds.

{/if}

Full Service Breakdown

```

The {#if} block evaluates at build time, showing urgent alerts only when data conditions warrant. This transforms static reports into intelligent, self-adjusting dashboards that surface what matters and suppress noise automatically.

Example 4: Looping Through Query Results

Generate repetitive sections without copy-paste maintenance:

# Regional Performance Overview

```sql regions
SELECT DISTINCT region_name, region_code
FROM sales_territories
ORDER BY region_name

{#each regions as region}

{region.region_name}

SELECT 
    product_line,
    SUM(sales) as total_sales,
    AVG(satisfaction_score) as avg_satisfaction
FROM regional_sales
WHERE region = '${region.region_code}'
GROUP BY 1

Customer satisfaction: {region_{region.region_code}[0].avg_satisfaction.toFixed(1)}/5.0

{/each}


This pattern generates complete analytical sections per region automatically. Add a new region to your database? The report expands instantly. No manual updates. No missed territories. **Pure programmatic scalability.**

## Advanced Usage & Best Practices

Master Evidence faster with these pro strategies:

**Version Control Everything**
Treat your Evidence project like production code. Branch for new reports, pull request for review, and deploy via CI/CD. The `.evidence` directory caches query results for fast development; add it to `.gitignore` while committing all source files.

**Optimize Query Performance**
Evidence executes queries at build time, not on user request. For large datasets, materialize aggregations in your warehouse rather than computing in Evidence. Use incremental models in dbt, then query the pre-computed tables. This keeps builds fast and costs predictable.

**Component Composition**
Build reusable component libraries for your organization. Create a `components/` directory with custom Svelte components wrapping your brand's chart styles, standard metric definitions, or common layout patterns. Import and use across reports for consistency.

**Environment-Based Configuration**
Use different `evidence.config.yaml` files or environment-specific overrides. Development connects to your local Postgres; production connects to the read replica. Never commit credentials—always use environment variable substitution.

**Scheduled Builds with GitHub Actions**
```yaml
# .github/workflows/build-evidence.yml
name: Build Evidence Reports
on:
  schedule:
    - cron: '0 6 * * *'  # Daily at 6 AM
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run build
      - run: npm run deploy  # Your deploy script

Evidence vs. The Competition

Feature	Evidence	Tableau	Looker	Metabase	Streamlit
Code-First Workflow	✅ Native SQL + Markdown	❌ Drag-and-drop	⚠️ Proprietary LookML	⚠️ Limited	✅ Python
Version Control	✅ Full git integration	❌ Binary files	⚠️ Partial	❌ No	✅ Yes
Deployment Flexibility	✅ Any static host	❌ Vendor-locked	❌ Google Cloud	⚠️ Self-hosted only	⚠️ Limited
Templated Pages	✅ Built-in	❌ Manual copy	⚠️ Complex	❌ No	⚠️ Custom code
Cost Model	✅ Free, open-source	💰 $$$ Per-user licensing	💰 $$$ Enterprise	⚠️ Free tier limits	⚠️ Cloud pricing
Learning Curve	✅ Markdown + SQL	❌ Steep	❌ LookML complexity	⚠️ Moderate	⚠️ Python required
Custom Visualizations	✅ Svelte components	⚠️ Limited extensions	⚠️ Complex	❌ No	✅ Full Python
Performance at Scale	✅ Static, CDN-cached	⚠️ Server-dependent	⚠️ Query-based	⚠️ Self-hosted limits	⚠️ Server-computed

Evidence's unique position: the only tool combining true code-first BI with markdown simplicity and static site performance. No proprietary languages to learn. No vendor lock-in. No per-user pricing surprises.

Frequently Asked Questions

Is Evidence free for commercial use? Absolutely. Evidence is MIT-licensed open source. Use it personally, internally, or in commercial products without licensing fees. The GitHub repository contains everything you need.

What databases does Evidence support? Evidence connects to PostgreSQL, MySQL, BigQuery, Snowflake, DuckDB, SQLite, and more. The connector architecture expands regularly—check docs.evidence.dev for the current list.

Can non-technical team members edit reports? Evidence targets technical users comfortable with SQL. However, Evidence Studio introduces AI-assisted workflows that lower the barrier. For fully non-technical users, traditional BI tools may still fit better.

How does Evidence handle data security? Queries execute at build time, not on end-user devices. Sensitive data never reaches browsers unless explicitly queried. Self-host deployments keep all data within your infrastructure. Use environment variables for credential management.

What's the difference between Evidence and dbt? They complement perfectly! dbt transforms data in your warehouse; Evidence visualizes and presents it. Many teams use dbt for data modeling and Evidence for the presentation layer—modern analytics engineering stack.

Can I use Evidence with my existing CI/CD pipeline? Yes—Evidence's static output integrates seamlessly. Build in GitHub Actions, GitLab CI, or any automation platform. Deploy artifacts to Netlify, Vercel, S3, or internal servers. It's just another code project.

How do I get help if I'm stuck? Join the active Evidence Slack community for real-time support. Browse examples for inspiration. Open GitHub issues for bugs or feature requests.

Conclusion: The Future of BI Is Code

Evidence represents more than a tool—it's a philosophical shift in how we think about business intelligence. The era of proprietary, click-based, vendor-locked analytics is ending. The future belongs to code: auditable, version-controlled, collaboratively developed, and infinitely flexible.

If you're tired of fighting your BI tool, of maintaining logic in inaccessible graphical interfaces, of paying per-user fees for static reports—Evidence offers genuine liberation. Write SQL you already know. Format with markdown you already use. Deploy with git workflows you already have. The learning investment is minimal; the productivity returns are transformational.

The data engineering community has spoken with their stars, their contributions, and their migration away from legacy platforms. Business intelligence as code isn't coming—it's here, it's proven, and it's waiting for you.

Ready to stop clicking and start coding? Clone the Evidence repository, spin up your first project, and experience what BI should have been all along. Your future self—reviewing git diffs instead of chasing dashboard versions—will thank you.

The revolution won't be drag-and-dropped. It will be committed, pushed, and deployed. Join it today.