Metadata-Version: 2.4
Name: mkdocs-revealjs
Version: 0.11.1
Summary: MkDocs plugin to embed Reveal.js presentations with Markdown syntax
Author-email: "Rod2ik, aka Rodrigo Schwencke" <rod2ik.dev@gmail.com>
License: GPL-3.0-or-later
Project-URL: Homepage, https://rod2ik.gitlab.io/mkdocs-revealjs/
Project-URL: Documentation, https://rod2ik.gitlab.io/mkdocs-revealjs/
Project-URL: Repository, https://gitlab.com/rod2ik/mkdocs-revealjs
Project-URL: Issues, https://gitlab.com/rod2ik/mkdocs-revealjs/-/issues
Keywords: mkdocs,revealjs,presentation,slides,markdown,education,teaching,teachers
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: MkDocs
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Education
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs<2.0,>=1.4
Requires-Dist: Markdown>=3.4
Requires-Dist: PyYAML>=6.0
Provides-Extra: macros
Requires-Dist: mkdocs-macros-plugin>=1.1.2; extra == "macros"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mkdocs-material<10,>=9; extra == "dev"
Requires-Dist: mkdocs-superquiz>=0.5.8; extra == "dev"
Requires-Dist: mkdocs-macros-plugin>=1.1.2; extra == "dev"
Requires-Dist: pytest<9,>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# mkdocs-revealjs

> Embed one or more Reveal.js presentations directly inside MkDocs Markdown pages, with light/dark theme synchronization and native integration with other MkDocs plugins.

[![PyPI](https://img.shields.io/pypi/v/mkdocs-revealjs)](https://pypi.org/project/mkdocs-revealjs/)
[![License: GPLv3+](https://img.shields.io/badge/License-GPLv3%2B-blue.svg)](LICENSE)

**Documentation & live demos:** https://rod2ik.gitlab.io/mkdocs-revealjs/

## Modes

A page-wide presentation uses the canonical mode:

```yaml
---
revealjs:
  mode: diapo
---
```

A Reveal.js evaluation powered by `mkdocs-superquiz` uses:

```yaml
---
revealjs:
  mode: diapo.eval
---
```

There is intentionally no legacy `presentation:` syntax in 0.10.0.

### Accepted mode aliases

| Canonical | Accepted aliases |
| --- | --- |
| `diapo` | `diaporama`, `presentation`, `diapo.presentation`, `diapo.normal` |
| `diapo.eval` | `eval`, `evaluation`, `exam`, `examen`, `assessment`, `diapo.evaluation`, `diapo.exam`, `diapo.examen`, `diapo.assessment` |

Documentation uses only the canonical forms after this table.

## Multiple decks in one Markdown page

Use explicit deck blocks. Five or more `=` are accepted; the canonical form is:

```markdown
Ordinary MkDocs content.

=====

# Slide 1

---

# Slide 2

=====/

Ordinary MkDocs content again.
```

Each block may start with local front matter:

```markdown
=====

---
mode: diapo.eval
id: algebra-test
revealjs:
  transition: fade
superquiz:
  randomize: all
---

...slides...

=====/
```

`id` is optional. Missing identifiers are generated as `diapo1`, `diapo2`, `eval1`, `eval2`, ...

## Optional Markdown imports with mkdocs-macros-plugin

Install the optional extra and enable `macros` before `superquiz`/`revealjs`:

```bash
pip install "mkdocs-revealjs[macros]"
```

```yaml
plugins:
  - macros
  - superquiz
  - revealjs
```

Then import all explicit decks from another Markdown file at the exact insertion point:

```markdown
{{ diapo("slides/demo.md") }}
```

Alias:

```markdown
{{ include_diapo("slides/demo.md") }}
```

Select one explicitly named deck with a fragment:

```markdown
{{ diapo("slides/demo.md#algebra-test") }}
```

Relative paths are resolved from the current Markdown source file. A leading `/` means the MkDocs `docs_dir` root, never the operating-system root. Imports may not escape `docs_dir`.

## Configuration scopes

Reveal.js values resolve from least to most local:

```text
built-in defaults < mkdocs.yml < page front matter < deck-local front matter
```

SuperQuiz adds its own per-type and per-question layers. An explicit deck is a scope: a `diapo.eval` deck owns its own evaluation session; an explicit normal `diapo` deck keeps its questions embedded even inside a page-level SuperQuiz evaluation.

## Highlights

- multiple independent Reveal.js decks per page;
- horizontal and vertical slides;
- Material light/dark synchronization, including Android Reveal Scroll View backgrounds;
- Reveal.js, Highlight.js and Mermaid light/dark theming;
- server-side compatibility islands for MkDocs extensions;
- native `mkdocs-superquiz`, `mkdocs-maths-admonitions`, XTables and TikZJax integration;
- fragments, notes, auto-animate and Reveal.js options;
- optional `diapo()` / `include_diapo()` macros;
- `diapo.eval` sessions with global SuperQuiz validation, scoring, timer, question navigation, and a dedicated post-validation result/violation-summary slide.
- `mkdocs-superquiz >= 0.5.8` evaluation integration: the first click anywhere inside the visible `diapo.eval` wrapper enters deck-scoped fullscreen before password entry for both standard and strict evaluations. QR/timer/Reset/Unlock/live counts share one draggable deck toolbar, while numbered question navigation remains independently draggable. Strict defaults show QR + Reset and hide Unlock; the timer defaults to a 50-minute countdown; every recorded strict violation emits a stacked transient tooltip above the deck UI.

## Development

```bash
yarn dev
yarn dev:lan
yarn build
yarn build:full
yarn bfc
```

`yarn dev:lan` binds MkDocs to `0.0.0.0:8000` for testing from a real phone on the same LAN.

## License

GNU GPL-3.0-or-later.
