slidev-addon-blackboard

Presenter blackboard overlays, persistent boards, guide layers, and exhibit tools for Slidev decks.

Install

npm install slidev-addon-blackboard

Add the addon to your slides.md frontmatter:

---
addons:
  - blackboard
---

Or declare it in your deck package.json:

{
  "slidev": {
    "addons": [
      "blackboard"
    ]
  }
}

Features

• Toggle a blackboard or whiteboard overlay during presentation.
• Draw, erase, undo, redo, and navigate across multiple board pages.
• Persist boards to .slidev/blackboards for live reuse.
• Add presenter-only guide boards that sit underneath the live board as a private prompt.
• Load pre-made live board sets that are shown during the presentation.
• Insert table, Mermaid, image, and SVG exhibits from deck assets.
• Include blackboard pages in export and build flows.

Blackboard Types

The addon supports a few different board sources, depending on how you want to present:

• Live blackboards are the boards you draw on during the presentation. They can be blank, persistent, or loaded from a pre-made set.
• Guide blackboards are pre-made boards visible only to the presenter. They appear underneath the live blackboard at a configurable opacity, which makes them useful for prompts, solution outlines, diagrams, or timing cues that should not be shown to the audience.
• Pre-made live blackboards are pre-written boards that appear as the live boards during the presentation. Use them when you want prepared writing, diagrams, or annotations to show up for the audience without redrawing them live.
• Saved live blackboards are boards captured during the presentation, that are used when exporting.

Configuration

The addon reads the blackboard frontmatter option from your deck.

---
addons:
  - blackboard
blackboard:
  persist: true
  guide:
    enabled: true
    opacity: 0.22
  export:
    include: true
    background: whiteboard
  build:
    append: true
    background: whiteboard
---

Common options:

• blackboard: false disables the addon for a deck.
• blackboard.enabled can be true, false, dev, build, or export.
• blackboard.persist: true stores live boards under .slidev/blackboards/live.
• blackboard.persist: "./path" stores live boards at a custom path.
• blackboard.guide.enabled enables guide board sets.
• blackboard.export.include includes blackboard pages in export mode.
• blackboard.build.append appends blackboard slides during static builds.

Board Assets

When persistence is enabled, the addon looks under .slidev/blackboards by default:

.slidev/blackboards/
  exhibits/
  guides/
  live/
  premade/

Use guides for presenter-only guide boards. Use live for boards written or saved during presentation. Use premade for pre-made live blackboards that should be visible as live boards during the talk.

The exhibits folder can contain Markdown tables, Mermaid files, SVG files, and image assets. The deck public folder is also exposed as a deck-assets exhibit source.

Global Preferences

Live teaching preferences are global across decks. The addon stores the blackboard/whiteboard background, brush color, brush size, selected drawing tool, and guide opacity in ~/.slidev/blackboard/preferences.json. Changing one of those controls in presenter mode updates the global profile, so the next deck opens with the same blackboard style. Saved board sets store only boards and drawings; they do not store a theme.

Export and build backgrounds remain deck/export options, so changing the live teaching background does not change configured export behavior.

Blackboard Sections

Blackboard sections let a deck move naturally between slides and live writing. A section maps a range of slides to one set of live boards, one matching pre-made live board set, and one matching guide board set. The section manifest is stored by the addon in .slidev/blackboards/sections.json.

There are two kinds of sections:

• Prepared sections are created before presenting. They are anchored to two Slidev routeAlias values: one on the first slide in the range and one on the last slide in the range.
• Live sections are created automatically during a presentation. If the presenter opens the blackboard on a slide that does not belong to an existing valid section, the addon creates a slide-number section named Slide X.

Add prepared-section aliases in slide frontmatter:

---
routeAlias: /cost-volume-profit-start
---

# Cost-volume-profit

---
routeAlias: /cost-volume-profit-end
---

# Section wrap-up

Use leading slashes for aliases, such as /cost-volume-profit-start. In presenter mode, open the blackboard section menu, choose Create prepared section, select the first and last aliases, and give the section a unique name. The addon blocks duplicate names and invalid alias ranges.

During presentation:

• The blackboard nav button is visible only in presenter mode.
• When the presenter reaches the first slide of a valid section, a visible button appears on the presenter slide view. Clicking it opens that section's blackboard.
• Opening the blackboard inside an existing section loads that section's boards.
• Adding, removing, or selecting boards affects only the active section's board set.
• Close hides the blackboard and stays on the current slide.
• Finish section hides the blackboard and moves to the first slide after the section, unless the section has a custom finish slide.

Inside the blackboard section menu you can:

• switch the active section
• rename the section
• edit slide-number section start/end slides
• set an optional finish slide
• create prepared alias sections
• remove a section

Removing a section also removes its matching live, pre-made live, and guide board sets. Slide-number sections show a stability warning because deck edits can shift their stored slide numbers; route-alias sections resolve their start and end slides from the current deck.

Requirements

This addon targets Slidev >=52.0.0.

Development

npm run check:pack

Slidev compiles addon .vue and .ts files directly, so the package intentionally publishes source files rather than a bundled build.

License

MIT