Document faces/ directory convention and dbt project setup
Problem
The documentation inconsistently used dashboards/ as the directory for dashboard YAML files, but the actual convention across the CLI, all examples, and the playground is faces/. This caused confusion for users following the docs. Additionally, there was no clear guide for adding Dataface to an existing dbt project.
Context
- The CLI defaults to
faces/(dft validate faces/,dft serve faces/) - All 51+ example files across
examples/playground/faces/,examples/tutorial_dbt/faces/,examples/pied_piper_dbt/faces/,examples/dundersign_dbt/faces/usefaces/ - The Cloud app uses
dashboards/internally (Cloud-specific mapping for its Django models), but external users interact withfaces/ - Docs that referenced
dashboards/: getting-started.md, installation.md, cli-reference.md, best-practices.md, imports.md, queries.md, yaml-style-guide.md, charts/index.md
Plan
- Replace all
dashboards/references in docs withfaces/ - Add "Adding Dataface to an Existing dbt Project" section to installation.md
- Document
faces/conventions: partials infaces/partials/_*.yml, subdirectories map to URL paths
Implementation Progress
Completed. All changes made in a single pass:
Files modified (dashboards/ → faces/):
- docs/docs/guides/getting-started.md — project structure, file paths, CLI commands
- docs/docs/guides/installation.md — directory creation, test file, verification steps
- docs/docs/guides/cli-reference.md — 47 occurrences across all command examples
- docs/docs/guides/best-practices.md — project organization, CLI examples
- docs/docs/guides/yaml-style-guide.md — validation examples
- docs/docs/boards/imports.md — directory structure diagrams
- docs/docs/queries.md — validation/compile examples
- docs/docs/charts/index.md — serve/validate examples
New content added:
- docs/docs/guides/installation.md — "Adding Dataface to an Existing dbt Project" section with:
- 4-step quickstart (install, mkdir faces, create hello.yml, serve)
- Complete project structure diagram showing faces/, partials/, assets/
- Key conventions documentation (faces/ canonical, partials with _ prefix, subdirectories)
- Explanation that Dataface auto-discovers dbt_project.yml
Review Feedback
- [x] Review cleared