Documentation site

This repository publishes a MkDocs Material site from existing Markdown plus credential-free dbt docs for each edition.

Local preview

From the repository root (Python 3.11, uv recommended):

./scripts/build_docs_site.sh
cd website
.venv/bin/mkdocs serve

Open the URL printed by mkdocs serve (default http://127.0.0.1:8000).

scripts/build_docs_site.sh stages Markdown into website/content/ (gitignored), runs dbt docs generate --empty-catalog --no-compile --static for BigQuery and Snowflake using each edition's .ci profile, then builds website/site/.

Published site (GitHub Pages)

CI workflow docs-site.yml under .github/workflows/ builds on pull requests and deploys website/site to GitHub Pages on pushes to main.

Expected URL after Pages is enabled for this repository:

https://htiwari-dev.github.io/de-starter-kits/

Enable Settings → Pages → Build and deployment → Source: GitHub Actions once in the GitHub UI if it is not already configured.

dbt docs and empty catalog

CI and the default local docs build use --empty-catalog --no-compile --static so no warehouse credentials are required. Model DAG, descriptions, and tests still come from manifest.json (embedded in the static HTML). Column-level warehouse metadata appears only after a local dbt docs generate against a real profile; copy refreshed target/ artifacts into the staged dbt-docs/ folders if you need that metadata in a private build.

Cloud Run (later)

The same static tree under website/site can be served from a container. The website/Dockerfile uses nginx:alpine and copies the built site. Future Terraform (for example under website/infra/terraform) can publish that image to Artifact Registry and Cloud Run when cloud changes are approved. No GCP apply is part of the default docs workflow.