How to document

Queries (/queries)

Each query should have it's own directory with both the relevant sql file and a corresponding .md file. If you have a group of queries that are all closely related, then they can all live in a single directory and share a single .md file.

Example

query_group_name
├── query_one.sql
├── query_two.sql
├── query_group_name.md

In each markdown file, it's best practice to include the text of the query itself. Instead of copying and pasting, you can dynamically insert query code by adding the following in your markdown:

```sql
--8<-- "queries/path/to/query.sql"
```

Replace the path with the correct path relative to the repo root.

All .md files in the queries/ directory will be crawled and automatically added to the documentation, so no need to add them to a .pages file or anything.

dbt (/dbt)

These should be updated in the correct .yml files that dbt uses directly. If additional .yml files are created, they will need to be added a .pages document and possibly some of the scripts powering this documentation.

How this documentation system works

This site is built with MkDocs using the Material for MkDocs theme. The docs are not written directly in the docs/ directory — instead, a build script assembles them from source files spread across the repo.

The build process

Running scripts/build_docs.sh populates the docs/ directory from two sources:

1. Query docs (queries/)

Each query group in the repo has its own directory under queries/ containing SQL files and a .md file. The build script copies all .md files from every queries/*/ subdirectory into docs/queries/.

For example, queries/call_log_count/call_log_count.md becomes docs/queries/call_log_count.md.

2. dbt docs (dbt/models/)

The script runs scripts/generate_dbt_docs.py, which reads the dbt YAML schema files (dbt/models/_sources.yml and dbt/models/_models.yml) and generates two Markdown files:

• docs/dbt/sources.md — a page for each dbt source with table and column descriptions
• docs/dbt/models.md — a page for each dbt model with column descriptions and tests

This means dbt documentation stays in sync with the YAML schema files that dbt itself uses — there's no need to maintain separate docs.

3. Static pages

Some pages live directly in docs/ and are checked into the repo (e.g. index.md and this file). These are not generated by the build script.

Building the site

# Step 1: Assemble docs from repo sources into docs/
bash scripts/build_docs.sh

# Step 2: Build the static site (output goes to site/)
mkdocs build --strict

To preview locally with live reload:

mkdocs serve