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

Important changes

1.2.x => 1.3

Support kebab-case name for all directives. You can use revealjs-section instead of revealjs_section. I am planning to remove snake-case directives, but not soon (least, keeping until version 2.x).

In document and demo, use kebab-case directive.

0.x => 1.x

In update from 0.x to 1.x, it has breaking changes. See Migration guide.

Demo

• Source: Sphinx document

• Created: Reveal.js presentation

Contents

Setup

Requirements

sphinx-revealjs requires Python 3.6+ and Sphinx.

Current development environment

• Python: 3.9

• Sphinx: 2.4.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

Migration guide

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

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.

Style Configurations

revealjs_static_path

Type

list

Optional

Default

[] (empty)

Example

["_static"]

List of static files directory ( same as html_static_path )

revealjs_css_files

Type

list

Optional

Default

[] (empty)

Example

["custom.css"]

List of using custom css (same of html_css_files ).

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

revealjs_style_theme

Type

str

Optional

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

revealjs_google_fonts

Type

dict

Optional

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

Optional

Default

sans-serif

Example

serif, monospace

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

Presentation Configurations

revealjs_use_section_ids

Type

boolean

Optional

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]

Optional

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

Optional

Default

None

Raw JavaScript code for configuration of Reveal.js.

If this value is set, render script tag after source script tags.

Example:

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>

revealjs_script_plugins

Type

List[Dict]

Optional

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",
    "options: """
      {async: true, callback: function() { hljs.initHighlightingOnLoad(); } }
    """,
]

<!-- For revealjs 3.x -->
<div>
  <!-- Presentation body -->
</div>
<script src="_static/revealjs/js/revealjs.js"></script>
<!-- here!! -->
<script>
  let revealjsConfig = {};
  plugin_0 = {async: true, callback: function() { hljs.initHighlightingOnLoad(); } };
  plugin_0.src = "_static/revealjs/plugin/highlight/highlight.js"
  revealjsConfig.dependencies.push(plugin_0);
  revealjs.initialize(revealjsConfig);
</script>

<!-- For revealjs 4.x -->
<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>

Customize slide from document

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

If you want to configure one presentation from some, write revealjs-slide directive into reST document.

Directive usage

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

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

.. revealjs-slide::
    :theme: moon

Section
-------

Content

Directive attributes

Note

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

theme

Override revealjs_style_theme.

google_font

Override revealjs_google_fonts, but it can specify only one.

conf

Override revealjs_script_conf, but single line only.

Customize sections

To change behavior of sections, sphinx-revealjs provide some directives.

revealjs-section / revealjs_section

To change behavior per section, write directive per section.

Usage

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

Title
=====

Section
-------

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

Attributes

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

revealjs-break / 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)

Attributes

It accepts attributes as same as revealjs-section.

And it accepts notitle as unique feature.

notitle

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

Content directives

sphinx-revealjs provides features for contents of section.

revealjs-code-block

This is extends of code-block direcrive for presentation.

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

Usage

Set it instead of code-block.

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

   def hello():
       print("world")

Reference

• https://revealjs.com/code/#line-numbers-%26-highlights

revealjs-frabments / revealjs_fragments

Note

There are cases not working regular.

Inject fragment attribute into objects.

Usage

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

.. revealjs-fragments::

    * First
    * Second
    * Third

See demo

Reference

• https://github.com/hakimel/reveal.js/#fragments

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.

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

Indices and tables

• Index

• Module Index

• Search Page