Composants

DocAnvil propose des composants intégrés rendus via des directives délimitées. Ils sont traités avant le rendu Markdown, donc vous pouvez utiliser du Markdown à l'intérieur.

Syntaxe des directives

Les composants utilisent une syntaxe de bloc délimité avec des triples deux-points :

<div class="nom">
<p>Le contenu va ici. <strong>Markdown</strong> est pris en charge.</p>
</div>

La clôture ouvrante est ::: suivi du nom du composant et des attributs optionnels entre accolades. La clôture fermante est ::: seul sur sa ligne.

Attributs

Les attributs sont spécifiés à l'intérieur de {...} après le nom du composant :

Plusieurs attributs peuvent être combinés : :::note{title="Important" .classe-perso #ma-note}

Note

Affiche des blocs d'information avec un thème bleu/indigo.

Syntaxe brute :

<div class="admonition note">
<p class="admonition-title">Titre personnalisé</p>
<p>Votre contenu ici. Prend en charge le <strong>Markdown</strong>.</p>
</div>

Warning

Affiche des messages d'avertissement avec un thème orange.

Syntaxe brute :

<div class="admonition warning">
<p class="admonition-title">Zone de danger</p>
<p>Votre contenu d'avertissement ici.</p>
</div>

Lozenge

Affiche un statut visuel rapide avec un lozenge.

La syntaxe est la suivante : :::lozenge{type="default",text="Défaut"}

Onglets

Regroupez du contenu en onglets commutables. Chaque onglet est défini avec une directive :::tab imbriquée. L'extérieur ::::tabs utilise quatre deux-points pour que les clôtures internes :::tab (trois deux-points) ne ferment pas prématurément le conteneur :

console.log("Bonjour !");

print("Bonjour !")

fn main() {
    println!("Bonjour !");
}

Syntaxe brute :

<div class="tabs">
<div class="tab-headers">
  <button class="tab-header active" data-tab="0">JavaScript</button>
  <button class="tab-header" data-tab="1">Python</button>
</div>
<div class="tab-content active" data-tab="0">
<p>Contenu pour l'onglet JavaScript.</p>
</div>
<div class="tab-content" data-tab="1">
<p>Contenu pour l'onglet Python.</p>
</div>
</div>

Si aucun title n'est fourni, les onglets sont étiquetés "Tab 1", "Tab 2", etc.

Groupe de code

Un composant d'onglets spécialisé pour comparer des blocs de code entre langages. Chaque bloc de code délimité devient un onglet, avec le nom du langage comme libellé d'onglet :

fn saluer(nom: &str) {
    println!("Bonjour, {nom} !");
}

def saluer(nom):
    print(f"Bonjour, {nom} !")

function saluer(nom) {
  console.log(`Bonjour, ${nom} !`);
}

Syntaxe brute :

<div class="code-group">
<div class="tab-headers">
  <button class="tab-header active" data-tab="0">rust</button>
  <button class="tab-header" data-tab="1">python</button>
</div>
<div class="tab-content active" data-tab="0"><pre><code class="language-rust">fn saluer(nom: &amp;str) {
    println!("Bonjour, {nom} !");
}</code></pre></div>
<div class="tab-content" data-tab="1"><pre><code class="language-python">def saluer(nom):
    print(f"Bonjour, {nom} !")</code></pre></div>
</div>

Diagrammes Mermaid

Rendez des diagrammes et graphiques avec Mermaid.js. Le contenu à l'intérieur d'un bloc :::mermaid est passé directement à Mermaid — il n'est pas traité comme Markdown.

graph TD
    A[Écrire du Markdown] --> B[Lancer docanvil build]
    B --> C[Site HTML statique]
    C --> D[Déployer partout]

Syntaxe brute :

<pre class="mermaid">graph TD
    A[Écrire du Markdown] --> B[Lancer docanvil build]
    B --> C[Site HTML statique]
    C --> D[Déployer partout]</pre>

Mermaid prend en charge de nombreux types de diagrammes incluant les organigrammes, les diagrammes de séquence, les diagrammes de classes, les diagrammes d'état, les diagrammes de Gantt, et plus encore. Consultez la documentation Mermaid pour la référence complète de la syntaxe.

Composants personnalisés

{#custom-components} Les composants intégrés couvrent les cas courants, mais parfois vous voulez les vôtres. Déposez un template Tera dans theme/components/<nom>.html et utilisez-le avec :::nom{...} — la même syntaxe de directive que pour n'importe quel composant intégré.

Votre premier composant

Créez theme/components/card.html :

<div class="card">
  {% if attrs.title %}<h3>{{ attrs.title }}</h3>{% endif %}
  {{ body | safe }}
</div>

Puis utilisez-le dans votre contenu :

<div class="card" data-title="Quick start">
<p>Install DocAnvil and run <code>docanvil new my-docs</code>.</p>
</div>

Stylez-le dans votre CSS personnalisé (.card { ... }) et vous avez un bloc réutilisable sans aucun copier-coller.

Variables du template

Chaque template de composant a accès à :

Les composants intégrés qui ont besoin de données structurées passent des variables supplémentaires — tabs (une liste de {title, body}) pour le composant tabs, et blocks (une liste de {lang, code}) pour code-group. Vous les verrez si vous éjectez l'un ou l'autre.

Échappement

DocAnvil échappe automatiquement la sortie des templates, comme pour toute chaîne non fiable : &, <, >, ", et ' sont échappés. body est du HTML déjà rendu, donc affichez-le avec | safe — exactement comme {{ content | safe }} dans layout.html. attrs et body_raw sont du texte brut et doivent généralement être affichés sans | safe.

Attributs optionnels

Si un template référence un attribut qui n'a pas été passé (et sans valeur de repli), la page affiche un encadré d'erreur à sa place et la compilation émet un avertissement — ce qui échoue sous --strict. Donnez une valeur par défaut à chaque attribut optionnel :

{{ attrs.title | default(value="Note") }}

ou protégez-le avec un {% if %} :

{% if attrs.title %}<h3>{{ attrs.title }}</h3>{% endif %}

Imbrication

Les composants s'imbriquent les uns dans les autres, pas seulement les onglets dans les onglets. Utilisez plus de deux-points sur la clôture extérieure pour que sa fermeture ::: ne soit pas prise pour une fermeture intérieure :

<div class="card" data-title="Heads up">
<p>:::note
Nested components render just like top-level ones.
:::</p>
<p>Inline too: :::lozenge{type="warning" text="Beta"}</p>
</div>

Composants inline

Le même template rend aussi bien l'usage en bloc qu'en ligne — :::nom{attributs} sans corps ni clôture fermante. Dans le template, inline est true et body est vide, donc vérifiez attrs plutôt que body pour savoir quoi afficher. Le composant intégré lozenge.html en est un bon exemple : il n'utilise que attrs.

Gardez un composant inline à l'intérieur d'une ligne de texte, comme Statut : :::lozenge{text="Done"}. Un composant écrit seul sur sa propre ligne est interprété comme le début d'un bloc, et la recherche descendra jusqu'à la prochaine ::: nue pour trouver une clôture — avalant tout ce qui se trouve entre les deux.

Restyler les composants intégrés

Vous voulez changer l'apparence ou le comportement d'un composant intégré ? Éjectez son template et modifiez-le :

docanvil component eject note

Cela copie le template intégré vers theme/components/note.html. Un template utilisateur portant le nom d'un composant intégré prend le relais du rendu de ce composant tout en conservant ses données — modifier theme/components/tabs.html continue de recevoir la liste tabs, et theme/components/code-group.html continue de recevoir blocks.

Si vous restylez tabs ou code-group, conservez les classes et attributs tab-header / tab-content / data-tab / active — docanvil.js s'en sert pour changer d'onglet. Pour mermaid, affichez la source du diagramme avec {{ body_raw | safe }} : Mermaid lit le texte brut de l'élément, donc des entités échappées casseraient le diagramme.

Vérifier les templates

docanvil doctor vérifie chaque fichier de theme/components/ pour des erreurs de syntaxe Tera, des noms inutilisables comme directive (lettres, chiffres, _ et - uniquement), et un {{ body }} affiché sans | safe. Lancez docanvil component list à tout moment pour voir quels composants sont intégrés, lesquels sont surchargés, et lesquels sont les vôtres.

Imbrication des directives

Lors de l'imbrication de directives, utilisez plus de deux-points sur la clôture extérieure pour la distinguer des clôtures intérieures — cela fonctionne pour tout composant, intégré ou personnalisé, pas seulement les onglets. Le motif ::::tabs (quatre deux-points) et :::tab (trois deux-points) en est l'exemple le plus clair :

<div class="tabs">
<div class="tab-headers">
  <button class="tab-header active" data-tab="0">Premier</button>
  <button class="tab-header" data-tab="1">Deuxième</button>
</div>
<div class="tab-content active" data-tab="0">
<p>Contenu ici.</p>
</div>
<div class="tab-content" data-tab="1">
<p>Contenu ici.</p>
</div>
</div>

La directive extérieure utilise 4 deux-points (::::) tandis que les intérieures utilisent 3 (:::). La clôture fermante doit correspondre au nombre exact de deux-points utilisé dans la clôture ouvrante.

Directives inconnues

Si vous utilisez un nom de directive qui ne correspond à aucun composant intégré, le contenu est enveloppé dans un <div> avec le nom de la directive comme classe :

<div class="bloc-personnalise">
<p>Cela devient un <code><div class="bloc-personnalise extra"></code>.</p>
</div>

Cela vous permet de créer des blocs stylisés personnalisés avec votre propre CSS.

Résumé

Pages associées

• Markdown — mise en forme du texte, tableaux, et autres fonctionnalités Markdown
• Wiki-links — liens à doubles crochets et popovers inline