Lightdash Documentation

Welcome to the Lightdash documentation repository! This repo contains all documentation for Lightdash, built with Mintlify.

🚀 Quick Start

Prerequisites

• Node.js 18+ installed
• Familiarity with Markdown/MDX

Local Development

Install the Mintlify CLI to preview documentation changes locally:

# Install Mintlify CLI
npm i -g mintlify

# Start local development server
mintlify dev

Troubleshooting

• Mintlify dev isn't running - Run mintlify install to re-install dependencies
• Page loads as a 404 - Make sure you are running in a folder with mint.json

📁 Documentation Structure

Our documentation follows a strict folder structure where images mirror the page structure:

docs/
├── get-started/          # Onboarding and setup guides
├── guides/               # Feature guides and how-tos
├── references/           # API and feature reference docs
├── dbt-guides/           # dbt-specific guides
└── self-host/            # Self-hosting documentation

images/
├── get-started/          # ✅ Mirrors docs structure
├── guides/
├── references/
└── ...

Key Principles

1. Images belong with their pages: A page at guides/dashboard.mdx should use images from images/guides/dashboard/
2. Shared images go higher: If an image is used by multiple pages, place it in the nearest common parent folder
3. Use kebab-case: All files and folders use kebab-case (e.g., my-new-guide.mdx, not my_new_guide.mdx)

✍️ Contributing

Thank you for your interest in improving Lightdash's documentation!

Creating a New Page

1. Choose the right location:

   • get-started/: For new users setting up Lightdash
   • guides/: Step-by-step instructions for specific tasks
   • references/: Detailed feature documentation and API docs
   • dbt-guides/: dbt-specific content

2. Create the MDX file with proper frontmatter:

---
title: "Your Page Title"
description: "A brief description (under 160 characters for SEO)"
---

# Your Page Title

Introduction paragraph explaining what this page covers.

## Section 1

Content here...

3. Add to navigation in docs.json:

{
  "group": "Your Group Name",
  "pages": [
    "path/to/your-new-page"
  ]
}

Content Best Practices

Use Clear, Action-Oriented Titles

• ✅ Good: "How to create a dashboard"
• ❌ Bad: "Dashboards"

Write for Your Audience

• get-started/: Assume no prior Lightdash knowledge
• guides/: Assume basic familiarity
• references/: Technical users who need details

Structure Your Content

# Page Title (H1 - only one per page)

Brief introduction (2-3 sentences)

## What you'll learn (H2)
- Bullet point 1
- Bullet point 2

## Prerequisites (H2)
- Required setup steps
- Links to other docs

## Step-by-step guide (H2)

### Step 1: Do something (H3)
Detailed instructions...

### Step 2: Do next thing (H3)
More instructions...

## Next steps (H2)
- Link to related guides

🖼️ Image Guidelines

Adding Images

1. Create a folder matching your page:

   guides/my-new-feature.mdx
   images/guides/my-new-feature/
   

2. Use descriptive filenames:

   • ✅ Good: create-dashboard-button.png
   • ❌ Bad: screenshot1.png, image.png

3. Optimize images:

   • PNG for screenshots with text
   • JPG for photos
   • WebP for best compression (when supported)
   • Max width: 2000px
   • Compress before committing

4. Add images in MDX:

<Frame>
  <img src="/images/guides/my-feature/screenshot.png" alt="Descriptive alt text"/>
</Frame>

Image Naming Convention

• Use kebab-case: my-feature-screenshot.png
• Be descriptive: dashboard-settings-modal.png not modal.png
• Include state if relevant: button-hover-state.png

Accessibility

Always include meaningful alt text:

<img src="/images/path/file.png" alt="Dashboard settings showing the theme selector dropdown menu"/>

🔁 Using Reusable Snippets

To maintain consistency across the documentation, we use reusable snippets for common callouts and content blocks.

Available Snippets

Feature Availability Callouts

<!-- Enterprise-only features -->
<Snippet file="snippets/callouts/enterprise-only.mdx" />

<!-- Cloud-only features -->
<Snippet file="snippets/callouts/cloud-only.mdx" />

<!-- Self-hosted only features -->
<Snippet file="snippets/callouts/self-hosted-only.mdx" />

Permission & Access Callouts

<!-- Requires admin permissions -->
<Snippet file="snippets/callouts/admin-only.mdx" />

<!-- Beta features -->
<Snippet file="snippets/callouts/beta-feature.mdx" />

Common Setup Sections

<!-- dbt prerequisites (includes heading) -->
<Snippet file="snippets/setup/dbt-project-required.mdx" />

<!-- Support channels (includes heading) -->
<Snippet file="snippets/common/support-channels.mdx" />

When to Use Snippets

• ✅ Use snippets for standard callouts that appear across multiple pages
• ✅ Use snippets for repeated setup instructions or prerequisites
• ❌ Don't use snippets for page-specific content that won't be reused

Creating New Snippets

If you notice the same content repeated across 3+ pages:

1. Create a new snippet file in /snippets/ with an appropriate subdirectory
2. Use descriptive filenames: enterprise-only.mdx not callout1.mdx
3. Document the new snippet in this section
4. Update existing pages to use the snippet

🔄 Submitting Changes

1. Create a Branch

git checkout -b docs/your-feature-name

Branch naming:

• docs/new-feature-guide - New documentation
• docs/fix-typo-in-setup - Fixes
• docs/update-api-reference - Updates

2. Make Your Changes

• Edit or create MDX files
• Add images to the correct folders
• Update docs.json navigation if needed

3. Test Locally

mintlify dev

• Check all links work
• Verify images display correctly
• Review formatting

Run Validation Scripts

Before submitting your PR, run these validation scripts to catch common issues:

# Check for broken internal links and orphaned pages
node scripts/check-links.js

# Check for broken external links (optional, slower)
node scripts/check-links.js --external

# Validate that images are in the correct locations
node scripts/check-image-locations.js

What these scripts check:

• check-links.js - Validates all internal markdown and JSX links, verifies linked files exist, and identifies orphaned pages (not in docs.json)
• check-image-locations.js - Ensures images mirror page structure (e.g., guides/dashboard.mdx → images/guides/dashboard/), checks for missing images, and validates file extensions

Automated checks: These scripts run automatically on all PRs via GitHub Actions. The validation workflow will comment on your PR with any issues found (but won't block merging).

Auto-fixing Image Location Issues

If images are in the wrong location (common when using Mintlify Slack app), you can automatically fix them:

# Preview what would be changed (recommended first)
node scripts/fix-image-locations.js --dry-run

# Apply the fixes
node scripts/fix-image-locations.js

The auto-fix script will:

• Move images to the correct directory structure
• Update all MDX file references automatically
• Handle both single-use and shared images intelligently
• Create necessary directories

Using the GitHub bot: If you see image location issues in a PR comment, you can trigger the auto-fix bot:

1. Go to Actions > Fix Image Locations
2. Click "Run workflow"
3. Enter the PR number
4. The bot will automatically fix and commit the changes

Troubleshooting common issues:

• Broken links: Use absolute paths from root (/guides/my-guide not ../guides/my-guide) and omit file extensions in links
• Misplaced images: Run node scripts/fix-image-locations.js to automatically fix
• Shared images: Can be placed in the nearest common parent directory

4. Commit Your Changes

git add .
git commit -m "docs: add guide for custom metrics"

Commit message format:

• docs: add [feature] - New content
• docs: fix [issue] - Bug fixes
• docs: update [page] - Updates
• docs: remove [deprecated content] - Removals

5. Push and Create PR

git push origin docs/your-feature-name

Then create a Pull Request with:

• Clear title describing the change
• Description of what changed and why
• Screenshots if relevant
• Link to related issues

📝 Style Guide

Voice and Tone

• Friendly and approachable: Write like you're helping a colleague
• Clear and concise: Get to the point quickly
• Active voice: "Click the button" not "The button should be clicked"
• Second person: "You can create a dashboard" not "Users can create dashboards"

Formatting

Code Blocks

Use syntax highlighting:

SELECT
  user_id,
  COUNT(*) as event_count
FROM events
GROUP BY user_id

Callouts

<Note>
  Helpful tips and additional context
</Note>

<Warning>
  Important warnings about potential issues
</Warning>

<Info>
  Informational callouts
</Info>

Links

• Use descriptive link text: create a new dashboard
• Not: Click here

Lists

Use numbered lists for sequential steps:

1. First do this
2. Then do this
3. Finally do this

Use bullet points for non-sequential items:

• Feature A
• Feature B
• Feature C

Common Terms

Maintain consistency:

• Lightdash (capital L, not lightdash)
• dbt (lowercase, not DBT)
• dashboard (lowercase, not Dashboard)
• metric (not measure or KPI in docs)
• dimension (not attribute or field)

🐛 Reporting Issues

Found a problem in the docs?

1. Check if an issue already exists
2. Create a new issue with:
   • Clear title
   • Page URL
   • Description of the problem
   • Suggested fix (if you have one)

❓ Questions?

• Slack: #analytics-engineering (for team members)
• GitHub Discussions: For community questions

🚀 Publishing Changes

Changes are automatically deployed to production after pushing to the main branch via our GitHub App integration.