Markdown Slides Preview for VS Code

An extension for Visual Studio Code that allows you to preview and present markdown files as slides directly in your editor.

Features

Render markdown slides directly in VS Code
Automatic slide detection from markdown content
Support for Mermaid diagrams
Keyboard navigation (arrow keys, space)
Fullscreen presentation mode
Export slides functionality (Coming Soon)

Installation

From VS Code Marketplace

Open VS Code
Go to Extensions view (Ctrl+Shift+X or Cmd+Shift+X on macOS)
Search for "principle.md"
Click Install

From VSIX File

Download the .vsix file from the latest release
Open VS Code
Go to Extensions view
Click the "..." menu (top-right of Extensions view)
Select "Install from VSIX..."
Choose the downloaded .vsix file

Usage

Open a markdown file in VS Code
Use one of these methods to open the preview:
- Click the preview icon in the editor title bar (when viewing a markdown file)
- Run the command "principle.md: Open Preview" from the command palette (Ctrl+Shift+P or Cmd+Shift+P)
- Use the keyboard shortcut Ctrl+Shift+V (Cmd+Shift+V on macOS)
The preview will open in a new editor column

Creating Slides

There are two ways to define slides in your markdown:

Method 1: Using slide markers

:::slide
# Slide 1 Title
Slide 1 content
:::

:::slide
## Slide 2 Title
Slide 2 content
:::

Method 2: Using level 2 headings

Each level 2 heading (##) in your document will start a new slide.

# Presentation Title

## Slide 1
Content for slide 1

## Slide 2
Content for slide 2

Mermaid Diagrams

You can include Mermaid diagrams in your slides:

:::slide
# Diagram Example

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
``  `
:::

Keyboard Controls

In the slide preview:

Right Arrow / Down Arrow / Space: Next slide
Left Arrow / Up Arrow: Previous slide
PageDown / Alt+Right: Next slide
PageUp / Alt+Left: Previous slide
Alt+Home: First slide
Alt+End: Last slide
F: Toggle fullscreen mode
Escape: Exit fullscreen mode

In VS Code:

Ctrl+Shift+V (Mac: ⌘+Shift+V): Open slide preview
Ctrl+Shift+E (Mac: ⌘+Shift+E): Export slides

Exporting Slides (Coming Soon)

You can export your slides using one of these methods:

Run the command "principle.md: Export Slides" from the command palette
Use the keyboard shortcut Ctrl+Shift+E (Cmd+Shift+E on macOS)

The extension supports exporting to:

HTML - A standalone HTML file that can be opened in any browser
Markdown - A processed markdown file with slides properly formatted

Configuration

You can configure the extension in your VS Code settings:

markdownSlides.theme: Theme for slide preview (auto/light/dark)
markdownSlides.autoRefresh: Automatically refresh preview when file changes

Drafting Presentations via MCP (Model Context Protocol)

You can also draft presentations without saving them to a file by using the Model Context Protocol (MCP).

Work with your favorite ide agent to draft perfect requirements so that you can feel safe sending it off on its own.

MCP Tool: `sendMarkdownSlides`

The extension exposes an MCP tool named sendMarkdownSlides that accepts markdown content and an optional presentation title.

Arguments:

markdown (string, required): The markdown content for the presentation. Must not be empty.
presentationTitle (string, optional): A title for the presentation.

Example MCP Client Configuration (Supergateway):

If you are using a tool like Supergateway to interact with MCP services, you can configure it as follows:

{
  "PrincipleMDSlides": {
    "command": "npx",
    "args": [
      "-y",
      "supergateway",
      "--sse",
      "http://localhost:7630/principle-md-api/sse"
    ],
    "disabled": false,
    "autoApprove": [],
    "timeout": 600
  }
}

Note: The default port for the PrincipleMD MCP server is 7630. If you have configured a different port in the extension settings (principleMD.mcpServer.port), please update the URL accordingly.

How it works:

When an MCP client calls the sendMarkdownSlides tool, the extension will:

Receive the markdown content.
Open a new, virtual markdown document with the received content.
Display the slide preview for this virtual document.

This allows for quick iteration and drafting of presentations without needing to create and save .md files for each version.

Requirements

Visual Studio Code v1.60.0 or higher

License

GNU GPL v3.0

principle.md