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

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

From VSIX File

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

Usage

1. Open a markdown file in VS Code
2. 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)
3. 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:

1. Run the command "principle.md: Export Slides" from the command palette
2. 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

Creating Custom Providers

The extension supports creating custom providers to organize and display your markdown files in different ways. There are three approaches:

1. Provider Mappings (Configuration-based)

Map specific file patterns to existing providers using VS Code settings:

{
  "principle-md.providerMappings": [
    {
      "pattern": "docs/**/*.md",
      "provider": "slides",
      "label": "Documentation Slides",
      "priority": 1
    },
    {
      "pattern": "meeting-notes/**/*.md", 
      "provider": "files",
      "label": "Meeting Notes",
      "priority": 2
    }
  ]
}

2. Dynamic Custom Providers (User-configurable)

Define entirely new providers through configuration without writing code:

{
  "principle-md.customProviders": {
    "research-notes": {
      "displayName": "Research Notes",
      "icon": "book",
      "groupBy": "directory",
      "sortBy": "modified",
      "commands": ["principle-md.openPreview"]
    },
    "project-docs": {
      "displayName": "Project Documentation",
      "icon": "folder-library", 
      "groupBy": "none",
      "sortBy": "name",
      "commands": ["principle-md.openPreviewBeside"]
    }
  }
}

Then reference these in your provider mappings:

{
  "principle-md.providerMappings": [
    {
      "pattern": "research/**/*.md",
      "provider": "research-notes"
    }
  ]
}

3. Custom Provider Classes (Code-based)

For advanced use cases, you can create custom provider classes by extending the VS Code TreeDataProvider interface. This approach allows for:

• Custom metadata parsing (frontmatter, tags, etc.)
• Specialized file templates
• Custom grouping and sorting logic
• Integration with external APIs or databases

To create a custom provider class:

1. Create a new TypeScript file implementing vscode.TreeDataProvider<YourTreeItem>
2. Register the provider in your extension's activate function
3. Add corresponding commands and views to package.json

Example structure:

export class CustomProvider implements vscode.TreeDataProvider<CustomTreeItem> {
  // Implement required methods:
  // - getTreeItem(element: CustomTreeItem)
  // - getChildren(element?: CustomTreeItem)
  // - refresh()
}

For detailed examples and implementation guides, see the documentation files:

• docs/provider-mappings-ui-guide.md - Visual guide for provider mappings
• docs/user-configurable-providers.md - Complete guide for dynamic providers
• docs/creating-custom-providers.md - Advanced guide for custom provider classes

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:

1. Receive the markdown content.
2. Open a new, virtual markdown document with the received content.
3. 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