sphinx-revealjs

sphinx-revealjs is Sphinx extension to generate Reveal.js presentation documents from standard reStructuredText.

Basic Features

  • Nested sections

  • Speaker note

  • Syntax highlight for Reveal.js (not used pygments)

  • Customize slides and sections by conf.py or source reST

Demo

Screenshot of source Sphinx doc
Screenshot of Reveal.js slide

Concept and motivation

Goal of this library is to provide presentation platform for self-branding of engineer using Sphinx. Using static site hosting service, you can show own presentations to anyone.

Core motivation is that I want to play presentation by this library.

Contents

Setup

Requirements

sphinx-revealjs requires Python 3.6+ and Sphinx.

Current development environment

  • Python: 3.10.4

  • Sphinx: 4.3.2

Installation

You can install sphinx-revealjs from PyPI.

$ pip install sphinx-revealjs

sphinx-revealjs specify Sphinx and docutils expressly as dependencies. You get Sphinx by this command only.

Configuration

sphinx-revealjs does not provide revealjs builder instead of html builder. To use builder, edit your conf.py.

extensions = [
    "sphinx_revealjs",
]

if you want to configure more, edit conf.py with seeing Configurations.

Build

Run make command to build presentations. Files are generated to revealjs folder.

$ make revealjs

You can generate all pages as index.html to use dirrevealjs.

make dirrevealjs

Upgrading guide

Upgrading from 0.x to 1.x

From version 1.x, this bundle Reveal.js 4.x, and implement for it. Due it, documentations for old version does not work to build correctly.

You have to lock version, or migrate source for next version.

Configurations
revealjs_script_plugins

Reveal.js 4.x has big changes for usage of plugins from 3.x.

sphinx-revealjs is also adjust for this changes, and need update revealjs_script_plugins .

revealjs_script_plugins = [
    {
+        "name": "RevealNotes",
+        "src": "revealjs4/plugin/notes/notes.js",
-        "src": "revealjs/plugin/notes/notes.js",
    },
    {
+        "name": "RevealHighlight",
+        "src": "revealjs4/plugin/highlight/highlight.js",
-        "src": "revealjs/plugin/highlight/highlight.js",
-        "options": """
-            {async: true, callback: function() { hljs.initHighlightingOnLoad(); } }
-        """
    },
]

  • Changed structure from src and options to src and name.

    • For 4.x, to use plugin for core,
      add class name of it not source path,
      and need to preload source by script tag.
    • Class name is defined in plugin source.
      You need find from source or ref documents (official plugin only)

    • In adding, does not accept options for plugins.

MORE: See Using Plugins from Reveal.js document

revealjs_css_files

If you use highlight plugin and specify bundled stylesheet file, change path of stylesheet. Style files is migrated to highlight plugin folder.

  • Before: revealjs/lib/css/zenburn.css

  • After: revealjs4/plugin/highlight

Upgrading from 1.x to 2.x

From 2.x, some features are removed because splitted other extensions or duplicated behaviors. If you want to use new version by documentation using 1.x, you should upgrade project files.

Fonts

sphinx-revealjs does not support font configuration features to provide features as “Presentation tools”.

If you want to use Google Fonts

You can add CSS URL into revealjs_css_files directly.

revealjs_css_files = [
    "https://fonts.googleapis.com/css2?family=Noto+Sans+JP",
    "css/custom.css",
]

Example of css/custom.css.

.reveal *, .reveal h1, .reveal h2, .reveal h3, .reveal h4, .reveal h5, .reveal h6 {
    font-family: 'Noto Sans JP', sans-serif;
}
Use googlefonts-markup

If you want to write only font-family, use googlefonts-markup.

from googlefonts_markup import Font

revealjs_css_files = [
    Font(family_name="Noto Sans JP").css_url(),
    "css/custom.css",
]
Change using Google Fonts per presentations

You need to create custom theme per presentations.

# Define default theme
revealjs_style_theme = "black"

=====
Title
=====

.. Set `revealjs-slide/theme` to override theme

.. revealjs-slide::
   :theme: "css/theme-for-this-presentation.css"
Speaker Views

New configration revealjs_notes_from_comments are defined. But, because default values is False, your presentation not write speaker-note when you upgrade sphinx-revealjs

Configuration for compatible behaviors

You can set True revealjs_notes_from_comments to use behaviors of ver 1.x.

revealjs_notes_from_comments = Ture
Configurations
html_js_files/revealjs_js_files

sphinx-revealjs does not ref html_js_files as list of additional JavaScript files. It refer only revealjs_js_files.

You must do one of these.

  • Copy needy values of html_js_files to revealjs_js_files

  • Sync html_js_files to revealjs_js_files (ex: revealjs_js_files = html_js_files)

revealjs_use_index

sphinx-revealjs does not generate genindex.html (list of in vals) on default. If you want genindex.html for Reveal.js builder, you muse set True.

Directives

sphinx-revealjs defines kebab-cased directives only, and removed snake-cesed directives. You must replace cases to run by 2.x.

Before

After

revealjs_break

revealjs-break

revealjs_fragments

revealjs-fragments

revealjs_section

revealjs-section

revealjs_slide

revealjs-slide

Configurations

sphinx-revealjs can build multiple presentations. You can configure in conf.py for all presentations.

Basic configurations

revealjs_static_path
Type:

list

Default:

[] (empty)

Example:

["_static"]

List of static files directory ( same as html_static_path )

revealjs_js_files
Type:

list

Default:

[] (empty)

Example:

["custom.js"]

List of using custom css (same as html_js_files ).

When you want to use JS that does not related revealjs, can use this.

revealjs_css_files
Type:

list

Default:

[] (empty)

Example:

["custom.css"]

List of using custom css (same as html_css_files ).

If you want to customize presentation by CSS, write external css and use it.

revealjs_use_index
Type:

bool

Default:

False

Flag that does builder generate genindex.html (same as html_use_index ).

Style Configurations

revealjs_style_theme
Type:

str

Default:

black

Example:

moon, custom.css

Theme name of stylesheet for Reveal.js.

  • If value does not have suffix .css,
    use bundled Reveal.js theme(included revealjs/css/theme).

Presentation Configurations

revealjs_use_section_ids
Type:

boolean

Default:

False

If this is set True, inject id attribute into section element (parent of headerings). This means that change format of internal links (default is numbering style).

revealjs_script_files
Type:

List[str]

Default:

[]

Example:

["presentation.js"]

List of sources that render as script tags.

There is bundled Reveal.js script at revealjs/js/reveal.js.

Example:

<div>
  <!-- Presentation body -->
</div>
<!-- here!! -->
<script src="_static/revealjs/js/revealjs.js"></script>
<script src="_static/presentation.js"></script>
revealjs_script_conf
Type:

str or dict

Default:

None

Configuration of Reveal.js presentation. This value is used as options of Reveal.initialize in output files.

  • If value is string type, handle as raw javascript code.

  • If value is dict object, convert to json string at internal.

Example 1: case of str

revealjs_script_conf = """
{
    controls: false,
    transition: 'zoom',
}
"""

<div>
  <!-- Presentation body -->
</div>
<script src="_static/revealjs/js/revealjs.js"></script>
<!-- here!! -->
<script>
  let revealjsConfig = {};
  revealjsConfig = Object.assign(revealjsConfig, {
    controls: false,
    transition: 'zoom',
  });
  revealjs.initialize(revealjsConfig);
</script>

Example 2: case of dict

revealjs_script_conf = {
    "controls": False,
    "transition": "zoom",
}

<div>
  <!-- Presentation body -->
</div>
<script src="_static/revealjs/js/revealjs.js"></script>
<!-- here!! -->
<script>
  let revealjsConfig = {};
  revealjsConfig = Object.assign(revealjsConfig, JSON.parse('{"controls": false, "transition": "zoom"}'));
  revealjs.initialize(revealjsConfig);
</script>

example 1 and 2 are behaving same.

revealjs_script_plugins
Type:

List[Dict]

Default:

[]

List of plugin configurations. If this value is set, render script tag after source script tags.

There are bundled Reveal.js plugins at revealjs/plugin.

Example:

revealjs_script_plugins = [
    {
        "src": "revealjs4/plugin/highlight/highlight.js",
        "name": "RevealHighlight",
    },
]

<div>
  <!-- Presentation body -->
</div>
<script src="_static/revealjs/js/revealjs.js"></script>
<script src="_static/revealjs/plugin/highlight/highlight.js"></script>
<!-- here!! -->
<script>
  let revealjsConfig = {};
  revealjsConfig.plugins = [RevealHighlight,];
  revealjs.initialize(revealjsConfig);
</script>
revealjs_notes_from_comments
Type:

boolean

Default:

False

If this is set True, builder writes notes section from comment block.

Font configurations

Note

These configurations will be dropped when version 2.x.

You can use raw CSS or googlefonts-markup instead of these.

revealjs_google_fonts
Type:

dict

Default:

[]

Example:

[]

List of using fonts from Google Fonts. If this value is set, render link and style tags into html.

revealjs_generic_font
Type:

str

Default:

sans-serif

Example:

serif, monospace

If you use revealjs_google_fonts, set last of font-family style.

Directives

sphinx-revealjs provides some directives to customize presence and behaviors.

For customize presentation

Sphinx can manage multiple documents, so that sphinx-revealjs can build multiple presentation slides.

If you want to configure one presentaion from some, use this directive into your source.

.. revealjs-slide::

Write revealjs-slide directive on directly below of title header.

Note

Directive based customize has options less than conf based because implementation restrict.

:theme: (string)

Override revealjs_style_theme.

:google_font: (string)

Override revealjs_google_fonts, but it can specify only one.

:conf: (JSON-string or no-value)

Override revealjs_script_conf, but single line only.

Usage:

Presentation title
==================

.. revealjs-slide::
   :theme: moon

Section
-------

Content

For customize sections

If you want to change behavior of sections, use these directives.

.. revealjs-section::

To change behavior per section, write directive per section.

:data-XXX:

This directive can accept attribute as same as Reveal.js section tags.

Usage:

Write revealjs-slide directive on directly below of section title header.

Title
=====

Section
-------

.. revealjs-section::
   :data-background-color: #009900
.. revealjs-break::

If you want to transition section with keeping title, revealjs-break can use.

Usage:

Write revealjs-break to point of want to split section.

Title
=====

Section
-------

Content 1

.. revealjs-break::

Content 2(next slide)
:data-XXX:

It accepts attributes as same as revealjs-section.

:notitle:

If it is set in directive, next section page does not display title.

For interactive contents

.. revealjs-code-block::

This is extends of code-block direcrive for presentation.

If you want to use data-line-number attributes in code-block.

:data-line-numbers: (string or no value)

Code highlighting pattern. See Reveal.js document

Example:

.. revealjs-code-block:: python
   :data-line-numbers: 1

   def hello():
       print("world")
.. revealjs-fragments::

Note

There are cases not working regular.

Inject fragment attribute into objects. Referer to “Fragments” from Reveal.js

Example:

Write block as directive that you want to present as fragments.

.. revealjs-fragments::

   * First
   * Second
   * Third

See demo

.. revealjs-notes::

When you write this section, inner text are as content of Speaker View.

If you write some directives on same-level, Reveal.js uses first direcrive only.

Note

You must be careful for comment block when you set revealjs_notes_from_comments in conf.py. Reveal.js recoginzes first <aside> element as content of speaker-view, so you may not see directive content as notes.

Example:

.. revealjs-notes::

   This content output into <aside> element on <section>.

Using examples

List

Customizing design simply

When using bundled theme, you can customze design by adding custom CSS.

Example: Disable transform style in header text

Some of reveal.js bundled themes (ex: black ) set uppercase in text-transform of heading texts. You can add extra custom CSS to use other settings.

Source
conf.py
revealjs_css_files = [
    "revealjs4/plugin/highlight/zenburn.css",
    "custom.css",
]
custom.css
.reveal h1, .reveal h2, .reveal h3, .reveal h4, .reveal h5, .reveal h6 {
   text-transform: none;
}

Changelog

ver 2.0.0

date:

2022-05-31

base:

Reveal.js 4.3.1

Added Features

  • Directive revealjs-notes writes speaker-view content into presentation

  • Config reveajs_notes_from_comments toggle if it creates speaker-view content from comment-block

    • BREAKING CHANGE: Default value is False. You must set True explicitly to use as same as ver 1.x

  • Config reveajs_use_index toggle if it creates genindex.html

    • BREAKING CHANGE: Default value is False. You must set True explicitly to use as same as ver 1.x

Fixes
Deleted feaures

  • Remove snake-cesed directives

  • Does not generate search.html

Old versions

Version 1.x
ver 1.5.3
date:

2022-06-02

base:

Reveal.js 4.3.1

Fixes

  • All nodes for sphinx-revealjs does not write anything when none revealjs builder works.

ver 1.5.2
date:

2022-04-29

base:

Reveal.js 4.3.1

Fixes

  • Work revealjs-break directive in dirrevealjs builder (#109)

  • Inherit behavior of any nodes from html builder to dirrevealjs builder (#108)

Deprecated

Mark as deprecated(logging.warning) to drop at version 2.x (updated from v1.5.0)

  • Snake-cased directive ( revealjs_slide, revealjs_section and revealjs_break )

  • CSS Font configurations ( revealjs_google_fonts and revealjs_generic_font )

  • Passing values from html_js_files to revealjs_js_files

ver 1.5.1
date:

2022-04-21

base:

Reveal.js 4.3.1

Fixes

  • Add role="main" into page.html for searching by Sphinx (#102)

Misc

  • Add documentation link into metadata (PyPI)

ver 1.5.0
date:

2022-04-11

base:

Reveal.js 4.3.1

Features

  • Add dirrevealjs builder to generate all pages as index.html

Deprecated

Mark as deprecated(logging.info) to drop at version 2.x

  • Snake-cased directive ( revealjs_slide, revealjs_section and revealjs_break )

  • CSS Font configurations ( revealjs_google_fonts and revealjs_generic_font )

  • Passing values from html_js_files to revealjs_js_files

  • Full-support for Python 3.6.x

ver 1.4.6
date:

2022-03-26

base:

Reveal.js 4.3.1 (updated)

(Only update reveal.js)

ver 1.4.5
date:

2022-03-06

base:

Reveal.js 4.3.0 (updated)

(Only update reveal.js)

ver 1.4.4
date:

2021-12-12

base:

Reveal.js 4.2.1 (updated)

(Only update reveal.js)

ver 1.4.3
Date:

2021-11-20

Reveal.js:

v4.2.0

(None updates for features)

Extra

  • Update classifiers of PyPI

    • Fix key of license

    • Add other keys

ver 1.4.2
Date:

2021-11-20

Reveal.js:

v4.2.0

(None updates for features)

Extra

  • Update test matrix of GitHub Actions to confirm that this supports python 3.10

  • Update classifiers of PyPI because test cases passed under Python 3.10 and Sphinx 4.x

ver 1.4.1
Date:

2021-11-16

Reveal.js:

v4.2.0 (updated)

Fixes

  • Replace reveal.js to use right bundle version.

ver 1.4.0
Date:

2021-11-13

Reveal.js:

v4.2.0 (updated)

New features

  • Add revealjs_js_files for conf.py to set JS file. (#77)

  • revealjs_script_conf accepts dict types (#56)

Extra

  • Change test codes from nose to py.test

ver 1.3.1
date:

2021-07-17

base:

Reveal.js 4.1.3

Fixes

  • revealjs-fragments for paragraph contents (#71)

ver 1.3.0
date:

2021-07-11

base:

Reveal.js 4.1.3

New features

  • Support some attributes of sections

  • Add directive revealjs-code-block to line highlighting for reveal.js

  • Add kebab-case directives for currently snake-case directives

    • revealjs-slide <= revealjs_slie

    • revealjs-section <= revealjs_section

    • revealjs-break <= revealjs_break

    • revealjs-fragments <= revealjs_fragments

ver 1.2.1
date:

2021-06-13

base:

Reveal.js 4.1.3 (updated)

(Only update reveal.js)

ver 1.2.0
date:

2021-06-06

base:

Reveal.js 4.1.1 (updated)

New fetures

  • When builder writes contents from extensions, use same of html builder

ver 1.1.0
date:

2021-04-04

base:

Reveal.js 4.1.0

New features

  • Add option to add id attribute per sections (#59, #61)

    • Supporting label syntax of Sphinx.

Extra

  • Fix dependencies for development environment

  • Add package.json to notify updates reveal.js by dependabot

ver 1.0.1
date:

2021-01-30

base:

Reveal.js 4.1.0

Fixes

  • Change order of link tags for css files (#40, #41)

  • Rename test case function names for duplicated (#42, #54)

ver 1.0.0
date:

2021-01-03

base:

Reveal.js 4.1.0

Breaking changes

In this version, sphinx-revealjs bundle Reveal.js version 4.x, and does not supporting to work with Reveal.js 3.x.

If you want to migrate presentation source for this version, please see migration example.

New features

  • Using Revealjs 4.x (use 4.1.0)

    • With supporting multiple presentation management in single documentation

Drop

  • Bundle and implements for Revealjs 3.x

Version 0.x
ver 0.12.1
date:

2020-12-12

Fixes

  • Restrict effect of revealjs_section for only one section ( PR#36 )

ver 0.12.0
date:

2020-06-21

New features

  • Config variables:

    • revealjs_js_files

    • revealjs_css_files

    • revealjs_static_path

Updates

  • revealjs_google_fonts use Google Fonts API version 2

  • Change css selector for google-fonts

Drop

  • Remove zenburn.css from default included css files

  • Ignore html_js_files, html_css_files and html_static_path

ver 0.11.0
date:

2020-04-17

Features
  • Add new config variables revealjs_style_theme,
    revealjs_google_fonts,``revealjs_generic_font``,
    revealjs_script_files, revealjs_script_conf
    and revealjs_script_plugins
  • Breaking: Change directive option,
    from config to conf in RevealjsSlide directive.
Drop
  • Breaking: Remove config variables
    revealjs_theme and revealjs_theme_options.
Fixes

  • Use black for formatting

ver 0.10.1
date:

2020-04-09

Fixes

  • Change bundle Reveal.js (3.9.1 -> 3.9.2)

ver 0.10.0
data:

2020-03-25

Features

  • Change bundle Reveal.js (3.8.0 -> 3.9.1)

  • Add support version (3.8, author’s default)

Fixes

  • In development, depend by sphinxcontrib-gtagjs. (use in demo)

Extra

  • Change license (MIT -> Apache-2.0)

  • Use poetry as build environment

ver 0.9.0
date:

2019-12-22

Fixes

  • google-fonts default options is changed for not to render in template.

  • Adjusting templates based by sphinx basic theme. (short breaking)

    • Enable metatags , scripts and more template values.

ver 0.8.0
date:

2019-11-11

Features

  • Add new config option google_font to set google-font style.

ver 0.7.0
date:

2019-10-28

Features

  • Add new directive revealjs_fragments to use Fragment.

ver 0.6.1
date:

2019-09-12

Fixes

  • Remove tag that refer source not exits

ver 0.6.0
date:

2019-07-31

Features

  • Add new directive revealjs_break to split sections.

    • Updated demo

Extra

  • Add docstrings any sources. (ignore tests)

  • Remove Pipenv.

  • Migrate metadata and options from setup.py into setup.cfg .

  • Use bumpversion for versioning

ver 0.5.1
date:

2019-06-30

Extra

  • Update Reveal.js from 3.7.0 to 3.8.0

ver 0.5.0
date:

2018-12-31

Features

  • Revealjs initialize config accept from sphinx document config

  • Revealjs initialize config accept from revealjs_slide directive

ver 0.4.1
date:

2018-12-21

Fixes

  • revealjs_section directive of source apply for itself only

ver 0.4.0
date:

2018-12-10

Features

  • It can select theme per presentations.

ver 0.3.1

First public release on PyPI.

Licenses

This library is licensed Apache License version 2.0.

About license of directly dependencies, please see each software projects or documentations.

Indices and tables