Troubleshooting with Blogdown and Academic theme

Different rendering Engines

Hugo comes with its own rendering engine, called Goldmark to render markdown files. Rstudio uses another engine Pandoc. Pandoc has more function, but may not understand all the syntax used by Goldmark, which is a source of problem when using blogdown to render a Rmarkdown document.

Blogdown uses Goldmark to render .md files, and Pandoc for .Rmd files.

As a R user, it’s likely that we are going to post about R with examples, so we will use .Rmd files. The theme uses .md files, and all the documentation syntax is made to work for Hugo and Goldmark so when you want to use some code coming from the documentation, it may fail when rendering your .Rmd file with Pandoc.

Blogdown::shortcode()

Academic provide a shortcode to create a spoiler box, to display the text only after clicking on a button.

The documentation provide the following syntax :

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

But intead of displaying the button, it simply writes the following text :

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

Obviously it’s not what we expected. To fix this sort of problem, Blogdown provide a function shortcode(). It tells markdown not to convert it with Goldmark as it is a Hugo shortcode. The syntax is :

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

And then it works :

There are different shortcode() functions and you may want to read the documentation to use the best one in your context :

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

htmltools::HTML()

Another example is the possibility offered by the theme to use icons and emoji. According to the documentation, the following code should display the icon for R with the text “R” :

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

But it fails, as Pandoc doesn’t recognize the shortcodes :

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

So why does this happen? Because Pandoc render the sign < as its html code < and the signe > as >, the shortcode becomes {{< icon name=“r-project” pack=“fab” >}} which is not interpreted anymore as a shortcode by Hugo and is just displayed as text.

To render it properly, we can use in a R chunk the function htmltools::HTML() which marks the text as HTML and will not escape the special characters like < or >

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

Now it works :

R

Diagram

Academic can render diagram with mermaid, but once again, the syntax provided with .md files won’t work with Pandoc, as shown below from an example of the sample website:

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

renders as

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

To fix that issue, the best way, in my opinion, is to do like we would do on a normal Rmarkdown document or R script, and use R and the library DiagrammeR which provide a mermaid() function, based on mermaid.js as well.

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

Note that it requires to add the parameter diagram: true in the yaml header of the post (or for the whole website in the params.toml)

Plotly

Academic support Plotly, but it supposed that you save the data in a json file first, and as discussed before, the shortcode won’t work as is with Pandoc.

Fortunately, as R users we have the wonderful package ggplot2 to create awesome visualization, and the package plotly that can transform it to an interactive plot for us. So instead of following the example provided by Academic, I recommend to use plotly directly from R, as shown in the following example.

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

Conflict between Plotly and Mathjax

So this one kept me busy for a while …

You can use Latex expressions with markdown, and it works fine both with .md and .Rmd files. It requires to set math: true in the yaml header. When the parameter math is set to true, the plots that I created with Plotly disapeared, as well as the diagram created with DiagrammeR.

So what happened ? Apparently, there is a conflict between Plotly and Mathjax, which is used to render Latex, causing Plotly to fail. The problem occurs when Mathjax is loaded before Plotly, which is the case here, as Mathjax is loaded first when set math to true, and plotly is loaded next as part of the content of the markdown document. I don’t know why the diagram fails to display as well, but as Plotly and DiagrammeR both use htmlwidgets, I suspect that the error might spread there somehow.

So how to fix it ? Well we need to load Mathjax after Plotly, it appears to fix the problem. In order to do that, first make sure that math: false in the file params.toml, and that it is not in the post header section, or set to false as well. Than load manually Mathjax in the .Rmd document with the following code :

<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>

Now it works, Plotly is loaded automatically in the header, and Mathjax in the content. I can display an equation written with Latex and the plots and diagrams are still rendered in the page.

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

What else?

Is there something that works the same between the documentation and .Rmd files ?

Yes, callout works exactly the same :

{{% 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 %}}