README file from
GithubObsidian Presenter
Storyboard & Speaker Script Studio for Obsidian — Built for the AI Presentation Era.
Stop fighting pixel alignment in Markdown. In the era of AI slide generators (Gamma, Claude, Genspark), Obsidian Presenter lets you focus on what only a human can craft: the core argument, storyline, 1-slide-1-message density, and speaker script.
Write naturally in Markdown (# H1 as cover, ## H2 as slide action title, > [!note] as speaker script & background context). Rehearse your 16:9 visual storyboard alongside a live Speaker Script Dock (with character count and speaking time estimation), and either copy a structured AI Slide Blueprint in one click or share directly as a self-contained HTML SlideDoc, PDF, or editable PowerPoint (.pptx).
Features
- Live Storyboard & Speaker Script Studio (Split-Pane Preview):
- View a 16:9 visual storyboard right beside your editor in real time as you write.
- Built-in Speaker Script & Context Dock beneath the slide card displays your
> [!note]talking points alongside live character count and speaking time estimates (~X min). - Automatically syncs and highlights the slide matching your editor cursor position (with a pin/unpin toggle and a 250ms debounced renderer).
- One-Click AI Slide Prompt & Storyboard Blueprint Copy:
- Run
Presenter: Copy AI slide prompt & storyboard blueprint(or click the ✨ Sparkles button on the preview toolbar) to copy a structured, slide-by-slide design prompt and storyboard specification for Gamma, Claude, Genspark, or ChatGPT. - Preserves each slide's role, layout archetype (2-column, 3-step flow, 2x2 matrix, pyramid, funnel, chart, etc.), on-slide body copy, and speaker script context—plus total estimated speaking time.
- Run
- Natural Markdown Structure & Continuation Heading Inheritance:
# H1: Presentation title slide.## H2: New slide title and delimiter.### H3/#### H4: Subsections and column headers within slides.- Explicit slide delimiters using horizontal rules (
---) automatically inherit and number the parent## H2section heading asTitle 1-1, Title 1-2, ... Title 1-N(configurable via Settings or frontmatterinheritHeadings: false).
- Smart Slide Layouts & "Tsutawaru Design" Auto-Transforms:
- Automatically identifies header-only slides as centered Section Divider slides and single-blockquote slides as Quote / Big Statement cards.
- Zero-directive auto-layouts: Writing 2–3 concise
### H3sections automatically arranges them into borderless soft-surface cards (#F8FAFC); writing 4### H3sections automatically forms a 2×2 grid to minimize eye movement. - Golden ratio (
6:4) media & code splits: A standalone image or fenced code block paired with explanatory bullet points automatically transforms into a6:4split layout (with dark syntax surface#0F172Afor code). - Vertical-borderless comparison tables with column highlight: Eliminates visual noise by removing vertical borders, right-aligning numbers (
tabular-nums), and highlighting the recommended column via<!-- table: highlight N -->or[Recommended]/[推奨]/★headers. - Q&A hanging indent alignment: Consecutive
Q.andA.lines are automatically formatted into aligned FAQ cards. - Full override support with explicit directives (
<!-- slide: section -->,<!-- slide: quote -->,<!-- slide: content -->) and configurable toggle in Settings or frontmatter (smartLayouts: false).
- 70:25:5 Color System & Flexible Themes (Settings & Frontmatter):
- Built on the golden 70:25:5 color hierarchy: Base background (
baseColor:#ffffff), Main structure (accentColor:#2563eb), and 5% Pop highlight (popColor:#ea580c) for hero KPIs, recommended table columns, and priority quadrants. - Zero-configuration required: notes convert to slides instantly, and any property can be overridden per note via frontmatter.
- Built on the golden 70:25:5 color hierarchy: Base background (
- Multi-Column Grid Layouts & Ratio/Step Options:
- Uses standard Markdown-compatible HTML comments (
<!-- columns 2 -->,<!-- columns 3 -->,<!-- columns 2x2 -->) for cross-platform compatibility. - Non-uniform column ratios: Supports
<!-- columns 6:4 -->(3:2),<!-- columns 4:6 -->(2:3),<!-- columns 2:1 -->, and<!-- columns 1:2 -->. - Step flow process: Use
<!-- columns 3 step -->to format items as progressive sequence cards (STEP 01,STEP 02...). - Choose between borderless Card style (
#F8FAFCsoft surface) and Plain style (<!-- columns 2 plain -->).
- Uses standard Markdown-compatible HTML comments (
- Interactive Slide Template Navigator & Command Palette Quick Picker:
- Built-in visual template navigator featuring 13 consulting-grade slide layouts, 12 purpose-driven usecases ("Find by purpose"), CSS wireframe previews, strict layout rules, and 6 core slide design principles.
- Insert complete slide scaffolds (action title + structured columns/tables/callouts) or layout bodies with a single click from the command palette (
Presenter: Insert slide design template...,Presenter: Open slide template navigator..., or any of the 13 directPresenter: Insert design template: ...commands) or the live preview toolbar.
- KPI Metrics & Styled Key Takeaway Callouts:
- Standalone bold metrics like
**+140%**or**3.5x**are automatically displayed with prominent accent typography. - Callouts such as
> [!important],> [!tip], and> [!warning]are styled as impactful conclusion summary cards.
- Standalone bold metrics like
- Slide Overview Grid (Slide Sorter):
- Press
GorO(or click the grid icon on the toolbar) to view a bird's-eye thumbnail grid of all slides, enabling instant jump navigation during Q&A sessions.
- Press
- Clickable Image & Diagram Zoom (Lightbox):
- Click any image or Mermaid diagram during a presentation or in exported HTML to zoom in full-screen (
Escapeto close).
- Click any image or Mermaid diagram during a presentation or in exported HTML to zoom in full-screen (
- One-Click Executive Summary & AI Blueprint Copy:
- Run
Presenter: Copy AI slide prompt & storyboard blueprintto copy a complete slide-by-slide storyboard prompt for AI slide generation tools. - Run
Presenter: Copy executive summary for sharingfrom the command palette (or the preview toolbar ✨ menu) to copy a structured outline with key takeaways to your clipboard for instant pasting into Slack, Teams, or email.
- Run
- Automatic Labels & Badges:
- Writing
[IMPORTANT],[NOTE], or[STEP 1]automatically formats text into a visually distinct accent badge.
- Writing
- Full Obsidian Markdown Support:
- Clean rendering of tables, code blocks, images, LaTeX math formulas, Callouts, checklists, and lists.
- Header, Footer & Logo Display:
- Customizable header titles, logos, copyright notices, and page numbers (
X / Y).
- Customizable header titles, logos, copyright notices, and page numbers (
- Speaker Notes:
- Standard Obsidian callouts (
> [!note]) are automatically excluded from the main projection slides and kept as speaker notes. - Toggle speaker notes on/off during a presentation using the toolbar or the
Nkey.
- Standard Obsidian callouts (
- Handout (SlideDoc) Printing:
- Select "Print handout with notes" to produce clean, executive-ready A4 handouts featuring the slide view alongside detailed explanations.
- Standalone Portable HTML Export:
- Export self-contained, single-file HTML presentations (
<note-name>-presentation.html) via the command palette. - Recipients need only a web browser (no Obsidian or internet connection required) and can switch between [ 🖥 Slide View ] and [ 📄 Handout Document View ] with a single click.
- Includes slide overview drawer (
Gkey),#slide-Ndeep-link URL hash synchronization, and lightbox zoom.
- Export self-contained, single-file HTML presentations (
- Editable PowerPoint (
.pptx) Export:- Export native, editable PowerPoint slide decks (
<note-name>-presentation.pptx) via the command palette (Presenter: Export presentation as powerpoint (.pptx)) or the toolbar Print/Export menu. - Preserves theme colors, multi-column grids, non-uniform ratios, step flow cards, tables, code blocks, callouts, KPI cards, images, Mermaid diagrams, and speaker notes.
- Export native, editable PowerPoint slide decks (
- High-Quality PDF Export:
- Press
Cmd + P(Mac) orCtrl + P(Windows) inside presentation mode to export high-resolution slide or handout PDFs.
- Press
- Slide Overflow Detection & Auto-fit:
- Detects overflowing content in real time and displays an alert badge (
⚠ N) on the toolbar. - Auto-fit compresses font size, line height, and padding down to 70% to keep content inside the card frame without losing legibility.
- For long slides exceeding 70% reduction, the inspector modal provides a one-click Split slide button to cleanly divide the slide at heading boundaries (undoable via
Cmd + Z).
- Detects overflowing content in real time and displays an alert badge (
- Responsive Aspect Ratio:
- Automatically scales to fit any screen resolution while maintaining standard 16:9 or 4:3 aspect ratios.
Installation
From Obsidian Community Plugins
(Available once approved)
- Open Settings → Community plugins in Obsidian.
- Turn off Restricted mode.
- Click Browse and search for Presenter.
- Click Install, then Enable.
Manual Installation
- Download the latest release assets (
main.js,manifest.json,styles.css) from GitHub Releases. - Create the plugin folder inside your vault:
<Vault>/.obsidian/plugins/markdown-presenter/ - Copy
main.js,manifest.json, andstyles.cssinto that folder. - In Obsidian, go to Settings → Community plugins, click Reload plugins, and enable Presenter.
Usage
1. Write Slide Notes
Frontmatter configuration is completely optional. Add frontmatter only when you want to customize settings for a specific presentation.
---
# Optional overrides (defaults from Settings tab are used if omitted)
header: "Q4 Strategy Pitch"
accentColor: "#38bdf8"
---
# New Business Proposal
Innovating Knowledge Work with AI
Speaker: Jane Doe
Date: 2026-10-15
## Background & Challenges
While generative AI tools increase information bandwidth, sharing structured knowledge still takes too long.
- High presentation deck creation overhead
- Time wasted adjusting formatting and slide layouts
- Knowledge quickly becoming outdated
## Proposed Solution
<!-- columns 2 -->
### Markdown-Driven
- Regular notes transform directly into slides
- AI-generated outlines ready for presentation
### Rapid Preview & PDF
- Instant real-time preview
- One-click PDF generation for executive review
<!-- /columns -->
## Summary
Bridge the gap between thought and presentation with zero friction.
2. Open Live Slide Preview
Keep a live slide preview open side-by-side as you write:
- Editor Tab Header: Click the TV icon in the top-right header of your note.
- Command Palette: Run
Presenter: Open slide previeworPresenter: Toggle slide preview. - Ribbon Icon: Click the TV icon in the left ribbon bar.
[!TIP]
- Cursor Sync: The preview automatically scrolls to the slide where your cursor is positioned. Click the pin icon in the preview header to pause auto-sync and inspect a specific slide.
- Launch Fullscreen: Click the "Start presentation" button in the preview header to immediately switch to full-screen mode at the current slide.
3. Start Presentation (Fullscreen)
- Ribbon Icon: Click the projector screen icon in the left ribbon.
- Command Palette: Run
Presenter: Start presentation.
Keyboard Shortcuts
| Action | Keys |
|---|---|
| Next Slide | → / ↓ / Space / PageDown / L / J |
| Previous Slide | ← / ↑ / PageUp / H / K |
| First Slide | Home |
| Last Slide | End |
| Toggle Fullscreen | F |
| Slide Overview Grid | G / O |
| Toggle Speaker Notes | N |
| Print / PDF Export | P |
| Zoom Image / Diagram | Click image or Mermaid SVG (Escape to close) |
| Exit Presentation | Escape |
Multi-Column Grid Layouts
1. Basic Syntax (HTML Comment Directives)
Presenter uses standard HTML comments (<!-- columns N -->) to specify multi-column layouts so your notes stay 100% compliant with CommonMark. In other editors (GitHub, VS Code), these comments remain invisible and your headings render as standard sections.
2-Column Example
<!-- columns 2 -->
### Left Column
Content for the left side (lists, images, text)
### Right Column
Content for the right side
<!-- /columns -->
Headings (such as H3) automatically define column boundaries. If you wish to split paragraphs without headings, insert <!-- column -->:
<!-- columns 2 -->
Content for left column
<!-- column -->
Content for right column
<!-- /columns -->
Use <!-- columns 3 --> or <!-- columns 4 --> for 3 or 4 columns.
2. Column Styles: Card vs Plain
| Style | Appearance | Usage |
|---|---|---|
| Card (Default) | Subtle background tint, rounded border, and comfortable padding | <!-- columns 2 --> or <!-- columns 2 card --> |
| Plain | Transparent background, borderless, zero internal padding | <!-- columns 2 plain --> or <!-- columns 3 plain --> |
Example: Plain Style
<!-- columns 2 plain -->
### Minimalist Layout
Blends directly into the slide background without borders.
### Clean Data Comparison
Ideal for clean side-by-side lists and image comparisons.
<!-- /columns -->
Setting Global or Note Defaults
- Per-note default: Add
columnStyle: plainto the frontmatter. - Global vault default: Go to Settings → Presenter → Default column style and select
Plain (transparent & borderless).
3. Quick Insertion Commands & Slide Template Navigator
Insert column directives or full consulting slide templates quickly using the Command Palette (Cmd + P / Ctrl + P), the live preview toolbar (layout-template icon), or by binding hotkeys:
Presenter: Insert slide design template...(QuickSuggestModalsearch picker for all 13 logical archetypes with wireframe previews;Entersmart-inserts based on cursor context,Shift+Enterinserts layout body only,Cmd/Ctrl+Enterinserts full slide)Presenter: Open storyboard & layout navigator...(Visual 3-tab navigator with 13 logical slide archetypes, 12 communication purposes, and 6 storyboard principles)Presenter: Insert design template: <template name>(13 direct commands for horizontal flow, vertical flow, swimlane, cycle, 2-column, 3-column, 2x2 matrix, pyramid, chart & insight, big number KPI, funnel, bento box, and executive summary)Presenter: Insert column layout...(Interactive modal picker)Presenter: Insert 2-column layoutPresenter: Insert 3-column layoutPresenter: Insert 4-column layoutPresenter: Insert 2-column plain layoutPresenter: Insert column break(<!-- column -->)
[!TIP] If text is currently selected, running an insert command automatically wraps the selected block in
<!-- columns N -->and<!-- /columns -->.
Labels & Badges
Writing [label] text automatically styles the bracketed label with an accent color badge:
- [IMPORTANT] Deadline is next Wednesday
- [CHALLENGE] Reducing slide creation time
- [STEP 1] Requirements definition and outline
Regular Markdown links [Title](url), internal wikilinks [[Note]], and task checkboxes - [ ] remain unaffected.
Speaker Notes & Distribution
Balance live stage presentations with easy document distribution for non-technical stakeholders:
1. Writing Speaker Notes
Use standard Obsidian callout syntax > [!note]:
## Core Architecture
- Microservices backend
- Event-driven message queue
> [!note] Speaker Note & Explanation
> This text is automatically hidden on the big presentation screen and visible only in speaker notes (`N` key).
> During HTML export or handout printing, it expands beneath the slide as detailed explanatory reading material.
2. Standalone HTML Export
Export your presentation as a single self-contained HTML file:
- Run
Presenter: Export presentation as standalone HTMLfrom the Command Palette. - The exported
<note-name>-presentation.htmlcontains all scripts and styles inline—no external servers or dependencies required. - Recipients simply double-click to view, with a toggle in the top-right corner to switch between [ 🖥 Slide Mode ] and [ 📄 Handout Document Mode ] (featuring a sticky hierarchical table of contents sidebar to jump across sections).
3. Editable PowerPoint (.pptx) Export
Export your presentation as a native PowerPoint file for corporate sharing or further editing:
- Run
Presenter: Export presentation as powerpoint (.pptx)from the Command Palette, or click the Print icon in presentation mode and select Export as powerpoint (.pptx). - Saves
<note-name>-presentation.pptxto the same folder as your note and triggers a browser download, complete with editable text boxes, styled columns, tables, diagrams, and speaker notes.
4. Handout (SlideDoc) Print & PDF
- Press
Por click the Print icon in presentation mode and choose Print handout with notes. - Generates an executive A4 PDF report with slide cards on top and detailed speaker notes below.
Slide Overflow Detection & Auto-fit
Prevents content overflow and cut-off text during presentations.
1. Alert Badges & Inspector Modal
- A badge (
⚠ N) appears on the toolbar whenever slides exceed their visible card bounds. - Clicking the badge opens the Slide overflow inspection modal showing exact overflow percentages (
+20% overflow) and quick action buttons.
2. Auto-fit
Automatically scales down CSS font size, line height, and padding (clamped down to 70% to ensure readability).
- Vault-wide setting: Enable Settings → Layout & grid → Auto-fit overflowing slides.
- Per-note setting: Add
fit: autoto frontmatter.
---
fit: auto
---
3. One-Click Slide Splitting
For large slides that still overflow at 70% reduction, click Split slide inside the inspection modal to automatically insert a --- break before the second ### heading.
AI Slide Authoring Skill (Agent Skill)
An official AI Agent Skill (create-presentation) optimized for Obsidian Presenter is available in a dedicated repository for tools like Google Antigravity and Claude Code.
- Repository: xhisashix/obsidian-presenter-skill
- Key Features:
- Automatically structures H1/H2 hierarchies and ensures one message per slide.
- Implements multi-column layouts (2-column, 3-column, 2:1 ratio, step flows).
- Decorates slides with KPI big numbers, bracket badges, and conclusion callouts.
- Segregates speaker notes and handout details via
> [!note]. - Applies overflow auto-fit (
fit: auto).
- Getting Started: Simply clone or copy the skill into your Vault's
.agents/skills/directory to generate high-quality slide decks by prompting in natural language. See the skill repository for details.
Design Documents
For architecture details, specifications, and UI/UX design:
- System Architecture (architecture.md)
- Functional Specification (specification.md)
- UI/UX & Styling Specification (ui-ux.md)
Development
# Install dependencies
npm install
# Watch mode
npm run dev
# Production build (type-check & bundle)
npm run build
# Run linter
npm run lint
# Run test suite
npm test
License
MIT License © 2026 xhisashix