dbdocs 0.0.1__tar.gz → 1.0.1__tar.gz

dbdocs-1.0.1/.gitignore

@@ -0,0 +1,168 @@
+# custom
+/target
+/samples/local
+CHANGELOG.md
+/dbt_packages
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+/site-docs
+/demo-site
+# Generated dbdocs demo, bundled into the docs site at /demo/ at build time.
+/docs/demo
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Ruff
+.ruff_cache/
+
+# Local Claude settings + personal agent memory
+.claude/settings.local.json
+.claude/agent-memory-local/
+
+# Frontend (React Flow graph bundle) — Node.js toolchain artifacts
+node_modules/
+frontend/node_modules/
+frontend/dist/
+frontend/.vite/
+frontend/coverage/
+frontend/*.tsbuildinfo
+.eslintcache
+
+# npm / yarn / pnpm logs & debug output
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# The BUILT graph bundle IS committed (shipped in the wheel) — do not ignore it.
+!dbdocs/site/bundle/assets/graph/
+!dbdocs/site/bundle/assets/graph/**
+
+# dbdocs DEBUG file log
+logs/

{dbdocs-0.0.1 → dbdocs-1.0.1}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Dat Nguyen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Dat Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dbdocs-1.0.1/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: dbdocs
+Version: 1.0.1
+Summary: Alternative dbt docs site: Catalog + ERD + column-level lineage
+Project-URL: Homepage, https://github.com/datnguye/dbt-docs
+Project-URL: Repository, https://github.com/datnguye/dbt-docs
+Author-email: Dat Nguyen <datnguyen.it09@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: dbt,dbterd,documentation,erd,lineage,sqlglot
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: dbterd>=1.26
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sqlglot>=25
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/logo.svg" alt="dbdocs logo" width="220" height="88">
+</p>
+
+<p align="center"><b>An alternative dbt docs site — catalog + ERD + column-level lineage, baked into one file.</b></p>
+
+<p align="center">
+  <a href="https://dbdocs.datnguye.me/latest/demo/"><img src="https://img.shields.io/badge/live-demo-FF694A?style=flat&logo=rocket&logoColor=white" alt="live demo"></a>
+  <a href="https://dbdocs.datnguye.me/"><img src="https://img.shields.io/badge/docs-visit%20site-blue?style=flat&logo=gitbook&logoColor=white" alt="docs"></a>
+  <a href="https://pypi.org/project/dbdocs/"><img src="https://badge.fury.io/py/dbdocs.svg" alt="PyPI version"></a>
+  <img src="https://img.shields.io/badge/CLI-Python-FFCE3E?labelColor=14354C&logo=python&logoColor=white" alt="python-cli">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org"><img src="https://img.shields.io/badge/Python-3.10|3.11|3.12|3.13-3776AB.svg?style=flat&logo=python&logoColor=white" alt="python"></a>
+</p>
+
+Turn your dbt artifacts into a single self-contained `index.html`: a browsable catalog, an interactive lineage DAG and ERD, and **column-level lineage** from your compiled SQL. No server, no database, no build step — just a file you can open or host anywhere.
+
+| Catalog | Model page | Lineage DAG |
+|---|---|---|
+| ![catalog](docs/assets/img/demo-catalog.png) | ![model page](docs/assets/img/demo-model-page.png) | ![dag](docs/assets/img/demo-model-dag.png) |
+
+## Install
+
+```bash
+pip install dbdocs --upgrade
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```bash
+dbt docs generate     # writes target/manifest.json + target/catalog.json
+dbdocs generate       # builds ./site/index.html with all data baked in
+dbdocs serve          # static http server on http://127.0.0.1:8000
+```
+
+Full walkthrough, configuration, and architecture live in the **[documentation](https://dbdocs.datnguye.me/)**.
+
+## Why dbdocs?
+
+dbt's own docs are great until you want lineage at the *column* level — that's the gap this fills. Everything is derived from your dbt `manifest.json` / `catalog.json` and baked into one offline-friendly SPA: catalog navigation grouped by database/schema, per-model SQL and columns, interactive React Flow graphs, column-level lineage via sqlglot, client-side search, a dark/light theme, and versioned deploys with a built-in version switcher.
+
+See the [docs](https://dbdocs.datnguye.me/) for the deep dives.
+
+## Contributing
+
+Contributions are welcome — bugs, features, docs, typos. See the **[Contributing Guide](https://dbdocs.datnguye.me/latest/nav/development/contributing-guide.html)**.
+
+If dbdocs saves you some clicks, consider [buying me a coffee](https://www.buymeacoffee.com/datnguye).
+
+<a href="https://www.buymeacoffee.com/datnguye"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg?logo=buy-me-a-coffee&logoColor=white&labelColor=ff813f&style=for-the-badge" alt="buy me a coffee"></a>
+
+## License
+
+[MIT](./LICENSE) © Dat Nguyen

dbdocs-1.0.1/README.md

@@ -0,0 +1,56 @@
+<p align="center">
+  <img src="docs/assets/logo.svg" alt="dbdocs logo" width="220" height="88">
+</p>
+
+<p align="center"><b>An alternative dbt docs site — catalog + ERD + column-level lineage, baked into one file.</b></p>
+
+<p align="center">
+  <a href="https://dbdocs.datnguye.me/latest/demo/"><img src="https://img.shields.io/badge/live-demo-FF694A?style=flat&logo=rocket&logoColor=white" alt="live demo"></a>
+  <a href="https://dbdocs.datnguye.me/"><img src="https://img.shields.io/badge/docs-visit%20site-blue?style=flat&logo=gitbook&logoColor=white" alt="docs"></a>
+  <a href="https://pypi.org/project/dbdocs/"><img src="https://badge.fury.io/py/dbdocs.svg" alt="PyPI version"></a>
+  <img src="https://img.shields.io/badge/CLI-Python-FFCE3E?labelColor=14354C&logo=python&logoColor=white" alt="python-cli">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org"><img src="https://img.shields.io/badge/Python-3.10|3.11|3.12|3.13-3776AB.svg?style=flat&logo=python&logoColor=white" alt="python"></a>
+</p>
+
+Turn your dbt artifacts into a single self-contained `index.html`: a browsable catalog, an interactive lineage DAG and ERD, and **column-level lineage** from your compiled SQL. No server, no database, no build step — just a file you can open or host anywhere.
+
+| Catalog | Model page | Lineage DAG |
+|---|---|---|
+| ![catalog](docs/assets/img/demo-catalog.png) | ![model page](docs/assets/img/demo-model-page.png) | ![dag](docs/assets/img/demo-model-dag.png) |
+
+## Install
+
+```bash
+pip install dbdocs --upgrade
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```bash
+dbt docs generate     # writes target/manifest.json + target/catalog.json
+dbdocs generate       # builds ./site/index.html with all data baked in
+dbdocs serve          # static http server on http://127.0.0.1:8000
+```
+
+Full walkthrough, configuration, and architecture live in the **[documentation](https://dbdocs.datnguye.me/)**.
+
+## Why dbdocs?
+
+dbt's own docs are great until you want lineage at the *column* level — that's the gap this fills. Everything is derived from your dbt `manifest.json` / `catalog.json` and baked into one offline-friendly SPA: catalog navigation grouped by database/schema, per-model SQL and columns, interactive React Flow graphs, column-level lineage via sqlglot, client-side search, a dark/light theme, and versioned deploys with a built-in version switcher.
+
+See the [docs](https://dbdocs.datnguye.me/) for the deep dives.
+
+## Contributing
+
+Contributions are welcome — bugs, features, docs, typos. See the **[Contributing Guide](https://dbdocs.datnguye.me/latest/nav/development/contributing-guide.html)**.
+
+If dbdocs saves you some clicks, consider [buying me a coffee](https://www.buymeacoffee.com/datnguye).
+
+<a href="https://www.buymeacoffee.com/datnguye"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg?logo=buy-me-a-coffee&logoColor=white&labelColor=ff813f&style=for-the-badge" alt="buy me a coffee"></a>
+
+## License
+
+[MIT](./LICENSE) © Dat Nguyen

{dbdocs-0.0.1 → dbdocs-1.0.1}/dbdocs/__main__.py

@@ -1,3 +1,3 @@
-from dbdocs import main
-
-main.main()
+from dbdocs import main
+
+main.main()

dbdocs-1.0.1/dbdocs/cli/main.py

@@ -0,0 +1,86 @@
+import functools
+import importlib.metadata
+import socketserver
+from http.server import SimpleHTTPRequestHandler
+
+import click
+
+from dbdocs.core.config import DbDocsConfig
+from dbdocs.core.exceptions import DbDocsError
+from dbdocs.core.log import logger
+from dbdocs.site import deploy as deploy_module
+from dbdocs.site.builder import ReportBuilder
+
+__version__ = importlib.metadata.version("dbdocs")
+
+
+# dbdocs
+@click.group(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    invoke_without_command=True,
+    no_args_is_help=True,
+    epilog="Specify one of these sub-commands and you can find more help from there.",
+)
+@click.version_option(__version__)
+@click.option("-c", "--config", "config_path", default=None, help="Path to dbdocs.yml.")
+@click.pass_context
+def dbdocs(ctx, config_path):
+    """Alternative dbt docs site: dbt docs + ERD + column-level lineage."""
+    logger.info("Run with dbdocs==%s", __version__)
+    try:
+        ctx.obj = DbDocsConfig.load(config_path)
+    except DbDocsError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@dbdocs.command(name="generate")
+@click.option("-o", "--output-dir", default=None, help="Where to write the site (default: config).")
+@click.option(
+    "--dialect", default=None, help="SQL dialect for column lineage (default: adapter_type)."
+)
+@click.pass_obj
+def generate(config: DbDocsConfig, output_dir, dialect):
+    """Build the self-contained site from dbt artifacts."""
+    if dialect is not None:
+        config.dialect = dialect
+    try:
+        out = ReportBuilder(config).generate(output_dir=output_dir)
+    except DbDocsError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(f"Generated site into {out}")
+
+
+@dbdocs.command(name="serve")
+@click.option("-p", "--port", default=8000, show_default=True, help="Port to serve on.")
+@click.pass_obj
+def serve(config: DbDocsConfig, port):
+    """Serve the generated site locally (static http server)."""
+    handler = functools.partial(SimpleHTTPRequestHandler, directory=config.output_path)
+    click.echo(f"Serving {config.output_path} at http://127.0.0.1:{port} (Ctrl-C to stop)")
+    socketserver.ThreadingTCPServer.allow_reuse_address = True
+    with socketserver.ThreadingTCPServer(("127.0.0.1", port), handler) as httpd:
+        httpd.serve_forever()
+
+
+@dbdocs.command(name="deploy")
+@click.option("--version", "version", required=True, help="Version label to deploy (e.g. 1.2).")
+@click.option("--alias", default=None, help="Moving alias for this version (e.g. latest).")
+@click.option(
+    "--title", default=None, help="Display title for this version (default: the version)."
+)
+@click.option(
+    "--delete", "delete", is_flag=True, default=False, help="Delete this version instead."
+)
+@click.option("--push/--no-push", default=False, help="Publish to the gh-pages branch.")
+@click.pass_obj
+def deploy(config: DbDocsConfig, version, alias, title, delete, push):
+    """Generate a versioned build and update the version index (or --delete one)."""
+    try:
+        if delete:
+            deploy_module.delete(config, version=version, push=push)
+            click.echo(f"Deleted version {version}")
+            return
+        out = deploy_module.deploy(config, version=version, alias=alias, push=push, title=title)
+    except DbDocsError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(f"Deployed version {version} into {out}")

dbdocs-1.0.1/dbdocs/core/artifacts.py

@@ -0,0 +1,82 @@
+"""Loading dbt artifacts (manifest/catalog) via the dbterd parser.
+
+dbterd parses ``manifest.json`` / ``catalog.json`` into ``dbt_artifacts_parser``
+Pydantic models. Two cross-cutting gotchas live here so the rest of dbdocs never
+has to think about them:
+
+* **Schema field aliasing.** ``dbt_artifacts_parser`` aliases the ``schema``
+  field to ``schema_`` to avoid clobbering Pydantic's ``BaseModel.schema()`` —
+  so ``node.schema`` is a *bound method*, not the value. Always read
+  ``node.schema_``; :func:`db_schema` centralizes that.
+* **Schema-version relaxation.** Passing the detected schema version to
+  ``read_manifest``/``read_catalog`` makes dbterd apply its relaxation policies,
+  keeping parsing robust across dbt versions (including dbt Core 2.0).
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from dbterd.helpers import file
+
+#: Bucket label used when a node/source has no database or schema set.
+UNKNOWN = "_unknown"
+
+#: unique_id prefixes surfaced as catalog nodes (tests/macros/etc. excluded).
+NODE_PREFIXES = ("model.", "seed.", "snapshot.")
+
+
+def artifact_version(target_path: str, artifact: str) -> "int | None":
+    """Resolve a dbt artifact's schema version int from its ``dbt_schema_version``.
+
+    Returns ``None`` (auto-detect, strict) if the version can't be determined —
+    e.g. the file is missing or not valid JSON.
+    """
+    artifact_path = Path(target_path) / f"{artifact}.json"
+    try:
+        metadata = json.loads(artifact_path.read_text(encoding="utf-8")).get("metadata", {})
+    except (OSError, json.JSONDecodeError):
+        return None
+    extracted = file.extract_artifact_version_from_file(metadata.get("dbt_schema_version", ""))
+    return int(extracted) if extracted else None
+
+
+def load_artifacts(target_path: str) -> "tuple[Any, Any]":
+    """Return the dbterd-parsed ``(manifest, catalog)`` for a dbt target dir."""
+    manifest = file.read_manifest(
+        path=target_path, version=artifact_version(target_path, "manifest")
+    )
+    catalog = file.read_catalog(path=target_path, version=artifact_version(target_path, "catalog"))
+    return manifest, catalog
+
+
+def adapter_type(target_path: str) -> "str | None":
+    """The warehouse adapter (``snowflake``/``bigquery``/…) from manifest metadata.
+
+    Read from the raw JSON rather than the parsed model so it works regardless of
+    how the parser exposes ``metadata``. Used as the default sqlglot dialect for
+    column-level lineage. ``None`` if unreadable.
+    """
+    manifest_path = Path(target_path) / "manifest.json"
+    try:
+        metadata = json.loads(manifest_path.read_text(encoding="utf-8")).get("metadata", {})
+    except (OSError, json.JSONDecodeError):
+        return None
+    return metadata.get("adapter_type")
+
+
+def db_schema(entity: Any) -> "tuple[str, str]":
+    """The ``(database, schema)`` an entity lands in, with safe fallbacks.
+
+    Reads ``schema_`` (the Pydantic alias — ``schema`` is a bound method) and
+    falls back to :data:`UNKNOWN` when either part is missing, so grouping never
+    produces a ``None`` bucket.
+    """
+    database = getattr(entity, "database", None) or UNKNOWN
+    schema = getattr(entity, "schema_", None) or UNKNOWN
+    return str(database), str(schema)
+
+
+def node_name(unique_id: str) -> str:
+    """The dbt node's short name — the last dotted segment of its unique_id."""
+    return unique_id.split(".")[-1]

dbdocs-1.0.1/dbdocs/core/config.py

@@ -0,0 +1,136 @@
+from dataclasses import asdict, dataclass, field, fields
+from pathlib import Path
+
+import yaml
+
+from dbdocs.core.exceptions import DbDocsConfigError
+
+DEFAULT_CONFIG_FILENAME = "dbdocs.yml"
+
+
+def _resolve_within_cwd(value: str, field_name: str) -> Path:
+    """Resolve *value* against cwd; reject a relative path that escapes the cwd.
+
+    An absolute *value* is resolved as-is (the caller's deliberate choice — this
+    is documented behaviour and must not be rejected).  A relative *value* is
+    resolved against ``Path.cwd()`` and then checked: if the result is not
+    inside (or equal to) the cwd, ``DbDocsConfigError`` is raised.
+    """
+    base = Path.cwd().resolve()
+    candidate = Path(value)
+    resolved = candidate if candidate.is_absolute() else (base / candidate)
+    resolved = resolved.resolve()
+    if not candidate.is_absolute() and resolved != base and base not in resolved.parents:
+        raise DbDocsConfigError(f"{field_name} {value!r} escapes the project directory ({base}).")
+    return resolved
+
+
+@dataclass
+class DbDocsConfig:
+    """Site configuration for a dbdocs build.
+
+    Loaded from a ``dbdocs.yml`` in the working directory; every field has a
+    default so the file is optional. ``version`` is intentionally absent — it is
+    a ``deploy`` CLI argument, not site config.
+
+    ``target_dir`` is where the dbt artifacts are read from; ``output_dir`` is
+    where the generated self-contained site is written.
+    """
+
+    site_name: str = "dbt docs"
+    site_url: str = "https://github.com/datnguye/dbt-docs"
+    site_author: str = "Dat Nguyen"
+    site_description: str = "Alternative dbt documentation site"
+    repo_name: str = "datnguye/dbt-docs"
+    repo_url: str = "https://github.com/datnguye/dbt-docs"
+    project_name: str = "dbt docs"
+    #: The footer's Buy-me-a-coffee badge shows by default; set false to hide it.
+    show_buy_me_a_coffee: bool = True
+    #: Project README rendered on the overview (relative to the working dir). Set
+    #: empty to omit the README section. Missing file ⇒ section simply absent.
+    readme: str = "README.md"
+    target_dir: str = "target"
+    #: Where the generated site is written. Nested under the dbt ``target/`` by
+    #: default so docs sit alongside the artifacts they're built from.
+    output_dir: str = "target/site"
+    #: SQL dialect for column-lineage parsing; ``None`` ⇒ derive from the
+    #: artifact's ``adapter_type`` (e.g. snowflake, bigquery, postgres).
+    dialect: "str | None" = None
+    #: Alias the SPA's version switcher treats as the default landing version.
+    default_version: str = "latest"
+    #: dbterd ERD options (``algo``, ``entity_name_format``, ``select``,
+    #: ``resource_type``, …) passed straight to ``DbtErd``. Configured here so the
+    #: ERD shape lives in ``dbdocs.yml`` rather than a separate ``.dbterd.yml``.
+    dbterd: dict = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, path: "str | Path | None" = None) -> "DbDocsConfig":
+        """Load config from ``path`` (or ``./dbdocs.yml``); all-defaults if absent."""
+        config_path = Path(path) if path is not None else Path.cwd() / DEFAULT_CONFIG_FILENAME
+        if not config_path.is_file():
+            return cls()
+
+        try:
+            raw = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+        except yaml.YAMLError as exc:
+            raise DbDocsConfigError(f"Could not parse {config_path}: {exc}") from exc
+
+        if raw is None:
+            return cls()
+        if not isinstance(raw, dict):
+            raise DbDocsConfigError(
+                f"{config_path} must contain a mapping, got {type(raw).__name__}"
+            )
+
+        known = {f.name for f in fields(cls)}
+        unknown = set(raw) - known
+        if unknown:
+            raise DbDocsConfigError(
+                f"Unknown keys in {config_path}: {', '.join(sorted(unknown))}. "
+                f"Allowed keys: {', '.join(sorted(known))}."
+            )
+        return cls(**raw)
+
+    #: Build-control fields that are not part of the site's display metadata.
+    _NON_METADATA_FIELDS = (
+        "target_dir",
+        "output_dir",
+        "dialect",
+        "default_version",
+        "dbterd",
+        "readme",
+    )
+
+    def render_context(self) -> dict:
+        """The site display metadata injected into the SPA's ``metadata`` block.
+
+        Excludes build-control fields (where artifacts are read, where the site
+        is written, the lineage dialect override) that aren't site metadata.
+        """
+        context = asdict(self)
+        for field_name in self._NON_METADATA_FIELDS:
+            context.pop(field_name, None)
+        return context
+
+    @property
+    def target_path(self) -> str:
+        """Absolute path to the dbt target/ dir where the artifacts live.
+
+        A relative ``target_dir`` is resolved against the current working
+        directory **at access time** — this is intentional and must stay aligned
+        with dbterd's ``DbtErd``, which also reads artifacts from ``./target``
+        relative to the cwd. An absolute ``target_dir`` is returned unchanged.
+        A relative path that would escape the cwd raises ``DbDocsConfigError``.
+        """
+        return str(_resolve_within_cwd(self.target_dir, "target_dir"))
+
+    @property
+    def output_path(self) -> str:
+        """Absolute path to the dir the generated site is written into.
+
+        Resolved against the cwd at access time, mirroring ``target_path`` — a
+        relative ``output_dir`` follows the working directory, an absolute one is
+        returned unchanged.
+        A relative path that would escape the cwd raises ``DbDocsConfigError``.
+        """
+        return str(_resolve_within_cwd(self.output_dir, "output_dir"))