Using RevealPack - RevealPack Documentation

Skip to content

# Getting Started With RevealPack

The main purpose of this package is to make it easy to develop, package and share multiple Reveal.js presentations that share common resources and theming, e.g., a lecture series.

This guide will walk you through the process of creating and building a Reveal.js presentation using RevealPack. Follow these steps to get started with your presentation project.

## Installation

To begin, install RevealPack using pip. Ensure you are using Python 3.12 or a compatible version.

    pip install revealpack

## Project Setup

1. Create a Project Directory:
   - Choose a directory for your project. Create a new directory if necessary.

    mkdir my_presentation_project
    cd my_presentation_project

1. Initialize the Project:
   - Initialize the RevealPack project in your chosen directory. This creates the necessary directory structure and configuration files.

    revealpack init

    Alternatively, specify a different directory and navigate there:

    revealpack init --destination /path/to/your/project
    cd /path/to/your/project

1. Update Configuration:
   - Modify the generated `config.json` file to suit your project needs. Update the `info`, `directories`, `packages`, `theme`, `reveal_template`, `toc_template`, `logging`, `highlight_theme`, `custom_scripts`, `force_plugin_download`, and `reveal_configurations` fields.

    {
      "info": {
        "project_title": "My Reveal.js Lectures",
        "short_title": "revealLectures",
        "version": "1.0.0",
        "authors": ["Your Name"]
      },
      "directories": {
        "build": "dist",
        "source": {
          "root": "source",
          "presentation_root": "decks",
          "libraries": "lib"
        }
      },
      "packages": {
        "reveal.js": "5.1.0",
        "reveal_plugins": {
          "built_in": ["notes", "highlight", "math"],
          "external": {
            "vizzy": {
              "version": "1.0.4",
              "url": "https://github.com/Khlick/Vizzy/releases/download/v1.0.4/vizzy.js"
            }
          },
          "plugin_configurations": {
            "mathjax3": {
              "mathjax": "https://cdn.jsdelivr.net/npm/mathjax@4.0.0-beta.6/tex-mml-chtml.js",
              "loader": {
                "load": ["[tex]/html"]
              },
              "tex": {
                "packages": {
                  "[+]": ["html"]
                },
                "inlineMath": [["$", "$"], ["\\(", "\\)"]]
              },
              "options": {
                "skipHtmlTags": ["script", "noscript", "style", "textarea", "pre"]
              }
            },
            "notes": {},
            "highlight": {},
            "vizzy": {
              "autoRunTransitions": true,
              "autoTransitionDelay": 100,
              "devMode": false,
              "onSlideChangedDelay": 0
            }
          }
        }
      },
      "theme": "custom_theme/theme.css",
      "reveal_template": "reveal_template.html",
      "toc_template": "toc_template.html",
      "logging": "detailed",
      "highlight_theme": "custom_theme/hybrid.css",
      "custom_scripts": [],
      "force_plugin_download": true,
      "reveal_configurations": {
        "controls": true,
        "progress": true,
        "slideNumber": true,
        "history": true,
        "center": true,
        "transition": "slide"
      }
    }

1. Setup the Project:
   - Set up the environment for building presentations. This step downloads and installs Reveal.js packages, creates necessary directories, checks the theme, and generates templates.

      revealpack setup

## Creating Presentations

1. Create Presentation Subdirectory:

   - In the `source/decks` directory, create a subdirectory for each presentation.

2. Add Presentation Files:

   - Inside the presentation subdirectory, add HTML files for each slide. Include a `presentation.json` file for additional metadata and configuration.

   Example `presentation.json`:

    {
      "titlepage": {
        "headline": [
          "Analysis of Variance 3",
          "ANOVA Does Even More"
        ],
        "by": "Khris Griffis, Ph.D.",
        "byinfo": [
          "April 10, 2024",
          "CSULA: ME3040 Spring 2024"
        ],
        "background": {
          "image": "lib/img/power_1.png",
          "size": "cover"
        }
      },
      "footer": {
        "left": "Lecture 19",
        "right": "<a href=\"https:\\\\khrisgriffis.com\" target=\"_blank\" rel=\"noopener noreferrer\">Khris Griffis &#169;2024</a>"
      },
      "slides": [
        "objectives.html",
        "anova-repeated-measures-recap.html",
        "anova-two-way.html"
      ]
    }

    When rendered, the final presentation will have the following title slide:

    ![Presentation Title Render](img/pres_title_render.png)
    *Figure 1. Example render of the presentation title. Note: This theming is provided by the custom_theme but your own may be different, see [theming](theme.md).*

    Example `objectives.html` (single slide):

    This slide only contains one section, so the section tags are not needed. The open and close tags are automatically handled by the template.

    ---
    ---

    <div class="grid-wrapper">
      <div class="header">
        <h2>Today's Objectives</h2>
      </div>
      <div class="content">
        <div class="grid-generic full-width left-justify big" style="grid-template-columns: 1fr; grid-auto-rows: auto; row-gap: 5vmin">
          <div class="border-bottom fragment" data-fragment-index="1">
            <p><i class="target"></i> Recap Repeated-Measures ANOVA</p>
          </div>
          <div class="border-bottom fragment" data-fragment-index="2">
            <p><i class="target"></i> Two-Way ANOVA Introduction</p>
          </div>
        </div>
      </div>
    </div>
    <aside class="notes">
      <p>Let's recap some of the concepts of ANOVA.</p>
    </aside>

    This individual slide is rendered in the final presentation as:

    ![Presentation Slide Render](img/pres_objectives_example.png)
    *Figure 2. Example render of an individual slide. Note: This theming is provided by the custom_theme but your own may be different, see [theming](theme.md).*

    Example `anova-two-way.html` (multiple slides and section title):

    This slide contains a section title, followed by multiple slides. The section title needs a closing section tag, which allows us to style the section title content.

    ---
    sectiontitle:
      headline:
        - "Factor Analysis"
        - "Two-Way ANOVA"
      image:
        url: "lib/img/multigroup_5.png"
    ---

    <style>
      #section-content-2.section-title-content {
        background-color: rgba(240,240,240,0.7) !important;
        border-radius: 2rem !important;
        box-shadow: 0 0 2rem 2rem rgba(240,240,240,0.7) !important;
      }
    </style>
    </section>

    <!-- Slide 1 -->
    <section>
    <!-- slide contents -->
    </section>

    <!-- Slide 2 -->
    <section>
    <!-- slide contents -->
    </section>

    <!-- Slide 3 (last slide, no closing section tag) -->
    <section>
    <!-- slide contents -->

    The section title in the `anova-two-way.html` file is the second section title in the presentation. We use CSS styles to create a light gray background for the overlay text, providing contrast against the background image.

    ![Presentation Section Title Render](img/pres_sectiontitle_render.png)
    *Figure 3. Example render of section title yaml. Note: This theming is provided by the custom_theme but your own may be different, see [theming](theme.md).*

    ### Vertical Slide Stacks

    If you wish to insert a vertical slide stack (a column of slides), you can open and close the vertical slide stack sections in the slide. The YAML header must be empty for the vertical stack:

    ---
    ---

    <section>
    <!-- Vertical Slide 1 -->
    </section>

    <section>
    <!-- Vertical Slide 2 -->
    </section>

    <section>
    <!-- Vertical Slide 3  -->
    </section> <!-- Close last slide for vertical stacks -->

## Building Presentations

Once you have your assets in the libraries folders, and you have a deck or two to build, run the `revealpack build` command to generate the presentations and the table of contents:

    revealpack build

After running the build command, the `dist` directory will contain the generated HTML files for each presentation and an `index.html` file as the table of contents.

## Serving Presentations Locally

To serve the presentations locally and watch for changes, run the `revealpack serve` command:

    revealpack serve

This will start a live server and automatically rebuild the presentations when changes are detected in the decks and related directories.

## Packaging Presentations for Distribution

To package the presentations into a distributable format, use the `revealpack package` command:

    revealpack package --build-dir path/to/new/export

For more details on each command, refer to the respective documentation pages:

- Init
- Setup
- Build
- Serve
- Package

For a complete list of configuration options, see the Configuration page.

## Developer Guide

For developers looking to contribute to RevealPack or customize it further, see the Developer Guide.