Section 34.1 Reveal.js

To create a reveal.js slideshow using pretext, start by creating a new project as follows.

$ pretext new slideshow

You will notice a few differences from a standard project. In the project manifest, the format is “custom”, and there is an <xsl> tag that points to a custom xsl stylesheet in the xsl folder of the project. This will import the correct reveal.js stylesheet. After authoring your slides, you can build them with the following command.

$ pretext build web

xsltproc --xinclude -o path/to/output/slides.html
  --stringparam publisher path/to/source/publication.xml
  path/to/pretext/xsl/pretext-revealjs.xsl path/to/source/slides.xml

Reveal.js supports themes that affect the overall appearance of a slideshow. So in PreTeXt you can specify the name of theme in a publication file. See Subsection 45.6.1 for details.

You might assume that your slideshow will be presented with the internet available, perhaps in a classroom, and will be updated for use the next semester. Or maybe you are presenting at a conference where you do not want to trust an unfamiliar internet connection, and you will later host an archival version of your presentation on your website and you want it to “just work” ten years from now. So you can configure your slideshow to obtain resources from a Content Delivery Network (CDN) online, or you may arrange to copy the necessary files from reveal.js and store them locally (your hard disk, your website). See Subsection 45.6.4 for details on specifying these options, and see below for directions on how to organize the Reveal.js support files.

A third possibility is a single-file slideshow: elect host="embedded" on the <resources> element of your publication file, and the build retrieves the reveal.js files from the CDN once and folds them into the HTML file itself, along with every stylesheet and the fonts a theme uses. Embedded resources require embedded mathematics (next), so this election implies math="embedded" as well; an explicit math="online" alongside is a contradiction, draws an error, and the slideshow is built fully online instead. The result is one HTML file that presents in a browser with no network connection at all—with the usual exceptions for genuinely online services: Sage cells, embedded interactives, and the syntax highlighting of program listings each fetch their own resources when the network is available, and degrade quietly when it is not. Any images in your slides are still separate files in the managed directories alongside the HTML file. Building this way requires a network connection, and each build embeds the newest release of the reveal.js major version.

By default, Reveal.js will render LaTeX syntax with MathJax, entirely similar to how MathJax is used in the PreTeXt conversion to HTML. This is accomplished with the Reveal.js math plugin, which is loaded automatically as part of your output. When you specify that resources come from a CDN, then this plugin will also get MathJax from a CDN. When you specify that resources are available locally (your hard disk, your website), then the plugin itself will be obtained locally, but MathJax will still be obtained from a CDN. (Reveal.js can be configured to use a locally installed copy of MathJax, but we have not provided any support for this scenario.)

Alternatively, the mathematics can be embedded: at build time each piece of mathematics is replaced by an SVG image of its typeset appearance, along with a speech string that a screen reader can voice. The slideshow then never loads MathJax and performs no typesetting at all, so the mathematics appears instantly, does not depend on any network resource, and is always complete when the slideshow is exported to PDF. Combined with local resources (above), the entire slideshow can work offline—though online services such as Sage cells or embedded interactives remain online, and note that a Sage cell will fetch its own copy of MathJax to typeset the output of an evaluation. One trade-off: a speech string is fixed text, while MathJax rendered in the browser offers a screen-reader user interactive exploration of an expression. In the same spirit, an annotated PreFigure diagram becomes a static image, in place of its interactive keyboard-driven exploration. Elect this with the @math attribute of the <resources> element in your publication file (Subsection 45.6.4). The images are manufactured during the build by the node version of MathJax, which must be installed locally; see Section G.1 for instructions.

We are not enthusiastic about PDF as an electronic format. But it might be a good choice as an archival format, and a PDF presents well from the fullscreen (presentation) mode of a PDF viewer, so it may even be your final product. Reveal.js has an export procedure built in, though it is a bit of a hack: in a Chromium-based browser (only), open the slideshow with ?print-pdf appended to the address (before any # fragment), which lays the deck out one slide per page, and then print to a PDF file, setting margins to “None” and enabling background graphics. The page size of the resulting PDF is the size of a slide, so paper-size and orientation settings are irrelevant. Embedded mathematics (above) is always complete at print time; with online mathematics, wait for the typesetting to finish before printing.

An alternative is the decktape node (Javascript) program, suggested by Andrew Rechnitzer on 2020-08-01. The reveal plugin works well once you settle on a resolution (the -s option). The generic plugin, along with the default key action (ArrowRight) can capture the behavior of slides built using the @pause attribute. Note that the grid option (see below) may not always work well for printing all slides, while default creates slides that decktape steps through properly. A local web server can also be employed to serve up the slides, see Section 5.11.

talk
    slides.html
    reset.css
    reveal.css
    reveal.js
    theme
        solarized.css
    plugin
        math.js