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/
├── 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:

Development

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

Main workflow commands:

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_revealjs-0.8.6.tar.gz (40.6 kB view details)

Uploaded Aug 5, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

mkdocs_revealjs-0.8.6-py3-none-any.whl (36.7 kB view details)

Uploaded Aug 5, 2026 Python 3

File details

Details for the file mkdocs_revealjs-0.8.6.tar.gz.

File metadata

Download URL: mkdocs_revealjs-0.8.6.tar.gz
Upload date: Aug 5, 2026
Size: 40.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.14.6

File hashes

Hashes for mkdocs_revealjs-0.8.6.tar.gz
Algorithm	Hash digest
SHA256	`e5fbc90075bb0625457698d1c013a6a60a6edfbc91db0527e3324adf9877aaf6`
MD5	`8b5499a7e5fccd0d44eb8451d57147fc`
BLAKE2b-256	`4db6524ec1d9b4a2d05b1aad0b8dcfc434a41761550c28c98d8b5a8af380fc85`

See more details on using hashes here.

File details

Details for the file mkdocs_revealjs-0.8.6-py3-none-any.whl.

File metadata

Download URL: mkdocs_revealjs-0.8.6-py3-none-any.whl
Upload date: Aug 5, 2026
Size: 36.7 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.14.6

File hashes

Hashes for mkdocs_revealjs-0.8.6-py3-none-any.whl
Algorithm	Hash digest
SHA256	`f4268747beb5eb2d2bd8c6b663d7bb34a5a96637e1165652fec7ce508da6bd39`
MD5	`0fd40b4d78ed5647be20f8a099e432c7`
BLAKE2b-256	`a4bb7a62d0d75bd2c2233a4222503166d3d2faf0c3cda3100a99b3422b66af27`