A Zensical and MkDocs plugin that provides a focus-slide widget, see live-example.

Instant Slide Deck · Automatic Sectioning · Progression Bar · URL Sync & Reload Persistence · Keyboard Controls · Mermaid Diagrams · Multilingual

Purpose

To avoid creating slides in a separate presentation software, this plugin provides a focus-slide widget that allows you to create slides directly in your project documentation.

Installation

Option 1: Direct URL (Recommended for now, no installation required)

Because Zensical does not provide an official public plugin API module system yet, linking minified assets directly via CDN is the quickest method. No package installation is needed.

Add the assets to zensical.toml (or mkdocs.yml):

Latest version:

[project]
extra_css = [
	"https://cdn.jsdelivr.net/gh/BeyondMagic/zensical-slides@latest/dist/zensical-slides.min.css",
]
extra_javascript = [
	"https://cdn.jsdelivr.net/gh/BeyondMagic/zensical-slides@latest/dist/zensical-slides.min.mjs",
]

Versioned (pinned):

[project]
extra_css = [
	"https://cdn.jsdelivr.net/gh/BeyondMagic/zensical-slides@1.0.9/dist/zensical-slides.min.css",
]
extra_javascript = [
	"https://cdn.jsdelivr.net/gh/BeyondMagic/zensical-slides@1.0.9/dist/zensical-slides.min.mjs",
]

Option 2: Markdown Extension (MkDocs and Zensical)

Install the Python package:

pip install zensical-slides

Enable zensical_slides in your markdown extensions. This works in both standard MkDocs and Zensical, inlining bundled assets directly with full offline support.

In zensical.toml:

[project.markdown_extensions.zensical_slides]
progress_bar = "top"  # "top" (default), "bottom", or "none"
language = "en"       # "en" (default), "ja", or "pt"
assets = "local"      # "local" (default, bundled offline), "cdn", or "none"

In mkdocs.yml:

markdown_extensions:
  - zensical_slides:
      progress_bar: top
      language: en
      assets: local

Option 3: Local CLI Installer (zensical-slides install)

This method copies assets into your project's docs_dir and configures them in zensical.toml. It is provided now for compatibility and ahead of future official Zensical module API support.

pip install zensical-slides
zensical-slides install

The command copies logic.mjs and ui.css into <docs_dir>/assets/plugin/zensical-slides/ and adds them to zensical.toml:

[project]
extra_css = [
	"assets/plugin/zensical-slides/ui.css",
]
extra_javascript = [
	"assets/plugin/zensical-slides/logic.mjs",
]

When using Option 3, re-run zensical-slides install whenever you change settings in [project.theme] or [project.extra.slides].

Configuration

Depending on your installation method:

• Option 1 (Direct URL): Configure the language via [project.theme] (language = "en") or HTML document lang attributes.
• Option 2 (Markdown Extension): Configure settings directly in [project.markdown_extensions.zensical_slides] (or markdown_extensions in mkdocs.yml).
• Option 3 (CLI Installer): Configure settings in [project.theme] and [project.extra.slides]:

[project.theme]
language = "en" # "en" (English), "ja" (Japanese), or "pt" (Portuguese)

[project.extra.slides]
progress_bar = "top" # "top" (default), "bottom", or "none"

License

This project is licensed under LGPLv3.