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

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:

• 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
corepack enable
yarn install
yarn dev

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

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:

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.

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:

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.