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

Contents

Setup

Requirements

sphinx-revealjs requires Python 3.6+ and Sphinx.

Current development environment

  • Python: 3.8

  • 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

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_script_files
Type

List[str]

Optional

Default

["revealjs/js/reveal.js"]

Example

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

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

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

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 direcvite can accept attribute as same as Reveal.js section tags.

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

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 plesentation by this library.

Liceses

This library is licensed Apache License verion 2.0.

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

Indices and tables