Metadata-Version: 2.4
Name: mkdocs-revealjs
Version: 0.12.0
Summary: MkDocs plugin to embed Reveal.js presentations with Markdown syntax
Author-email: "Rod2ik, aka Rodrigo Schwencke" <rod2ik.dev@gmail.com>
License-Expression: 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: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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.10
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-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 decks directly inside MkDocs Markdown pages, with light/dark synchronization and integration hooks for dynamic MkDocs content.

[![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/

## Installation

Python 3.10 or newer is required.

```bash
pip install mkdocs-revealjs
```

```yaml
plugins:
  - search
  - revealjs
```

## Modes

The current API has exactly two modes:

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

for an ordinary Reveal.js deck, and:

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

for a Reveal.js evaluation owned by `mkdocs-superquiz`.

Historical mode aliases are not accepted.

## Multiple decks in one Markdown page

Use explicit deck blocks:

```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

Install the optional macros integration and enable `macros` before `revealjs`:

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

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

Then insert explicit decks from another Markdown file at the exact macro location:

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

Select one named deck with a fragment:

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

Relative paths resolve from the current Markdown source. A leading `/` resolves from `docs_dir`; imports cannot 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
```

An explicit deck is an independent scope. A `diapo.eval` deck owns its own evaluation session.

## Integrations

The runtime provides a generic dynamic-content lifecycle and current integrations for:

- `mkdocs-superquiz` evaluation decks;
- `mkdocs-maths-admonitions` full-deck numbering;
- `mkdocs-xtables` asynchronous table refresh;
- TikZJax dynamic rendering and post-render layout;
- `mkdocs-graphviz` server-rendered graphs;
- Material content tabs/details and Mermaid.

The documentation project uses explicit sibling/published dependency rules. Browser assets are generated under `site/overrides/vendor/`; Python documentation plugins are installed editable from declared siblings locally and from exact PyPI versions in CI. See the documentation page **Vendors & project dependencies** for the complete contract.

## Development

```bash
corepack enable
yarn install --immutable
yarn dev
yarn dev:lan
yarn build
yarn build:full
yarn bfc
yarn zip
```

`package.json` is the single source of truth for the project version.

## License

GNU GPL-3.0-or-later.
