Capacités Markdown de dbt Docs

dbt docs effectue le rendu du Markdown standard, mais l’environnement de rendu a des capacités et des lacunes spécifiques qu’il vaut la peine de connaître avant d’investir du temps dans une documentation enrichie.

Ce qui fonctionne

Le site dbt docs prend en charge toute la gamme de la syntaxe Markdown courante :

Mise en forme inline : gras, italique, barré
Titres : tous les niveaux (# à ######)
Listes : ordonnées et non ordonnées
Tableaux : syntaxe à barres verticales (| col1 | col2 |)
Blocs de code : délimités par des triples backticks, avec coloration syntaxique
Liens : liens Markdown standards vers des URL externes
Images : syntaxe d’image Markdown standard (locale et hébergée sur le web)

Cela s’applique aussi bien aux blocs doc dans les fichiers .md qu’aux descriptions inline en YAML, bien que les descriptions YAML nécessitent une gestion correcte des scalaires (voir ci-dessous).

Styles de scalaire YAML

Lors de la rédaction de descriptions multi-lignes directement en YAML (plutôt que dans des blocs doc), le style de scalaire est important :

# Plié (>): réduit les sauts de ligne en un seul paragraphe
description: >
  Valeur vie client en USD. Calculée en utilisant une fenêtre glissante
  de 3 ans avec une méthodologie de flux de trésorerie actualisé.

# Littéral (|): préserve les sauts de ligne exactement
description: |
  Valeur vie client en USD.
  Calculée avec une fenêtre glissante de 3 ans.
  Voir la documentation sur la méthodologie LTV pour les détails.

Le scalaire plié > convient aux descriptions en prose qui doivent être rendues comme un seul paragraphe. Le scalaire littéral | convient au contenu multi-ligne où la mise en forme est importante — listes à puces, tableaux, ou contenu avec des sauts de ligne intentionnels. Pour tout ce qui dépasse une phrase ou deux, les blocs doc sont généralement plus propres que l’un ou l’autre des styles de scalaire YAML.

Intégration d’images

Les images fonctionnent via la configuration asset-paths dans dbt_project.yml :

asset-paths: ["assets"]

Puis référencer les images dans les blocs doc ou les descriptions :

![Diagramme ERD](assets/finance-erd.png)

Les images hébergées sur le web fonctionnent avec la syntaxe Markdown standard et des URL externes. Cela est utile pour les diagrammes hébergés sur Confluence, Notion, ou un drive partagé.

Pour la génération d’ERD spécifiquement, dbterd produit des diagrammes à partir des artefacts dbt aux formats Mermaid, DBML, PlantUML, GraphViz, D2 et DrawDB. Vous pouvez les rendre sous forme d’images et les intégrer dans vos blocs doc, donnant aux parties prenantes une carte visuelle de la façon dont les modèles se rapportent les uns aux autres.

Référencement croisé de modèles

Les liens entre modèles au sein du site docs utilisent des chemins d’URL internes. Le format suit le pattern #!/model/model.<nom_projet>.<nom_modèle> :

description: >
  Filtré selon les règles définies dans
  [base__stripe__payments](#!/model/model.my_project.base__stripe__payments)

Vous pouvez trouver le chemin exact en naviguant vers un modèle dans dbt docs serve et en copiant le hash d’URL. C’est la seule façon de créer des liens internes dans le site docs — la fonction ref() n’est pas disponible dans les blocs doc.

Ce qui ne fonctionne pas

Plusieurs fonctionnalités fréquemment demandées sont absentes de dbt docs :

Diagrammes Mermaid : Pas de rendu natif. C’est une demande de fonctionnalité populaire suivie dans le problème #338 du dépôt dbt-docs. Vous pouvez générer des diagrammes Mermaid en externe et les intégrer comme images.
LaTeX / notation mathématique : Pas de rendu. Si vous avez besoin de formules, décrivez-les en texte brut ou intégrez des images rendues.
Pages personnalisées : Il n’y a aucun moyen de créer des pages de documentation au-delà des vues modèle/source auto-générées et de la vue d’ensemble du projet. La page d’aperçu (peuplée via un bloc doc nommé __overview__) est la seule page de niveau supérieur personnalisable.
Performance des grands fichiers : Si vous avez des fichiers .md très volumineux (500 Ko+) contenant de nombreux blocs doc, l’analyseur Jinja de dbt peut subir des ralentissements super-linéaires pendant la compilation. Divisez les grands fichiers si vous constatez une augmentation du temps de compilation.

Comment persist_docs affecte le Markdown

Lorsque vous utilisez persist_docs pour pousser les descriptions vers votre entrepôt, la mise en forme Markdown est réduite au texte brut. Le texte développé de votre bloc doc (pas la référence Jinja {{ doc() }}) devient le commentaire de l’entrepôt, mais toute la syntaxe Markdown — titres, gras, tableaux, liens — est supprimée. Rédigez des descriptions lisibles en texte brut si vous utilisez persist_docs, car c’est ainsi que la plupart des consommateurs les verront.