Metadata-Version: 2.4
Name: mkdocs-revealjs
Version: 0.9.3
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: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mkdocs-material<10,>=9; extra == "dev"
Requires-Dist: mkdocs-superquiz>=0.4.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 [Reveal.js](https://revealjs.com) presentations — written in Markdown — directly inside your [MkDocs](https://www.mkdocs.org) site, with full light / dark theme support.

[![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 demo →** https://rod2ik.gitlab.io/mkdocs-revealjs/

---

## What it does

- Write slides in plain Markdown inside any MkDocs page
- Presentations render as **embedded Reveal.js decks** — no separate site needed
- **Horizontal and vertical** slide navigation
- **Light / dark themes swap automatically** when the MkDocs Material colour scheme toggles — no page reload
- **Three independent theming scopes**: Reveal.js visual theme, Highlight.js code theme, Mermaid diagram theme
- **Mermaid diagrams** with per-scheme themes (opt-in)
- **Auto-animate** code transitions with a simple fence annotation
- Automatic runtime compatibility with **mkdocs-maths-admonitions** after slide creation
- **TikZJax compatibility** in ordinary slides, admonitions, collapsible details and Material content tabs
- **Fragments**, speaker notes, fullscreen, keyboard shortcuts
- Per-page overrides for every option
- Import slides from a separate `.md` file

---

## Quick start

### Install

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

### Enable in `mkdocs.yml`

```yaml
plugins:
  - search
  - revealjs:
      transition: slide
      controls: true
```

### Write a presentation page

```markdown
---
revealjs:
  presentation: true
---

## Slide 1

Hello world!

---

## Slide 2

- Point A
- Point B

Note: Speaker notes — press **S** to open speaker view.
```

That page now renders as an embedded Reveal.js presentation.
Press **F** for fullscreen, **O** for overview, **S** for speaker view.

---

## Slide syntax

```markdown
Horizontal separator  →  blank line + --- + blank line
Vertical separator    →  blank line + ---- + blank line
Speaker notes         →  Note: at start of line
End of presentation   →  blank line + ===== + blank line
```

Content after `=====` is rendered as normal MkDocs page content below
the presentation (useful for page titles, summaries, etc.).

---

## Theming

Each of the three scopes (`theme`, `highlight`, `mermaid`) supports a
**three-layer pipeline** per scheme:

```
starter  →  hack (inline CSS overrides)  →  custom (CSS file)
```

```yaml
plugins:
  - revealjs:
      theme:
        light: solarized
        dark:  dracula
      highlight:
        light: github
        dark:  github-dark
      mermaid:
        activate: true
        light: sky      # bundled custom theme
        dark:  fire     # bundled custom theme
```

### Custom Mermaid themes

The plugin ships two ready-made Mermaid themes (`sky` and `fire`) and
**auto-discovers** any additional theme you add: just drop a file named
`mermaid-theme-NAME.js` into `mkdocs_revealjs/themes/` and use `NAME` in
your config. No Python editing required.

Full theming reference → https://rod2ik.gitlab.io/mkdocs-revealjs/documentation/theming/

---

## Mermaid diagrams

```yaml
mermaid:
  activate: true
  light: sky
  dark:  fire
```

```markdown
<div class="mermaid">
flowchart LR
    A[Client] --> B[API] --> C[Database]
</div>
```

Diagrams re-render on every slide change and on every scheme switch.

Full Mermaid reference → https://rod2ik.gitlab.io/mkdocs-revealjs/documentation/mermaid/

---

## Repository layout

```text
mkdocs-revealjs/
├── src/
│   ├── mkdocs_revealjs/          # Python plugin and packaged assets
│   └── frontend/                 # SCSS sources compiled by Vite
├── site/                         # MkDocs documentation source
├── tests/
├── scripts/
├── dist/                         # generated wheel and source distribution
├── public/                       # generated GitLab Pages artifact
├── package.json                  # sole version source of truth
├── pyproject.toml
└── vite.config.mjs
```

---

## Documentation

The full documentation lives at **https://rod2ik.gitlab.io/mkdocs-revealjs/**
and covers:

- [Global options](https://rod2ik.gitlab.io/mkdocs-revealjs/documentation/globaloptions/)
- [Per-page options](https://rod2ik.gitlab.io/mkdocs-revealjs/documentation/perpageoptions/)
- [Slide syntax](https://rod2ik.gitlab.io/mkdocs-revealjs/documentation/slidesyntax/)
- [Theming](https://rod2ik.gitlab.io/mkdocs-revealjs/documentation/theming/)
- [Highlighting](https://rod2ik.gitlab.io/mkdocs-revealjs/documentation/highlighting/)
- [Mermaid diagrams](https://rod2ik.gitlab.io/mkdocs-revealjs/documentation/mermaid/)
- [Auto-animate](https://rod2ik.gitlab.io/mkdocs-revealjs/documentation/autoanimate/)
- [Fragments](https://rod2ik.gitlab.io/mkdocs-revealjs/documentation/fragments/)

---

## Development

```bash
git clone https://gitlab.com/rod2ik/mkdocs-revealjs
cd mkdocs-revealjs
corepack enable
yarn install
yarn dev
```

To test the development site from a phone on the same local network:

```bash
yarn dev:lan
```

Then open `http://<computer-LAN-IP>:8000/` on the phone. The regular
`yarn dev` command remains bound to localhost.

Main workflow commands:

```bash
yarn build
yarn build:full
yarn build:full:check
yarn bfc
yarn zip
```

`package.json` is the only version source of truth. The generated Python
`__version__` file and the documentation token `__REVEALJS_VERSION__` are
synchronized automatically by the build.

---

## License

GNU GPLv3 or later — see [LICENSE](LICENSE).
## Dynamic MkDocs content inside Reveal.js

Rich MkDocs fragments such as admonitions and content tabs are transported as
opaque HTML islands and hydrated only after Reveal.js has initialized. This
prevents Reveal's Markdown parser from changing radio groups, labels, nested
HTML, executable source blocks or third-party widget markup.

Browser libraries can integrate through the public lifecycle API:

```javascript
window.MkDocsRevealJS.registerContentAdapter("my-plugin", {
  refresh(root, context) {
    window.MyPlugin?.refresh?.(root, context)
  }
})
```

See `site/docs/documentation/content-lifecycle.md` for events and the
build-time `REVEALJS_MANAGED_PATTERNS` compatibility contract.
