Creating slides in Hugo Academic using remarkJS

Last updated on Mar 24, 2020 5 min read

In this post, I am going to describe how I installed and used a remark.js slide deck within the framework of Hugo using the Academic theme. First, I describe how I installed the relevant packages and then I am going to lay out what kinds of customizations I made.

1. Installation of relevant software

1.1 Hugo

The installation of the static website generator Hugo is pretty straight-forward and well described on the official website.

1.2 The Academic theme

The Academic theme is also amazingly documented and the I did not encounter any difficulties during the installation.

By default, reveal.js is used for to create slides in the Academic theme but, after trying it out for a bit, I had the strong feeling that remark.js suits my needs better. The talks I give usually involve a lot of figures and formulas. So how did I get remark.js to work?

2. Getting remark to work

Luckily, this is also well-documented on the Academic theme site. - see instructions in remark git repo: using with hugo

<!DOCTYPE html>
<html>
  <head>
    <title>Title</title>
    <meta charset="utf-8">
    <style>
      @import url(https://fonts.googleapis.com/css?family=Yanone+Kaffeesatz);
      @import url(https://fonts.googleapis.com/css?family=Droid+Serif:400,700,400italic);
      @import url(https://fonts.googleapis.com/css?family=Ubuntu+Mono:400,700,400italic);

      body { font-family: 'Droid Serif'; }
      h1, h2, h3 {
        font-family: 'Yanone Kaffeesatz';
        font-weight: normal;
      }
      .remark-code, .remark-inline-code { font-family: 'Ubuntu Mono'; }
    </style>
  </head>
  <body>
    <textarea id="source">

class: center, middle

# Title

---

# Agenda

1. Introduction
2. Deep-dive
3. ...

---

# Introduction

    </textarea>
    <script src="https://remarkjs.com/downloads/remark-latest.min.js">
    </script>
    <script>
      var slideshow = remark.create();
    </script>
  </body>
</html>

didn’t work because couldn’t push to academic repo
didn’t realize that there is supposed to be a top-level layouts folder (not there in hugo-academic)
create it manually, add code from remark -using with hugo website
replace header with basic template from remark website
it works!

3. Customization

So far, everything has been pretty obvious and just entailed following the instructions in the respective docs. But as soon as I got working on my first presentation in remark.js, I realized that I would need some customizations.

3.1 Multi-columns

I created a custom CSS file containing some classes that I wanted to use. Specifically, I wanted to have the possibility to display content in multiple columns, e.g. in order to display a bullet-point list next to a figure, each column taking up a certain percentage of the overall slide. I decided to go for two simple divisions, namely 50-50 and 60-40, the latter also in its reverse variant. This is what I went for:

.left-col50 {
      width: 49%;
      float: left;
}

.right-col50 {
      width: 49%;
      float: right;
}

.left-col33 {
      width: 33%;
      float: left;
}

.right-col66 {
      width: 66%;
      float: right;
}

.left-col66 {
      width: 66%;
      float: left;
}

.right-col33 {
      width: 33%;
      float: right;
}

It has been a while that I dealt with CSS. I am quite sure that there is a better way to do it. But since my talk was approaching fast, I opted for a pragmatic solution. I can imagine that using inheritance and taking into account pre-existing classes from the Academic theme could make the code more elegant and potentially shorter.

3.2 References

Since I was goint to present some research, wanted to be able to display citations and references. The references should appear on the lower-right bottom of the slide and have a smaller fontsize, while in-text citations should be displayed in gray and also have a smaller fontsize:

.ref {
  font-size: 60%;
  max-width: 66%;
  text-align: right;
  padding: 0 0 0 33%;
  position: absolute;
  bottom: 7%;
  right: 7%;
}

.cite {
  font-size: 80%;
  color: gray;
}

I would also love to find out how to get the references in my slides directly from a BibTeX file instead of copying (and formatting) the references on the slides themselves.

3.3 Figure captions

Finally, I added a class to display figure captions and one to display emphasized content:

.caption {
  font-size: 75%;
  text-align: center;
}

.alert {
  color: red;
}

3.4 Math and LaTeX formulas

As I would need to display LaTeX formulas, I followed THIS instruction and added the following code to single.html:

// Setup MathJax
MathJax.Hub.Config({
    tex2jax: {
      skipTags: ['script', 'noscript', 'style', 'textarea', 'pre']
    }
});

MathJax.Hub.Configured();

3.5 Audio and video

Since virtually all my talks are somehow about music, including sound in the slideshow is indispensable for me but since remark.js creates HTML files, I could simply add the HTML5 <audio> tag and point the src argument to the file I wanted to play.

<audio controls>
  <source src="file.wav" type="audio/wav">
  Your browser does not support the audio element.
</audio>

The controls parameter displays the play/stop buttons. What I haven’t figured out yet (not even whether it is possible in principle) is how to make a sound start or stop on click/key press/etc. For videos, it should work analogously by using the <video> tag.

Well, and that’s it already. That’s all one needs to know in order to use remark.js together with the Hugo Academic theme and do some basic style customizations.

4. Issues

For some reason, I only got this to work when the custom.css file was put in the same directory as the slides’ index.md which is not optimal, since this would require me to create one CSS files for each presentation. I asked this question in the Spectrum and got amazing help buy XXX. I will check out his suggested solution soon, since the talk is now given and I can risk to destroy everything again.

My pragmatic approach for multi-column slides has a big shortcoming: I am unable to use -- for incremental slide display within a column. This is definitely annoying and I am planning to find out how to alter this as soon as possible.

5. Conclusion

It remains to be seen whether I will stick to remark.js for all future presentations but so far I do not see why not. Since everything is based on markdown (and HTML/CSS), version-controlling the files is as easy as it could only be. Plus, the integration into Hugo’s system works flawlessly which is particularly nice.

I am a bit concerned once I want to show formulas and diagrams (potentially incrementally) wich I did with LaTeX/Tizk before. Anyway, if you want to have a look at my first attempt with remark.js, check out my very first talk.

Fabian C. Moss

Postdoctoral Researcher

Fabian C. Moss is a postdoctoral researcher in the Digital and Cognitive Musicology Lab (DCML) at École Polytechnique Fédérale de Lausanne (EPFL, Switzerland). He was born in Cologne, Germany, and studied Mathematics and Educational Studies at University of Cologne, and Music Education (Major Piano) and Musicology at Hochschule für Musik und Tanz, Köln. Working with large symbolic datasets of musical scores and harmonic annotations, he is primarily interested in Computational Music Analysis, Music Theory, Music Cognition, and their mutual relationship.