Ceci est une ancienne révision du document !
This last month I’ve been looking at the hugo-reveal theme more and more often as a method to create quick and functional slide decks using Reveal.js. Google Slides and Powerpoint/LibreOffice Impress (or Keynote on macOS) are functional, and what people generally think of when you say presentation or keynote. However, if you’re planning to present something to do with code, and want to use something like carbon.now.sh to make nicely formatted screenshots of your code, I highly recommend you take a look at this article before you make your final decision.
Project files All project files are on github. https://github.com/lswest/fcm-146-hugo-reveal If you prefer to download the files first, and simply follow along with the article, that’s fine.
Setup The first few steps to getting up and running are pretty simple: • Install git • Install hugo (odds are you can find a version in your local repositories - otherwise check gohugo.io). • Run: hugo new site presentation-name • Then you can do one of the following options: • run: git init in the folder created above, followed by: git submodule add https://github.com/dzello/reveal-hugo.git themes/reveal-hugo • Just download a zip archive from their github page (see further reading).
Starting your presentation There are a few things I usually do before writing any of the slides. I’ll be covering them in the next few headings. If you’re completely satisfied with the default appearance, just do the steps in the first heading.
Configure Hugo You’ll need to actually define the output type and the theme to use. This is the same information as you’d find on the reveal-hugo project page. I’ve placed the code on GitHub, so instead of pasting lines of code, I will refer to the following link and the corresponding line numbers. File: https://github.com/lswest/fcm-146-hugo-reveal/blob/master/config.toml lines: 5-10 I also highly recommend adjusting the archetypes file so you don’t need to constantly update the preamble for your files if you decide to split the slideshow up into multiple content files.
File: https://raw.githubusercontent.com/lswest/fcm-146-hugo-reveal/master/archetypes/default.md?raw=True What I do in this file is swap out the “—” with “+++” (to switch to TOML frontmatter), and then remove the draft = true, and set the output format. With the above two steps done, you can now create your first file: hugo new _index.md This will create a file under content/_index.md. In most cases, this file will contain your entire slideshow. If you prefer to split it up, you’ll want to check the project’s documentation for details.
Image shortcode I prefer to scale my images in the Markdown itself, instead of resizing it by hand. To do this, I edited an official example from the hugo Image Processing page for slideshows. File: https://github.com/lswest/fcm-146-hugo-reveal/blob/master/layouts/shortcodes/image.html Usage: image_file_resize_400x (note the lack of extension). The picture file should be in the same content folder level where the markdown file is – you’re calling the shortcode from.
Syntax Hugo-reveal puts a few of the Reveal.JS features behind shortcodes, and they are as follows: fragmentMarkdown goes herefragment - Allows you to step through the fragments (i.e. reveal one bullet point at a time) noteText goes herenote - Creates a note for the speaker view. sectionSlides go heresection - Creates a series of vertical slides. — - Start new slide ~~~ - Start/end code fragment. You can supply a programming language on the same line as your opening “~~~” (example: “~~~python”) For anyone wondering what the difference between “issue146” and “issue146” is - the percentage signs mean that markdown contained in the shortcode will be compiled, and the less than/greater than indicates that any inner text is just text.
Running the slideshow Just open a console, cd to the directory your hugo project is in, and run hugo serve. This will run the hugo site on http://localhost:1313 (by default at least). You can also build straight up HTML with hugo build if you want to host the files somewhere. Bear in mind that building the HTML and just opening it in the browser will disable some features (such as speaker notes).
Speaker notes Sometimes you want to make little notes for yourself on a slide, that aren’t visible to the audience. You can do this here as well, by using the note shortcode (see Syntax section). To open the speaker view, simply press the “s” key on your keyboard once the slideshow has started. It will open a new window and give you a presenter view. I would recommend you do this at the start of the presentation and move it to your monitor, leaving the normal slideshow on the projector. You can control the slideshow from the presenter view as well, and it will be synchronized between the two views.
Sharing your presentation After you’ve presented, you may want to put the slides up for anyone to look at, or to send it to your audience. While you can share the source code, it’s never going to be quite as convenient as a PDF. To create a PDF of the slides, you can visit http://localhost:1313/?print-pdf - this enables a special print stylesheet. After that, just print the page from your browser, and choose a PDF printer (or save to PDF). An example can be found here: https://github.com/lswest/fcm-146-hugo-reveal/blob/master/FCM%20146%20Example%20Slide%20Deck.pdf
Conclusion Hopefully this article has adequately shown why Reveal.JS should be a valid consideration when creating code-heavy slideshows. If you have already used it, feel free to let me know about any bugs or issues you’ve run into. Also, if you have any questions or requests for new articles, feel free to reach out to me at lswest34+fcm@gmail.com.
Further Reading https://github.com/dzello/reveal-hugo - reveal-hugo GitHub project. https://github.com/lswest/fcm-146-hugo-reveal - The project demo I set up for this article.