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 chromium

Usage

When adding extension 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 relative path for outdir of Sphinx.

revealjs_screenshot_excludes

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

List of docnames to exclude for target of screenshots. Values 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 recommend 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.