Options de personnalisation du site dbt Docs

Le site dbt docs par défaut prend en charge un ensemble limité de personnalisations. Cette note couvre les options disponibles et là où elles s’arrêtent.

Le bloc doc __overview__

Par défaut, la page d’accueil du site docs affiche un contenu générique. Il peut être remplacé par un bloc doc nommé __overview__ :

{% docs __overview__ %}
# Documentation de la plateforme de données

Bienvenue dans la documentation d'analytics engineering pour [votre entreprise].

**Liens rapides :**
- Les modèles mart se trouvent dans le répertoire `models/marts/`
- Les définitions de sources se trouvent sous `models/base/`
- Des questions ? Rejoignez-nous sur #data-team dans Slack

Dernière mise à jour : voir l'historique des exécutions du pipeline pour les informations de fraîcheur.
{% enddocs %}

Ce bloc doc peut aller dans n’importe quel fichier .md dans les chemins de ressources du projet. La page d’aperçu oriente les membres de l’équipe : où trouver les choses, qui contacter, quelles conventions suit le projet. Il prend en charge le Markdown complet — titres, liens, tableaux, blocs de code, images.

Couleurs des nœuds du DAG

Vous pouvez colorier les nœuds dans le graphe de lignage en définissant docs.node_color dans dbt_project.yml ou par modèle. Toute couleur hexadécimale ou couleur CSS nommée fonctionne :

models:
  my_project:
    base:
      +docs:
        node_color: "#a3c4bc"
    marts:
      +docs:
        node_color: "#c49a6c"

Cela aide à distinguer visuellement les couches dans le DAG. Les patterns courants :

• Colorier par couche : les modèles base dans une couleur, les intermédiaires dans une autre, les marts dans une troisième. Communique immédiatement l’étape de transformation.
• Colorier par équipe : les modèles appartenant à l’équipe finance en bleu, marketing en vert, produit en orange. Utile pour les projets avec plusieurs équipes contributrices.
• Colorier par domaine : les modèles de revenus dans une couleur, les modèles clients dans une autre. Aide les parties prenantes à trouver leur zone du graphe.

Les surcharges par modèle fonctionnent également, pour les cas où un modèle spécifique doit se démarquer :

models:
  - name: mrt__finance__revenue
    config:
      docs:
        node_color: "#ff6b6b"

Masquer des modèles de la documentation

Les modèles qui encombrerait le DAG sans apporter de valeur aux lecteurs peuvent être masqués avec docs.show: false :

models:
  - name: int__order_items_pivoted
    config:
      docs:
        show: false

Bons candidats au masquage :

• Modèles intermédiaires qui existent uniquement comme étapes de transformation et ne sont jamais interrogés directement
• Modèles utilitaires comme les tables de dates ou les tables de correspondance qui ajoutent du bruit au graphe de lignage
• Modèles de staging internes qui reflètent les sources mais n’ajoutent aucune logique métier

Les modèles masqués sont exclus à la fois de la liste des modèles et de la visualisation du DAG. Leurs connexions amont et aval sont également supprimées du graphe, donc masquer un nœud intermédiaire déconnecte effectivement son parent de ses enfants dans la représentation visuelle. Utilisez cette option délibérément.

Vous pouvez également l’appliquer au niveau du répertoire :

models:
  my_project:
    intermediate:
      +docs:
        show: false

Où s’arrêtent les options de personnalisation

C’est à peu près la limite. Le site dbt docs par défaut n’offre aucun moyen officiel de :

• Ajouter du CSS personnalisé ou de changer le thème visuel
• Changer le titre de la page depuis « dbt Docs »
• Ajouter votre logo d’entreprise ou votre image de marque
• Créer une navigation personnalisée ou des pages supplémentaires
• Ajouter du JavaScript personnalisé ou un suivi analytics
• Modifier l’algorithme de mise en page du DAG

Des issues ouvertes sur le dépôt dbt-docs ont demandé le support du marquage blanc et des thèmes depuis des années. Le seul contournement est le post-traitement du HTML généré — injection de CSS, remplacement de la balise de titre, ajout d’une image de logo. Cela se casse à chaque régénération de la documentation et nécessite une étape de build pour patcher la sortie. Pour des besoins de personnalisation plus profonds, Alternatives à dbt Docs par défaut couvre les options, du remplacement Next.js de Dagster aux plateformes de catalogues de données complètes.