Dépannage avec Blogdown et le thème Academic

Différents moteurs de rendu

Hugo est livré avec son propre moteur de rendu, appelé Goldmark, pour le rendu des fichiers de markdown. Rstudio utilise un autre moteur, Pandoc. Pandoc a plus de fonctions, mais peut ne pas comprendre toute la syntaxe utilisée par Goldmark, ce qui est une source de problème lors de l’utilisation de blogdown pour restituer un document Rmarkdown.

Blogdown utilise Goldmark pour le rendu des fichiers .md et Pandoc pour les fichiers .Rmd.

En tant qu’utilisateur de R, il est probable que nous allons publier sur R avec des exemples, nous utiliserons donc des fichiers .Rmd. Le thème utilise des fichiers .md et toute la syntaxe de la documentation est conçue pour fonctionner pour Hugo et Goldmark. Par conséquent, lorsque vous souhaitez utiliser du code provenant de la documentation, il peut échouer lors du rendu de votre fichier .Rmd avec Pandoc.

Blogdown::shortcode()

Academic fournit un shortcode pour créer une boîte de spoiler, pour afficher le texte uniquement après avoir cliqué sur un bouton.

La documentation fournit la syntaxe suivante :

{{</* spoiler text="Click to view the spoiler" */>}}
You found me!
{{</* /spoiler */>}}

Mais au lieu d’afficher le bouton, il écrit simplement le texte suivant :

{{< spoiler text=“Click to view the spoiler” >}} You found me! {{< /spoiler >}}

Ce n’est évidemment pas ce à quoi nous nous attendions. Pour résoudre ce genre de problème, Blogdown fournit une fonction shortcode() qui permet de créer des shortcode Hugo en utilisant la syntaxe de R. La syntaxe est :

blogdown::shortcode("spoiler", text="Click to view the spoiler", .content="You found me!")

Et ça fonctionne :

Il existe différentes fonctions shortcode() et vous voudrez peut-être lire la documentation pour utiliser la plus adaptée à votre contexte :

• shortcode()
• shortcode_html()
• shortcodes()
• shortcode_open()
• shortcode_close()

htmltools::HTML()

Un autre exemple est la possibilité offerte par le thème d’utiliser des icônes et des emoji. Selon la documentation, le code suivant devrait afficher l’icône pour R avec le texte “R” :

{{</* icon name="r-project" pack="fab" */>}} R

Mais cela échoue, car Pandoc ne reconnaît pas les shortcodes :

{{< icon name=“r-project” pack=“fab” >}} R

Alors pourquoi cela arrive-t-il ? Comme Pandoc rend le signe < comme son code html < et le signe > comme >, le shortcode devient {{< icon name="r-project" pack="fab" >}} qui n’est plus interprété comme un shortcode par Hugo et est simplement affiché sous forme de texte.

Pour l’afficher correctement, nous pouvons utiliser dans un bloc de code R la fonction htmltools::HTML() qui marque le texte comme HTML et n’échappera pas les caractères spéciaux comme < ou >

htmltools::HTML('{{< icon name="r-project" pack="fab" >}} R')

Et ça fonctionne :

R

Diagramme

Academic peut afficher un diagramme avec Mermaid, mais encore une fois, la syntaxe fournie avec les fichiers .md ne fonctionnera pas avec Pandoc, comme illustré ci-dessous à partir d’un exemple de site Web :

```mermaid
stateDiagram
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]
```

Affiche

stateDiagram
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]

Pour résoudre ce problème, le meilleur moyen, à mon avis, est de faire comme nous le ferions sur un document Rmarkdown ou un script R normal, et d’utiliser R et la bibliothèque DiagrammeR qui fournissent une fonction mermaid(), basée également sur mermaid.js.

DiagrammeR::mermaid("
stateDiagram
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]
")

Notez qu’il nécessite d’ajouter le paramètre diagram: true dans l’en-tête yaml de la publication (ou pour l’ensemble du site Web dans le fichier params.toml)

Plotly

Academic support Plotly, mais cela suppose que vous enregistriez d’abord les données dans un fichier json, et comme indiqué précédemment, le shortcode ne fonctionnera pas tel quel avec Pandoc.

Heureusement, en tant qu’utilisateurs de R, nous avons le merveilleux package ggplot2 pour créer de superbes visualisations, et le package plotly qui peut le transformer en un graphique interactif pour nous. Ainsi, au lieu de suivre l’exemple fourni par Academic, je recommande d’utiliser plotly directement à partir de R, comme le montre l’exemple suivant.

plot <- ggplot(penguins, aes(bill_length_mm, bill_depth_mm, color = species)) +
          geom_point() +
          theme_bw()
ggplotly(plot)

Conflit entre Plotly et Mathjax

Alors celui-ci m’a occupé pendant un moment…

Vous pouvez utiliser des expressions Latex avec Markdown, et cela fonctionne bien avec les fichiers .md et .Rmd. Cela nécessite de définir math: true dans l’en-tête yaml. Lorsque le paramètre math est défini sur true, les graphiques que j’ai créés avec Plotly ont disparu, ainsi que le diagramme créé avec DiagrammeR.

Alors, que s’est-il passé ? Apparemment, il y a un conflit entre Plotly et Mathjax, qui est utilisé pour rendre Latex, provoquant l’échec de Plotly. Le problème se produit lorsque Mathjax est chargé avant Plotly, ce qui est le cas ici, car Mathjax est chargé en premier lorsque math est défini sur true, et plotly est chargé ensuite dans le cadre du contenu du document Markdown. Je ne sais pas pourquoi le diagramme ne s’affiche pas non plus, mais comme Plotly et DiagrammeR utilisent tous deux des widgets html, je soupçonne que l’erreur pourrait s’y propager d’une manière ou d’une autre.

Alors comment y remédier ? Eh bien, nous devons charger Mathjax après Plotly, cela semble résoudre le problème. Pour ce faire, assurez-vous d’abord que math: false dans le fichier params.toml, et qu’il n’est pas dans la section d’en-tête du post, ou alors qu’il y est défini sur false également. Ensuite, chargez manuellement Mathjax dans le document .Rmd avec le code suivant :

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

Maintenant, cela fonctionne, Plotly est chargé automatiquement dans l’en-tête et Mathjax dans le contenu. Je peux afficher une équation écrite avec Latex et les graphique Plotly et les diagrammes sont toujours rendus dans la page.

\[ y = \beta_0 + \beta_1\times x + \epsilon \quad \text{with} \quad \epsilon \sim \mathcal{N}(\, \sigma_\epsilon) \]

Quoi d’autre?

Y a-t-il quelque chose qui fonctionne de la même manière entre la documentation et les fichiers .Rmd ?

Oui, callout fonctionne exactement de la même manière :

{{% callout note %}}
A Markdown aside is useful for displaying notices, hints, or definitions to your readers.
{{% /callout %}}

{{% callout warning %}}
A Markdown aside is useful for displaying notices, hints, or definitions to your readers.
{{% /callout %}}