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¶

Source: Sphinx document
Created: Reveal.js presentation

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.9
Sphinx: 3.5.4

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

Upgrading guide¶

To 1.x from 0.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.

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

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.

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": "revealjs/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>

Font configurations¶

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_section::¶: Alias of revealjs-section for backward compatibility.

.. 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.

.. revealjs_break::¶: Alias of revealjs-breaK For backward compatibility.

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_fragments::¶: Alias of revealjs-fragments for backward compatibility.

Changelog¶

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

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.

docutils:
- https://docutils.sourceforge.io/
Sphinx:
- https://www.sphinx-doc.org/
- https://github.com/sphinx-doc/sphinx
Reveal.js:
- https://revealjs.com/#/
- https://github.com/hakimel/reveal.js