Configuration - RevealPack Documentation

Skip to content

# Configurations

Reference the table below for configuration options parsed by the `revealpack setup` command.

### Table 1. Configurations for `config.json`

Key | Sub-Key | Description
--- | --- | ---
`info` |  | Information about the project
| `project_title` | The full title of your project
| `short_title` | A short, concise title for your project
| `version` | The current version of your project
| `authors` | An array containing the names of the authors
`directories` |  | Configuration for directory structure used in the project
| `build` | Directory where the built presentation will be output (e.g., `dist`)
`directories.source` |  | Root configuration for source directories
| `root` | Root directory for all source files (e.g., `source`)
| `presentation_root` | Directory for storing individual presentation decks (e.g., `decks`)
| `libraries` | Directory for storing shared libraries and assets (e.g., `lib`)
`packages` |  | Configuration for Reveal.js and associated plugins
| `reveal.js` | The version of Reveal.js to be used (e.g., `5.1.0`)
`packages.reveal_plugins` |  | Plugins configuration for Reveal.js
| `built_in` | List of built-in plugins to include (e.g., `notes`, `highlight`, `math`)
| `external` | External plugins with their versions and download URLs
| `plugin_configurations` | Specific configurations for each plugin
`theme` |  | Path to the custom theme CSS file (e.g., `custom_theme/theme.css`)
`reveal_template` |  | Name of the Jinja2 template file for generating the presentation HTML
`toc_template` |  | Path to the Jinja2 template file for generating the table of contents HTML
`logging` |  | Logging level for setup and build processes (e.g., `error`, see logging docs.)
`highlight_theme` |  | Path to the highlight.js theme CSS file (e.g., `custom_theme/hybrid.css`)
`custom_scripts` |  | Array of custom JavaScript files to include in the presentation
`force_plugin_download` |  | Boolean to force re-download of plugins, even if they are already present
`reveal_configurations` |  | Configuration options for Reveal.js (see Reveal configuration)

## Specifications On Select Configurations

### `packages.reveal_plugins.external`

External plugins are optional, so the `external` field may be omitted. However, inclusion of external packages should be in the form of:

    {
      "packages": {
        "reveal.js": "5.1.0",
        "reveal_plugins": {
          "external": {
            "plugin1-name": {
              "version": "0.0.0",
              "url": "https://path/to/url.tar.gz"
            },
            "plugin2-name": {
              "version": "1.0.4"
            }
          }
        }
      }, // other config options
    }

Where `url` may be omitted if the package is locatable on npm with the template:

    plugin_url = f"https://registry.npmjs.org/{plugin}/-/{plugin}-{version}.tgz"

Additionally, the `alias` and `main` fields can be used to specify a different name for npm and the main JavaScript file, respectively:

    {
      "packages": {
        "reveal.js": "5.1.0",
        "reveal_plugins": {
          "external": {
            "plugin1-name": {
              "version": "0.0.0",
              "url": "https://path/to/url.tar.gz"
            },
            "plugin2-name": {
              "version": "1.0.4",
              "alias": "npm-plugin-name",
              "main": "main-file"
            }
          }
        }
      }, // other config options
    }

- `alias`: Specifies the npm package name if it differs from the plugin name.
- `main`: Specifies the main JavaScript file name if it differs from the plugin name. The `.js` extension is optional.

RevealPack will automatically cache downloaded plugins in the `directories.source.root` directory in a sub-folder `cached`. These plugins will be copied, unmodified, upon `build` and a reference will be generated with the expected relative reference:

    <script src="./src/plugin/{alias}/{main}.js"></script>

Where `{alias}` and `{main}` are placeholders for the alias and main file name, respectively. If `alias` is not provided, `{plugin}` will be used as the placeholder for the plugin name. Thus, the plugin shall have, e.g., `plugin2-name.js` or `main-file.js` in the unpacked directory. This is a common convention at the time of writing for Reveal.js plugins. Note that the directory unpacked from the url, or npm repo, download will be automatically named `f"{plugin}-{version}"` during the download and setup process.

If needed, the possible extensions for the `url` may be one of: `.zip`, `.tar.gz`, or `.js`. In the `.js` case, the JavaScript file will be downloaded to the cached directory under `f"{plugin}-{version}/{plugin}.js"`.

Here is an example of how to use the `alias` and `main` fields:

    {
      "packages": {
        "reveal.js": "5.1.0",
        "reveal_plugins": {
          "external": {
            "vizzy": {
              "version": "1.0.3",
              "alias": "vizzy-custom",
              "main": "vizzy-main"
            }
          }
        }
      }
    }

In this example, the plugin will be referenced in the HTML as:

    <script src="./src/plugin/vizzy-custom/vizzy-main.js"></script>

### `custom_scripts`

The `custom_scripts` configuration option allows you to include custom JavaScript files in your Reveal.js presentations. These scripts are specified in the `config.json` file and will be copied to the build directory during the build process. Each script will be inserted into the head of the generated HTML template, ensuring they are included in your presentation.

#### Configuration

In your `config.json` file, add an array under the `custom_scripts` key with the names of your JavaScript files. These scripts should be located in a subdirectory of the project root called `custom_scripts`.

Example `config.json`:

    {
      "custom_scripts": [
        "custom1.js",
        "custom2.js"
      ]
    }

#### How It Works

1. Specify Scripts: List your custom JavaScript files in the `custom_scripts` array in `config.json`.
2. File Location: Ensure that the specified scripts are placed in the `custom_scripts` directory in the project root.
3. Build Process: During the build process, these scripts will be copied to the `<build>/<libraries>/custom_scripts/` directory.
4. Template Insertion: The build process will insert the appropriate `<script>` tags into the head of the generated HTML template for each custom script.

Example script tags inserted into the HTML template:

    <script src="./lib/custom_scripts/custom1.js"></script>
    <script src="./lib/custom_scripts/custom2.js"></script>

By configuring `custom_scripts`, you can easily include custom functionality and extend your Reveal.js presentations with additional JavaScript code.

## Example `config.json`

Here is an example of what your `config.json` might look like:

    {
      "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",
              "alias": "vizzy-reveal",
              "main": "vizzy"
            },
          },
          "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"
      }
    }

#### Rendered Reveal (Jinja2) Template

    <!doctype html>
    <html lang="en">
        <head>
            <meta charset="utf-8">
            <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
            <title>{{deck.title}}</title>
            <link rel="icon" type="image/x-icon" href="lib\favicon.png">
            <link rel="stylesheet" href="./src/css/reset.css">
            <link rel="stylesheet" href="./src/css/reveal.css">
            <link rel="stylesheet" href="./src/theme/drG.css">
            <!-- highlight.js theme -->
            <link rel="stylesheet" href="./src/theme/hybrid.css">
            <!-- Custom Scripts -->

            <!-- Print PDF script -->
            <script>
                var link = document.createElement( 'link' );
                link.rel = 'stylesheet';
                link.type = 'text/css';
                link.href = window.location.search.match( /print-pdf/gi ) ? './src/css/print/pdf.css' : './src/css/print/paper.css';
                document.getElementsByTagName( 'head' )[0].appendChild( link );
            </script>

        </head>
        <body>
            <div class="reveal">
                <div class="slides">
                    {% if deck.titlepage %}
                    <section id="deck-title-slide" {%- if deck.titlepage.background -%}{%- for i,v in deck.titlepage.background.items() -%} data-background-{{ i }}="{{ v }}"{%- endfor -%}{%- endif -%}>
                        <div class="title-slide">
                        {% if deck.titlepage.image %}
                            <div class="image" style="background-image: url({{ deck.titlepage.image }});">
                            </div>
                        {% endif %}
                        <div class="headline">
                            {% if deck.titlepage.headline %}
                            {% for line in deck.titlepage.headline %}
                            {% if loop.first %}
                            <h2 class="r-fit-text">{{ line|title }}</h2>
                            {% else %}
                            <h3>{{ line|title }}</h3>
                            {% endif %}
                            {% endfor %}
                            {% endif %}
                        </div>
                        <div class="sub-header">
                            {% if deck.titlepage.by %}
                            {% for by in deck.titlepage.by %}
                            <p class="by">{{ by }}</p>
                            {% endfor %}
                            {% endif %}
                        </div>
                        <div class="byline">
                            {% if deck.titlepage.byinfo %}
                            {% for byinfo in deck.titlepage.byinfo %}
                            <p class="byinfo">{{ byinfo }}</p>
                            {% endfor %}
                            {% endif %}
                        </div>
                        <div class="background"></div>
                        </div>
                        {% if deck.titlepage.notes %}
                        <aside class="notes">
                        {% for note in deck.titlepage.notes %}<p>{{ note }}</p>
                        {% endfor %}
                        </aside>
                        {% endif %}
                    </section>
                    {% endif %}
                    {% set section_count = namespace(n = 0) -%}
                    {% for slide in deck.slides %}
                    {% if slide.sectiontitle %}
                    {% set section_count.n = section_count.n + 1 %}
                    <section id="section-title-{{ section_count.n }}"{% if slide.sectiontitle.image -%}
                     data-background-image="{{ slide.sectiontitle.image.url }}"{% for key, value in slide.sectiontitle.image.items() if key != 'url' -%} data-background-{{ key }}="{{ value }}"{% endfor -%}
                     {%- elif slide.sectiontitle.color -%}
                     data-background-color="{{ slide.sectiontitle.color }}"
                     {%- elif slide.sectiontitle.gradient -%}
                     data-background-gradient="{{ slide.sectiontitle.gradient }}"
                     {%- endif -%}>
                        <div class="grid-wrapper">
                            <div class="section-title-content"  id="section-content-{{ section_count.n }}">
                            <div class="section-number">
                                <span class="large-number">{{ section_count.n }}</span>
                            </div>
                            <div class="headlines">
                                {% for line in slide.sectiontitle.headline %}
                                {% if loop.first %}
                                <h2 class="r-fit-text">{{ line|title }}</h2>
                                {% else %}
                                <h3>{{ line|title }}</h3>
                                {% endif %}
                                {% endfor %}
                            </div>
                            </div>
                        </div>
                        {{ slide.content }}
                    {% else %}
                    <section {{ slide.attributes|to_html_attrs|safe }}>
                        {{ slide.content }}
                    {% endif %}
                    </section>
                    {% endfor %}
                </div>
                {% if deck.footer %}
                <footer class="main-footer">
                    <span>{{ deck.footer.left if deck.footer.left is defined else '' }}</span>
                    <span style="text-align:center;">{{ deck.footer.middle if deck.footer.middle is defined else '' }}</span>
                    <span style="text-align:right;">{{ deck.footer.right if deck.footer.right is defined else '' }}</span>
                </footer>
                {% endif %}
            </div>
            <script src="./src/reveal.js"></script>
            <script src="./src/plugin/notes/notes.js"></script>
            <script src="./src/plugin/highlight/highlight.js"></script>
            <script src="./src/plugin/math/math.js"></script>
            <script src="./src/plugin/vizzy/vizzy.js"></script>
            <script src="./src/plugin/reveal.js-menu/reveal.js-menu.js"></script>
            <script>
                Reveal.initialize({
                  center: false,
                  controls: true,
                  controlsBackArrows: "faded",
                  controlsLayout: "bottom-right",
                  display: "block",
                  fragments: true,
                  hideAddressBar: true,
                  hideCursorTime: 5000,
                  keyboard: true,
                  mobileViewDistance: 3,
                  mouseWheel: false,
                  navigationMode: "default",
                  overview: true,
                  pdfMaxPagesPerSlide: 1,
                  pdfSeparateFragments: false,
                  preloadIframes: true,
                  progress: false,
                  showSlideNumber: "print",
                  sortFragmentsOnSync: true,
                  touch: true,
                  transition: "fade",
                  transitionSpeed: "default",
                  viewDistance: 3,
                  width: 1920,
                  height: 1080,
                  margin: 0.125,
                  minScale: 0.1,
                  maxScale: 1.25,
                  plugins: [ RevealNotes, RevealHighlight, RevealMath, Vizzy ],
                  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: true,
                    onSlideChangedDelay: 0,
                  },
                });
            </script>
        </body>
    </html>