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.7+ and Sphinx 4.0+.

Current development environment ¶

Python: 3.11.x
Sphinx: 5.3.0

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

You can generate all pages as index.html to use dirrevealjs .

make dirrevealjs

Upgrading guide ¶

Upgrading from 2.x to 3.x ¶

From 2.x, some features are removed because splitted other extensions or duplicated behaviors. If you want to use new version by documentation using 2.x, you should upgrade project files.

Supported dependencies version ¶

This explicits versions of some dependencies. If you are using old version libraries, must update environment. 1

Runtime/Library	Requirement
Python	3.7 or newer
Sphinx core	4.0 or newer

Change bundled revealjs path ¶

sphinx-revealjs is using Revealjs v5.x(new major version) at version 2.9.0.

If you use path of bundled revealjs directly in other place, you need to change path.

Before	After
`revealjs4`	`revealjs`

You can use get_revealjs_path .

Change writing structure ¶

Todo

Ref to builder document

All slides are “vertical-slides” format ¶

Does not generate `section` element for level-4 sections ¶

Footnotes

1: This is defined as package metadata on pyproject.toml . If your environment does not meet requirements, you cannot install.

Upgrading from 1.x to 2.x ¶

From 2.x, some features are removed because splitted other extensions or duplicated behaviors. If you want to use new version by documentation using 1.x, you should upgrade project files.

Fonts ¶

sphinx-revealjs does not support font configuration features to provide features as “Presentation tools”.

If you want to use Google Fonts ¶

You can add CSS URL into revealjs_css_files directly.

                  revealjs_css_files = [
    "https://fonts.googleapis.com/css2?family=Noto+Sans+JP",
    "css/custom.css",
]

                 

Example of css/custom.css .

                  .reveal *, .reveal h1, .reveal h2, .reveal h3, .reveal h4, .reveal h5, .reveal h6 {
    font-family: 'Noto Sans JP', sans-serif;
}

                 

Use googlefonts-markup ¶

If you want to write only font-family, use googlefonts-markup .

                  from googlefonts_markup import Font

revealjs_css_files = [
    Font(family_name="Noto Sans JP").css_url(),
    "css/custom.css",
]

                 

Change using Google Fonts per presentations ¶

You need to create custom theme per presentations.

                  # Define default theme
revealjs_style_theme = "black"

                  =====
Title
=====

.. Set `revealjs-slide/theme` to override theme

.. revealjs-slide::
   :theme: "css/theme-for-this-presentation.css"

                 

Speaker Views ¶

New configration revealjs_notes_from_comments are defined. But, because default values is False , your presentation not write speaker-note when you upgrade sphinx-revealjs

Replace reveajs-notes(recommended) ¶

You can replace revealjs-notes from comment-block. And you can use comment-block as COMMENT(does not write as content from source).

Before:

.. This is 1.x style speaker-view content

After:

                  .. revealjs-notes::

   This is 1.x style speaker-view content

Configuration for compatible behaviors ¶

You can set True revealjs_notes_from_comments to use behaviors of ver 1.x.

                  revealjs_notes_from_comments = Ture

                 

Configurations ¶

html_js_files/revealjs_js_files ¶

sphinx-revealjs does not ref html_js_files as list of additional JavaScript files. It refer only revealjs_js_files .

You must do one of these.

Copy needy values of html_js_files to revealjs_js_files
Sync html_js_files to revealjs_js_files (ex: revealjs_js_files = html_js_files )

revealjs_use_index ¶

sphinx-revealjs does not generate genindex.html (list of in vals) on default. If you want genindex.html for Reveal.js builder, you muse set True .

Directives ¶

sphinx-revealjs defines kebab-cased directives only, and removed snake-cesed directives. You must replace cases to run by 2.x.

Before	After
`revealjs_break`	`revealjs-break`
`revealjs_fragments`	`revealjs-fragments`
`revealjs_section`	`revealjs-section`
`revealjs_slide`	`revealjs-slide`

Upgrading from 0.x to 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.

Configurations ¶

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.

revealjs_use_index ¶

Type: bool
Default: False

Flag that does builder generate genindex.html (same as html_use_index ).

revealjs_html_theme ¶

Type: str
Default: revealjs-basic
Example: revealjs-simple

Using HTML Theme for output contents. It can set any html theme, but it should set theme made for revealjs.

Bundled themes are:

revealjs-basic : Inherit style from basic html theme.
revealjs-simple : Minimal defined style.

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.

Note

For behavior compatibility, it appends {"scrollActivationWidth": None} as default configuration when value is dict object or is not set.

See it: https://github.com/hakimel/reveal.js/releases/tag/5.0.0

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", "scrollActivationWidth": null}'));
  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>

                

revealjs_notes_from_comments ¶

Type: boolean
Default: False

If this is set True , builder writes notes section from comment block.

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.

Warning

This option is not work in v2.x. It will removed in v3.x

: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 any data- attributes included options of section element for Reveal.js 1 . For more information, please see Reveal.js documentation .

Note

This may be not completed all attributes for Reveal.js. If you find missing attribute, pleas post issues or pull-requests into GitHub.

Usage:

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

                 Title
=====

Section
-------

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

                

.. 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-vertical:: ¶

To change behavior of sections rendered vertical (called as vertical slides 2 ).

:data-XXX: ¶: It accepts attributes as same as revealjs-section . There are affected on all slides vertical from declared section.

Usage:

Write revealjs-vertical to point of want to split section (second level).

                 Title
=====

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

For interactive contents ¶

.. revealjs-code-block:: ¶

This is extends of code-block direcrive for presentation.

If you want to use custom 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")

:data-ln-start-from: (integer) ¶: Set number of first-line in code block. When this is assigned, display line numbers even if data-line-numbers is not set.

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

   print(datetime.datetime.now())

Please see `Reveal.js document <https://revealjs.com/code/#line-number-offset-4.2.0>`_.

.. revealjs-literalinclude:: ¶

This is extends of literalinclude direcrive for presentation.

If you want to use custom attributes in literalinclude.

External attributes are same from revealjs-code-block .

.. revealjs-fragments:: ¶

Note

There are cases not working regular.

Inject fragment attribute into objects. Referer to “Fragments” from Reveal.js

You can see demo to know usage.

:custom-effect: (string) ¶: When it is set, inject as custom class. You can customize behavior of fragments transitions with CSS.

Example:

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

                 .. revealjs-fragments::

   * First
   * Second
   * Third

.. revealjs-notes:: ¶

When you write this section, inner text are as content of Speaker View .

If you write some directives on same-level, Reveal.js uses first direcrive only.

Note

You must be careful for comment block when you set revealjs_notes_from_comments in conf.py . Reveal.js recoginzes first <aside> element as content of speaker-view, so you may not see directive content as notes.

Example:

                 .. revealjs-notes::

   This content output into <aside> element on <section>.

Footnotes

1: Reveal.js plugins use data- attributes often to customize behavior.
2: Pleas see Reveal.js document to know about this.

Optional extensions ¶

sphinx-revealjs includes optional extensions. These are not core features for presentation, but supporting features to get for more values.

Why these are optional ? ¶

These require extra packages to work, but them do not need for standard features. However, required packages are large (example: playwright is 27MB to only create screenshot).

Therefore, I splitted core features and optional features as “package extra”.

Usage ¶

With install sphinx-revealjs , append extras by [] .

pip install 'sphinx-revealjs[OPT1]'

You can install multiple extras with comma.

pip install 'sphinx-revealjs[OPT1,OPT2]'

Edit conf.py to work extensions.

For details, please see extension’s page.

Features ¶

sphinx_revealjs.ext.footnotes ¶

Added: v2.8.0

Overview ¶

This extension updates position of footnotes.

Installation ¶

You need not install extra, you can use it immediately after installing sphinx-revealjs .

Usage ¶

WHen adding extension into your conf.py , insert CSS file to customize layout of footnotes.

Example ¶

conf.py ¶

                    extensions = [
    "sphinx_revealjs",
    "sphinx_revealjs.ext.footnotes",
]

                   

sample-slide.rst ¶

                    Sample title
============

This sentence has footnotes [#f1]_

.. [#f1] This is footnote.

Configuration ¶

All Configuration names are prefixed revealjs_footnotes_ .

revealjs_footnotes_font_size ¶

Type: str
Default: 50%
Example: 60%

Font-size of rendered footnote contents.

revealjs_footnotes_ref_font_size ¶

Type: str
Default: 70%
Example: 60%

Font-size of rendered footnote’s referer text.

sphinx_revealjs.ext.screenshot ¶

Added: v2.5.0

Overview ¶

Generate screenshot first section of presentations by Playwright. Screenshots can use as OGP Image contents.

Note

This extension generates screenshots only when your running builder is revealjs or dirrevealjs . Even if you run other builder with this in extensions, any screenshot are not generated.

Installation ¶

This extension need Playwright and browser component.

                  pip install 'sphinx-revealjs[screenshot]'
playwright install

Usage ¶

When addning extention into your conf.py , this generates screenshots per pages. You can set image path into :og:image: field of sphinxext-opengraph in advance.

Example ¶

conf.py ¶

                    extensions = [
    "sphinx_revealjs",
    "sphinx_revealjs.ext.screenshot",
    "sphinxext.opengraph",
]

                   

sample-slide.rst ¶

                    :og:image: ./_images/ogp/sample-slide.png

Sample title
============

Configuration ¶

All Configuration names are prefixed revealjs_screenshot_ .

revealjs_screenshot_outdir ¶

Type: str
Default: "_images/ogp"
Example: "_static/images"

Output directory for generated screenshots. This must be releative path for outdir of Sphinx.

revealjs_screenshot_excludes ¶

Type: List[str]
Default: [] (empty)
Example: ["index"]

List of docnames to exclude for target of screenshots. Valuese must be docname format that does not need extension of files.

Works ¶

After build all documents, launch headless-browser by Playwright.

Browser captures screenshots any document pages for these rule.

Targets are generating files. If it runs incremental build and document is not changed, document is not target.
If docname contains are revealjs_screenshot_excludes , document is not target.

When browser capture screenshots, this sets image size from Reveal config (with and height). This values are used viewport of presentation.

If you want to change all sizes, you can set revealjs_script_conf .
If you want to change per docs, you can set revealjs-slide directive.

Note ¶

Currently, I reccomend using sphinxext-opengraph to add ogp metatags (it is useful). I delegate behavior about opengraph, and sphinx-revealjs does not have feature to generate ogp tags.

Using tips ¶

Create custom theme ¶

Added: v2.1.0
Updated: v3.0.0

sphinx-revealjs includes SCSS sources of bundled themes. You can write custom theme from theme template of reveal.js using libsass .

Example 1: Using libsass ¶

First, install libsass to compile SASS/SCSS on your environment.

pip install libsass

Write SCSS source for your theme.

                 // Use teamplate sources from Reveal.js
@import "template/mixins";
@import "template/settings";

// Write your settings
$base03: #002b36;

// ...


@import "template/theme";

// You can write custom style too.
.reveal {
  h1, h2, h3 {
    text-transform: none;
  }
}

                

Compile source.

                 from pathlib import Path

import sass
from sphinx_revealjs.utils import get_revealjs_path

source = Path("_sass/custom.scss").read_text()
css = sass.compile(
    string=source,
    include_paths=[str(get_revealjs_path() / "css/theme")]
)
Path("_static/custom.css").write_text(css)

                

Use compiled CSS as your theme.

                 # conf.py
# If option has extension, find from static files.
revealjs_style_theme = "custom.css"
revealjs_static_path = ["_static"]

                

Example 2: sphinxcontrib-sass ¶

You can use sphinxcontrib-sass to simplify.

                 pip install --find-links=https://github.com/attakei-lab/sphinxcontrib-sass/releases sphinxcontrib-sass

                

                 # conf.py
from sphinx_revealjs.utils import get_revealjs_path

extensions = [
    # .. Your extensions
    # Add
    "sphinxcontrib.sass",
]

sass_src_dir = "_sass"
sass_out_dir = "_static"
sass_targets = {"custom.scss": "custom.css"}
sass_include_paths = [
    get_revealjs_path() / "css" / "theme",
]

                

When document updated, it compile scss to css.

Customizing design simply ¶

When using bundled theme, you can customze design by adding custom CSS.

Example: Disable transform style in header text ¶

Some of reveal.js bundled themes (ex: black ) set uppercase in text-transform of heading texts. You can add extra custom CSS to use other settings.

Source ¶

conf.py ¶

                   revealjs_css_files = [
    "revealjs/plugin/highlight/zenburn.css",
    "custom.css",
]

                  

custom.css ¶

                   .reveal h1, .reveal h2, .reveal h3, .reveal h4, .reveal h5, .reveal h6 {
   text-transform: none;
}

                  

Contributing ¶

Thank you for interested to sphinx-revealjs .

Todo

Add USING, QUESTION and DOCUMENTATION

Conttribute code ¶

Local development environment ¶

This is spec for development by author( attakei ) on 2022/08/27.

Arch Linux
Python 3.10.x
Installed pre-commit globally

Setting up repo ¶

After you clone forked Git repository, run commands to set up.

                python tools/fetch_revealjs.py
pre-commit install
python -m venv venv
venv/bin/pip install -e '.[test]'

               

Changelog ¶

ver 3.0.1 ¶

Release date: 2024-04-14 (JST)
Reveal.js version: 5.1.0 (updated)

(None updates for features)

ver 3.0.0 ¶

Release date: 2024-02-27
Reveal.js version: 5.0.5 (updated)

Breaking changes ¶

Dropped old Python and Sphinx versions.
Change path of bundled revealjs path.
The builder outputs everything in the “vertical slide” format.
Builder does not generate section element for level-4 sections.

Features ¶

Add new directive revealjs-vertical .
Section directives accepts any data- attributes. ( revealjs-section , revealjs-break and revealjs-vertical )
Add wrapper function to get bundled revealjs path.
Add new html-theme revealjs-simple that render minimum style reveal.js (Default theme is named revealjs-basic )

Fixes ¶

revealjs-break splits pages in vertical slides when it is added to top of section.

Old versions ¶

Version 2.x ¶

ver 2.9.3 ¶

date: 2024-01-13 JST
base: Reveal.js 5.0.4 (updated)

(None updates for features)

ver 2.9.2 ¶

date: 2023-12-03 JST
base: Reveal.js 5.0.2

Fixes ¶

Output script config from json.dumps() without JSON.parse in <script> .

ver 2.9.1 ¶

date: 2023-11-25 JST
base: Reveal.js 5.0.2

Miscellaneous ¶

Mark deprecated into google_font in revealjs-slide directive.

ver 2.9.0 ¶

date: 2023-11-19 JST
base: Reveal.js 5.0.2 (updated)

Note

This is for last minor update for v2.x

Features ¶

Set default configuration to disable scroll-view mode for compatiblity.

Miscellaneous ¶

Update translations.
Add logging for deprecated.

ver 2.8.0 ¶

date: 2023-10-29 JST
base: Reveal.js 4.6.1

Features ¶

Add custom event “revealjs:ready-for-writing” (internal)
Add optional extension sphinx_revealjs.ext.footnotes . See doc for detail.

Miscellaneous ¶

Checked works on Python 3.12
Use MyPy for type check

ver 2.7.1 ¶

date: 2023-09-29 JST
base: Reveal.js 4.6.1

Miscellaneous ¶

Lock Sphinx version for documentation

ver 2.7.0 ¶

date: 2023-09-29 JST
base: Reveal.js 4.6.1 (updated)

(None updates for features)

ver 2.6.0 ¶

date: 2023-04-30 JST
base: Reveal.js 4.5.0 (updated)

Features ¶

Support custom fragments of Reveal.js 4.5.0 or greater.
- Include demo updating.

Miscellaneous ¶

Checked Sphinx 7.x compatiblity.

ver 2.5.1 ¶

date: 2023-01-07
base: Reveal.js 4.4.0

Fixes ¶

sphinx_revealjs.ext.screenshot works only revealjs based builders.

Miscellaneous ¶

Update demo
- Use sphinx_revealjs.ext.screenshot and sphinxext-opengraph
- Change structure for i18n

ver 2.5.0 ¶

date: 2022-12-18
base: Reveal.js 4.4.0

Features ¶

Add optional extension sphinx_revealjs.ext.screenshot . See doc for detail.

Miscellaneous ¶

Extract only target files from archive of Reveal.js.
- Contain files are not changed
- It is for CVE-2007-4559

ver 2.4.1 ¶

date: 2022-11-20
base: Reveal.js 4.4.0

(None updates for features)

Extra ¶

Fix badge of readme

ver 2.4.0 ¶

date: 2022-11-13
base: Reveal.js 4.4.0

Added features ¶

Add data-ln-start-from into revealjs-code-block and revealjs-literalinclude .

Changes ¶

Demo documentation are changed from demo/revealjs4 to demo .

Deprecated ¶

Output warning when using it by Python 3.6
Mark notice level deprecated
- Change directory for contents of Reveal.js

Change supportings ¶

Add Python 3.11 into supportings
Drop Python 3.6 from supportings

Develoment environment ¶

Hooks of pre-commit are using as standard lintings. In GitHub Actions, lint is running pre-commit .
Use Flit as building library instead of Poetry.

ver 2.3.0 ¶

date: 2022-10-23
base: Reveal.js 4.4.0 (updated)

Updated Features ¶

Support data-background-gradient correctly (already defined, but not working at older Reveal.js)

ver 2.2.0 ¶

date: 2022-10-01
base: Reveal.js 4.3.1

Added features ¶

Add revealjs-literalinclude that is extends of literalinclude for data-line-numbers . It is likely revealjs-code-block .

ver 2.1.0 ¶

date: 2022-08-28
base: Reveal.js 4.3.1

Added Features ¶

Package includes SCSS sources of revealjs bundled-themes

Extra ¶

Use pre-commit

ver 2.0.1 ¶

date: 2022-08-02
base: Reveal.js 4.3.1

Fixes ¶

Custom builders accept app and env (optional) in initialize function

ver 2.0.0 ¶

date: 2022-05-31
base: Reveal.js 4.3.1

Added Features ¶

Directive revealjs-notes writes speaker-view content into presentation
Config reveajs_notes_from_comments toggle if it creates speaker-view content from comment-block
- BREAKING CHANGE: Default value is False. You must set True explicitly to use as same as ver 1.x
Config reveajs_use_index toggle if it creates genindex.html
- BREAKING CHANGE: Default value is False. You must set True explicitly to use as same as ver 1.x

Fixes ¶

Register data-XXX attributes into revealjs-section and revealjs-break from https://revealjs.com/

Deleted feaures ¶

Remove snake-cesed directives
Does not generate search.html

Version 1.x ¶

ver 1.5.3 ¶

date: 2022-06-02
base: Reveal.js 4.3.1

Fixes ¶

All nodes for sphinx-revealjs does not write anything when none revealjs builder works.

ver 1.5.2 ¶

date: 2022-04-29
base: Reveal.js 4.3.1

Fixes ¶

Work revealjs-break directive in dirrevealjs builder (#109)
Inherit behavior of any nodes from html builder to dirrevealjs builder (#108)

Deprecated ¶

Mark as deprecated(logging.warning) to drop at version 2.x (updated from v1.5.0)

Snake-cased directive ( revealjs_slide , revealjs_section and revealjs_break )
CSS Font configurations ( revealjs_google_fonts and revealjs_generic_font )
Passing values from html_js_files to revealjs_js_files

ver 1.5.1 ¶

date: 2022-04-21
base: Reveal.js 4.3.1

Fixes ¶

Add role="main" into page.html for searching by Sphinx (#102)

Misc ¶

Add documentation link into metadata (PyPI)

ver 1.5.0 ¶

date: 2022-04-11
base: Reveal.js 4.3.1

Features ¶

Add dirrevealjs builder to generate all pages as index.html

Deprecated ¶

Mark as deprecated(logging.info) to drop at version 2.x

Snake-cased directive ( revealjs_slide , revealjs_section and revealjs_break )
CSS Font configurations ( revealjs_google_fonts and revealjs_generic_font )
Passing values from html_js_files to revealjs_js_files
Full-support for Python 3.6.x

ver 1.4.6 ¶

date: 2022-03-26
base: Reveal.js 4.3.1 (updated)

(Only update reveal.js)

ver 1.4.5 ¶

date: 2022-03-06
base: Reveal.js 4.3.0 (updated)

(Only update reveal.js)

ver 1.4.4 ¶

date: 2021-12-12
base: Reveal.js 4.2.1 (updated)

(Only update reveal.js)

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

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

Versioning policy ¶

date: 2022-11-06

Note

This is possibility to change without announces.

Base rules ¶

sphinx-revealjs releases based from Semantic Versioning 2.0.0 .

Update major version with:
- Drop or changed configuration variables
- Have big changes of generated contents by new Reveal.js
- Breaking changes for setup-level requirements
Update minor version with:
- Update marks for deprecated (wraning level)
- Add new features (include inner extensions)
- Add supporing dependencies
- Drop supporing dependencies (not change setup-level)
- Change major version of Reveal.js, but it need not update as major version
- Change minor version of Reveal.js
- Change compononents by misc reasons
Update patch version with:
- Mark deprecated notice
- Fixed bugs
- Change patch version of Reveal.js

Following dependencies ¶

CPython ¶

sphinx-revealjs supports only “Living” versions for as of first of year.

“Living” means that it have not published last security-only releases. “Not living” means that it is finished to published security-only releases.

Wnen some version of CPython released “last security-only release”, sphinx-revealjs will release with marks deprecated notice-level at upcoming (patch version).
When sphinx-revealjs releases new minor version after 2 month from version with marked deprecated notice, this will drop old versions from everywhere and depricated warning (minor versoin).
If sphinx-revealjs must only use specify version, this will set python_requires and release new versoin (major or minor version).

Sphinx ¶

(TBD)

Reveal.js ¶

sphinx-revealjs bundles stable version.

When Reveal.js is released as patch version, sphinx-revealjs bundles new version and releases as patch version at upcoming.
When Reveal.js is released as minor version, sphinx-revealjs bundles new version and releases as minor version at upcoming. It is possibility to include adding options for new version.
When Reveal.js is released as major version, I will check compatibility for configuration of extension.

If I have decise to need breaking change, sphinx-revealjs will release as major version.

if it need not change or only add configuration, sphinx-revealjs will release as minor versoin. sphinx-revealjs bundles new version and releases as patch version at upcoming.

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

sphinx-revealjs ¶

Basic Features ¶

Demo ¶

Concept and motivation ¶

Contents ¶

Setup ¶

Requirements ¶

Current development environment ¶

Installation ¶

Configuration ¶

Build ¶

Upgrading guide ¶

Upgrading from 2.x to 3.x ¶

Supported dependencies version ¶

Change bundled revealjs path ¶

Change writing structure ¶

All slides are “vertical-slides” format ¶

Does not generate section element for level-4 sections ¶

Upgrading from 1.x to 2.x ¶

Fonts ¶

If you want to use Google Fonts ¶

Use googlefonts-markup ¶

Change using Google Fonts per presentations ¶

Speaker Views ¶

Replace reveajs-notes(recommended) ¶

Configuration for compatible behaviors ¶

Configurations ¶

html_js_files/revealjs_js_files ¶

revealjs_use_index ¶

Directives ¶

Upgrading from 0.x to 1.x ¶

Configurations ¶

revealjs_script_plugins ¶

revealjs_css_files ¶

Configurations ¶

Basic configurations ¶

Style Configurations ¶

Presentation Configurations ¶

Directives ¶

For customize presentation ¶

For customize sections ¶

For interactive contents ¶

Optional extensions ¶

Why these are optional ? ¶

Usage ¶

Features ¶

sphinx_revealjs.ext.footnotes ¶

Overview ¶

Installation ¶

Usage ¶

Configuration ¶

sphinx_revealjs.ext.screenshot ¶

Overview ¶

Installation ¶

Usage ¶

Configuration ¶

Works ¶

Note ¶

Using tips ¶

Create custom theme ¶

Example 1: Using libsass ¶

Example 2: sphinxcontrib-sass ¶

Customizing design simply ¶

Example: Disable transform style in header text ¶

Source ¶

Contributing ¶

Conttribute code ¶

Local development environment ¶

Setting up repo ¶

Changelog ¶

ver 3.0.1 ¶

ver 3.0.0 ¶

Breaking changes ¶

Features ¶

Fixes ¶

Old versions ¶

Version 2.x ¶

ver 2.9.3 ¶

ver 2.9.2 ¶

ver 2.9.1 ¶

Does not generate `section` element for level-4 sections ¶