Introduction of sphinx-revealjs

Based version:

3.2.0

Demo updated:

2024-10-18 JST

Overview

What is this?

Sphinx extension to build Reveal.js presentation

Features

• Convert sections from reStructuredText directly

• Support customize sections

• Support using plugins

• Support Sphinx extensions

• Select theme from default themes

Standard usage

Installation

You can install stable version of sphinx-revealjs from PyPI.

pip install sphinx-revealjs

Set up

Edit conf.py to use this extension.

extensions = [
    "sphinx_revealjs",
]

You can customize behavior. Please see documentation.

Write source

Write plain reStructuredText.

My Reveal.js presentation
=========================

Agenda
------

* Author
* Feature

Author: Who am I
================

Own self promotion

Content
=======

Build presentation

This extension has custom builder name revealjs. If you make docs as Reveal.js presentation, you call make revealjs.

make revealjs

This presentation is made from source.

Footnotes

You can set footnotes. footnotes are rendered on tail of slide by using internal-extension. [1]

Convert reStructuredText to Reveal.js

reST structure to Reveal.js sections

Title
=====

First section
-------------

Content 1
^^^^^^^^^

Content 2
^^^^^^^^^

<section>
    <section>
        <h1>Title</h1>
    </section>
</section>
<section>
    <section>
        <h2>First section</h2>
    </section>
    <section>
        <h3>Content 1</h3>
    </section>
    <section>
        <h3>Content 2</h3>
    </section>
</section>

Using built-in directives

Sub section
-----------

Content
^^^^^^^

.. image:: ./your-image.png

<section>
  <section>
     <h2>First section</h2>
  </section>
  <section>
     <h3>Content 1</h3>
     <img src="_images/your-image.png">
  </section>
</section>

Using custom directives of Sphinx extensions

.. oembed:: \
https://twitter.com/attakei/status/1517152841550376961

Comments of reST

Title
=====

First section
-------------

.. This is comment

<section>
  <h1>Title</h1>
</section>
<section>
  <section>
    <h2>First section</h2>
  </section>
</section>

Comments of reST are not written into output files by default settings.

Customize section behavior

Description

sphinx-revealjs provides custom directives to customize behavior of sections.

• revealjs-section

• revealjs-break

• ( revealjs-vertical )

Showing part of examples.

Change background color

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

Change background color

.. revealjs-section::
   :data-background-gradient: linear-gradient(to bottom, #283b95, #17b2c3)

Set background image

.. revealjs-section::
   :data-background-image: _static/icon-attakei.jpg
   :data-background-size: contain

Change transition(before)

.. revealjs-section::
   :data-transition: none

Change transition(after)

.. revealjs-section::
   :data-transition: concave

Non-title section

First

Keep title without duplicated written
-------------------------------------

First

.. revealjs-break::
   :notitle:

Second

Second

Keep title without duplicated written
-------------------------------------

First

.. revealjs-break::
   :notitle:

Second

Customse all slide of one vertical items

If you want to change behaivor of all slides on vertical slides (level 2 section), set revealjs-vertical.

.. Changing background-color of vertical slides (items scrolled bottom)

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

Interactive content

Description

sphinx-revealjs provides directives to show some interactive contents.

• revealjs-section

• revealjs-break

• revealjs-fragments

Showing part of examples.

Animate source code transitions

Enable animations for each revealjs-section and revealjs-break:

echo 'First part of my command'

Animate source code transitions

Enable animations for each revealjs-section and revealjs-break:

echo 'First part of my command'
echo 'Second part of my command'

Fragments

This is support fragment with groups.

.. revealjs-fragments::

   * First
   * Second
   * Third

• First

• Second

• Third

Fragments

You can customize behavior of fragments.

.. revealjs-fragments::
   :custom-effect: blur

   * First
   * Second
   * Third

// For custom effect of fragments
.fragment.blur {
  filter: blur(5px);
}
.fragment.blur.visible {
  filter: none;
}

Fragments

You can customize behavior of fragments.

.. revealjs-fragments::
   :custom-effect: blur

   * First
   * Second
   * Third

• First

• Second

• Third

Fragments

Using container directive, you can work stack layouting.

.. container:: r-stack

   .. revealjs-fragments::

      .. image:: https://picsum.photos/450/300

      .. image:: https://picsum.photos/300/450

      .. image:: https://picsum.photos/400/400

Fragments

Using container directive, you can work stack layouting.

Using Reveal.js plugins

Description

sphinx-revealjs can use Reveal.js plugins by revealjs_script_plugins in conf.py

revealjs_script_plugins = [
    {
        "name": "RevealMath",
        "src": "revealjs/plugin/math/math.js",
    },
]

Code highlighting

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

These codes are highlighting by RevealHighlight plugin.

Code highlighting

.. code-block:: python

   print("hello world")

You can use code-block and literalinclude for code highlighting.

Code highlighting

.. revealjs-code-block:: rst
   :data-line-numbers: 1|2

   print("hello world")

Using revealjs-code-block, line-level highlighting works.

Code highlighting

html_theme = "alabaster"
html_static_path = ["_static"]

# -- Options for Reveal.js output ---------------------------------------------
revealjs_html_theme = "revealjs-simple"
revealjs_static_path = ["_static"]
revealjs_style_theme = "custom.css"
revealjs_script_conf = {
    "controls": True,
    "progress": True,
    "hash": True,
    "center": True,
    "transition": "slide",
    "customcontrols": {

You can include other file with step-by-step highlighting by revealjs-literalinclude.

Code highlighting

.. revealjs-code-block:: python
   :data-ln-start-from: 47

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

You can use data-ln-start-from for display line numbers from specify value.

Code highlighting

# -- Options for Reveal.js output ---------------------------------------------
revealjs_html_theme = "revealjs-simple"
revealjs_static_path = ["_static"]
revealjs_style_theme = "custom.css"
revealjs_script_conf = {
    "controls": True,
    "progress": True,
    "hash": True,
    "center": True,
    "transition": "slide",
    "customcontrols": {
        "controls": [
            {

revealjs-literalinclude can use it too.

Speaker notes

revealjs_script_plugins = [
    {
        "name": "RevealNotes",
        "src": "revealjs/plugin/notes/notes.js",
    },
]

This is used RevealNotes plugin, Please press S key to try it!

Speaker notes

.. revealjs-notes::

   In this section, showing message from notes.

Enjoy writing reST as presentation

Please star!