September 12, 2018

org-reveal and GitLab

As some of you may know, I'm a huge fan of Emacs. I basically do all of my programming, emailing, planning, and scheming in it. Although it is primarily seen as a text editor by some, it is so much more than that. I won't get into it here, but suffice it to say that when I was asked to make a presentation, I immediately thought of org-reveal.

RevealJS is an HTML presentation framework used to generate very professional looking slides. It is an amazing toolkit, and one you should definitely explore. On its own, one can certainly create killer presentations, but HTML is the primary method of editing:

<html>
  <head>
    <link rel="stylesheet" href="css/reveal.css">
    <link rel="stylesheet" href="css/theme/white.css">
  </head>
  <body>
    <div class="reveal">
      <div class="slides">
        <section>Slide 1</section>
        <section>Slide 2</section>
      </div>
    </div>
    <script src="js/reveal.js"></script>
    <script>
      Reveal.initialize();
    </script>
  </body>
</html>

HTML is great, but it's not entirely easy to work with. Compare this, with an equivalent org file.

#+TITLE: How cool is org-reveal?
#+AUTHOR: Joe Cool
#+REVEAL_ROOT: http://cdn.jsdelivr.net/reveal.js/3.0.0/

* Slide 1
* Slide 2
[./someimage.png]
** Sub-slide
Nice, right? To get this working, you'll need a relatively modern copy of Emacs, org-mode and org-reveal. An older version of org-mode is shipped with Emacs, but upgrading it is necessary to have the latest org-reveal features. Consider updating your Emacs init file to include org-mode's ELPA archivesinstructions. Then use, M-x package-install org-mode. 
(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/"))
(add-to-list 'package-archives '("org" . "http://orgmode.org/elpa/") t) ; Org-mode's repository
(package-initialize)

If you're using Spacemacs, you'll want to enable the org layer. RevealJS support is already built-in and simple to enable. After you've set up your environment, create a foo.org file and export the org file into a RevealJS presentation with the following key sequence: C-c C-e R B. This will generate the HTMl document and open a browser for you to view your handiwork.

Since I'm a developer by profession, and much of my job revolves around being able to continuously compile and deliver assets, I naturally wanted to make sure I could do so with the presentation. In addition to providing an amazing interactive experience to the user, Emacs can also be used in "batch mode".

emacs foo.org --batch -x org-reveal-export-to-html --kill

foo.html will be built in the same directory as the org file. It is now possible to automate building the RevealJS presentation artifacts in a CI/CD pipeline. My current favorite platform for this is GitLab. Unlike GitHub, GitLab does not require a separate platform like TravisCI to provide a Continuous Intergration platform. Instead, you write a simple YAML file that describes your setup and build steps, taking advantage of an isolated Docker build environment.

To get started, create a separate directory containing the org presentation file, any media used in that file, and add the following .gitlab-ci.yml file in the root of the project.

image: iquiw/alpine-emacs
before_script:
  - emacs -q --load init.el --batch --kill
build-job:
  script: emacs -q --load init.el foo.org --batch -x org-reveal-export-to-html --kill
  artifacts:
    paths:
      - foo.html
      - someimage.png

Additionally, include this in the init.el file:

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "https://melpa.org/packages/") t)
(add-to-list 'package-archives
             '("org" . "http://orgmode.org/elpa/") t)
(package-initialize)

(unless (package-installed-p 'use-package)
  (package-install 'use-package))

(use-package org
  :ensure t)
(use-package ox-reveal
  :ensure t
  :after org)

Now, as changes are checked in to the project, they'll be available as artifacts for the build-job, as indicated in the YML file. build-job can be any job name desired, so use it to describe the step or contents. Whatever makes most sense.

Tags: emacs