sphinx-revealjs

Based version

1.3.0

Released

2021-07-11

Overview

What is this?

Sphinx extension to build Revealjs presentation

Features

  • Convert sections from reStructuredText directly

  • Select theme from default themes

Convert sections from reStructuredText directly

Adjust section structure

From:

Title
=====

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

    Content 1
    ^^^^^^^^^

    Content 2
    ^^^^^^^^^

To:

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

reStructuredText comments are used as speaker notes

From:

.. This is comment in reStructuredText

To:

<section>
  <aside class="notes">
    This is comment in reStructuredText
  </aside>
</section>

code-block as reveal.js code block

Directive for meta of section

Inject background color

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

Inject background image

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

Inject background video

.. revealjs-section::
    :data-background-video: https://s3.amazonaws.com/static.slid.es/site/homepage/v1/homepage-video-editor.mp4,https://s3.amazonaws.com/static.slid.es/site/homepage/v1/homepage-video-editor.webm

Inject background iframe

.. revealjs-section::
    :data-background-iframe: https://slides.com
    :data-background-interactive:

Transition settings(before)

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

Transition settings(after)

.. revealjs-section::
    :data-transition: fade

Background image transition

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

Keep title without duplicated written

First section

Keep title without duplicated written

Second section

.. revealjs-break::

Third section.

You can hide section title

.. revealjs-break::
    :notitle:

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'

Animate source code highlighting

Highlight source code per line, using the revealjs-code-block directive:

.. revealjs-code-block:: console
   :linenos:
   :data-line-numbers: 1|2|3,4

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

Support features

Fragments(reveal.js)

This is support fragment with groups.

.. revealjs-fragments::

   * First
   * Second
   * Third
  • First

  • Second

  • Third

Plugins(reveal.js)

bundled plugins can use just write conf.py

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

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

Math

Supporting math renderer from sphinx.

Example to use sphinx.ext.mathjax (recommended)

.. math::

    \begin{aligned}
      \dot{x} & = \sigma(y-x) \\
      \dot{y} & = \rho x - y - xz \\
      \dot{z} & = -\beta z + xy
    \end{aligned}
\[\begin{split}\begin{aligned} \dot{x} & = \sigma(y-x) \\ \dot{y} & = \rho x - y - xz \\ \dot{z} & = -\beta z + xy \end{aligned}\end{split}\]

Math

You can use math plugin of Reveal.js

Source:

revealjs-script_plugins = [
    {
        "name": "RevealMath",
        "src": "revealjs4/plugin/math/math.js",
    }
]
.. raw:: html

    \[\begin{aligned}
    \dot{x} &amp; = \sigma(y-x) \\
    \dot{y} &amp; = \rho x - y - xz \\
    \dot{z} &amp; = -\beta z + xy
    \end{aligned} \]

Math

You can use math plugin of Reveal.js

Output:

\[\begin{aligned} \dot{x} & = \sigma(y-x) \\ \dot{y} & = \rho x - y - xz \\ \dot{z} & = -\beta z + xy \end{aligned} \]

Use other sphinx extensions

You can use other extensions to render html.

Todo

This is example todo by sphinx.ext.todo . render at presentation.

Usage

Installation

You can install from PyPI.

$ pip install sphinx-revealjs

Configure

Edit conf.py to use this extension

extensions = [
    "sphinx_revealjs",
]

Write source

Write plain reStructuredText

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

Agenda
------

* Author
* Feature


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

Own self promotion

Content
=======

Build

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.

Other examples

Within this pages

Enjoy writing reST as presentation

Please star!

Star