# 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: MIT](https://img.shields.io/badge/License-MIT-yellow.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
- **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

```
mkdocs-revealjs/
├── mkdocs_revealjs/
│   ├── plugin.py                 ← all plugin logic
│   ├── assets/                   ← compiled CSS + JS
│   └── themes/                   ← custom Mermaid theme JS files
│       ├── mermaid-theme-sky.js
│       └── mermaid-theme-fire.js
├── docs/                         ← full documentation source
├── examplesite/                  ← demo MkDocs site
├── pyproject.toml
├── package.json
└── gulpfile.js
```

---

## 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
pip install -e ".[dev]" --break-system-packages
corepack enable && yarn install && yarn build
cd examplesite && mkdocs serve
```

---

## License

MIT — see [LICENSE](LICENSE).