mkdocs-revealjs 0.8.0

MkDocs plugin to embed Reveal.js presentations with Markdown syntax

mkdocs-revealjs

Embed Reveal.js presentations — written in Markdown — directly inside your MkDocs site, with full light / dark theme support.

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

pip install mkdocs-revealjs

Enable in mkdocs.yml

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

Write a presentation page

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

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)

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

mermaid:
  activate: true
  light: sky
  dark:  fire

<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
• Per-page options
• Slide syntax
• Theming
• Highlighting
• Mermaid diagrams
• Auto-animate
• Fragments

---

Development

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.