Les blocs Callout de Quarto

Un callout (appelé admonition par Docusaurus) est une syntaxe spéciale utilisée pour mettre un paragraphe en évidence, par exemple un encadré Faites attention à... ou Astuce : saviez-vous que.... Du côté de Docusaurus, j'ai abordé cette syntaxe dans Quelques trucs et astuces pour écrire des articles Docusaurus.

Sur ce blog propulsé par Docusaurus, la syntaxe d'une admonition est

<AlertBox variant="caution" title="Pay attention to...">
Never give your bank card code to a stranger.

</AlertBox>

et le rendu est le suivant

Et maintenant une petite astuce :

Quarto implémente cela un peu différemment, voyons donc comment...

Syntaxe​

Malheureusement, cette syntaxe ne fait pas partie du langage Markdown standard : chaque outil a donc la sienne.

Pour Quarto, la syntaxe est :

:::{.callout-caution}
## Pay attention to...
Never give your bank card code to a stranger.
:::

Et ce paragraphe est converti comme ceci en PDF :

La syntaxe Quarto pour une astuce est :

:::{.callout-tip}
## Did you know that...
By going to bed earlier, you'll get better quality sleep.
:::

Les callouts sont supportés en PDF, HTML, revealJS et d'autres formats.

Retrouvez la syntaxe en détail dans la documentation officielle.

Snippet VSCode​

Si vous utilisez VSCode, ne faites pas l'effort de retenir la syntaxe exacte : utilisez la fonctionnalité Snippet de VSCode.

Appuyez sur CTRL-SHIFT-P pour accéder à la Command Palette.

Commencez à taper Configure User Snippets, validez et sélectionnez markdown.json puisque nos snippets ne doivent être disponibles que lors de l'écriture de contenu Markdown.

S'il s'agit de votre premier snippet, le fichier JSON sera vide. Copiez/collez le texte ci-dessous. Sinon, copiez simplement le nœud callout et collez-le au bon endroit dans votre fichier.

{
    "callout": {
        "prefix": "quarto-callout",?
        "body": [
            ":::{.callout-${1|note,tip,warning,caution,important|}}",?
            "## ${2:title}",?
            "${3:body}",?
            ":::"
        ],
        "description": "Add a callout paragraph to your markdown file"
    }
}

Enregistrez et fermez le fichier markdown.json, puis retournez dans n'importe quel fichier Markdown (ou créez-en un nouveau).

Maintenant, en tapant quarto puis en appuyant sur CTRL-space, VSCode affichera la liste des possibilités pour ce mot et vous y retrouverez votre snippet. Sélectionnez-le et appuyez sur Enter pour valider.

Et, comme vous pouvez le voir sur l'image ci-dessous, VSCode va vous demander trois choses :

1. D'abord le type de callout, avec une liste de valeurs possibles ; facile, non ?
2. Ensuite, après avoir appuyé sur la touche tab, il vous sera demandé de saisir un titre et, enfin,
3. Le contenu de votre paragraphe.

VSCode vous montre le snippet de façon interactive et vous pouvez ainsi le créer facilement, sans avoir à retenir la syntaxe exacte.

:::{.callout-caution}
## Pay attention to...
Never give your bank card code to a stranger.
:::