Introduction¶

Zensical Slides

A large part of the problem of communication is with the introduction. If you want people to look at things from a certain point of view, or to appreciate certain aspects of your work, then you need to present this clearly at the start of the project.

zensical-slides turns any Zensical page into a slide deck directly in the browser. Click the ▶ Show button in the bottom-right corner or press P to test presentation mode on this page.

How slide grouping works¶

When presentation mode starts, the script groups the article content by <h2> (##) headings:

Everything before the first ## heading forms the opening slide.
Each ## heading starts a new slide and includes all following elements until the next ## heading.
State is preserved across page reloads (F5), and URLs synchronize with ?slide=N for direct slide linking.
Exiting presentation mode scrolls smoothly to the section you were viewing and clears ?slide from the URL.

Speaker note (.apresentador): This paragraph uses the muted presenter style so you can keep talking points on screen without distracting from the primary text.

Keyboard and button controls¶

You can move between slides using the on-screen buttons or keyboard shortcuts:

Action	Shortcut	UI Control
Toggle presentation mode	`P`	▶ Show / ✕ Exit
Next slide	`Right`, `Page Down`, or `Space`	Right arrow (`›`)
Previous slide	`Left` or `Page Up`	Left arrow (`‹`)
Jump to slide	Click on progress bar	Progression bar (top or bottom)
Toggle fullscreen	`F`	Fullscreen button (`⛶`)
Exit presentation mode	`Esc`	✕ Exit

Configuration¶

You can configure plugin options in zensical.toml:

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

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

Re-run zensical-slides install whenever changing configuration settings to regenerate the client configuration.

Installation¶

Install the package with pip and run the CLI installer inside your project directory:

pip install zensical-slides
zensical-slides install

The installer copies logic.mjs and ui.css into <docs_dir>/assets/plugin/zensical-slides/ and registers them in zensical.toml:

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

Diagrams and callouts in slides¶

Presentation mode styles blockquotes, tables, code blocks, and initializes Mermaid diagrams when a page loads.

Good documentation works both as a reference you read at your own pace and as a visual aid when walking a team through a decision.

flowchart LR
    MD["Markdown Page (## Sections)"] --> CLI["zensical-slides install"]
    CLI --> BUILD["zensical build / serve"]
    BUILD --> SLIDES["Interactive Slide Deck (Press P)"]