Home

Awesome

Marp for VS Code

CircleCI Codecov Visual Studio Marketplace Open VSX LICENSE

Create slide deck written in Marp Markdown on VS Code.

We will enhance your VS Code as the slide deck writer. Mark marp: true, and write your deck!

<p align="center"> <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/screenshot.png" width="800" /> </p>

See the documentation of Marpit Markdown and the features of Marp Core about how to write.

Please refer https://marp.app/ for more details of Marp ecosystem. We have powerful tools for Marp Markdown: Marpit Framework, CLI tool, Web interface and so on.

Usage

Marp features will be enabled when marp: true is written in a front-matter of Markdown document.

---
marp: true
---

# Your slide deck

Start writing!

You can create a new Marp Markdown document from "New File..." menu (<kbd>Alt</kbd> + <kbd>Ctrl</kbd> + <kbd>Win</kbd> + <kbd>N</kbd> / <kbd>Alt</kbd> + <kbd>Cmd</kbd> + <kbd>Ctrl</kbd> + <kbd>N</kbd>) to start writing a slide deck quickly.

<p align="center"> <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/new-file.gif" alt="Create Marp Markdown" width="500" /> </p>

marp: true also can toggle by opening the quick picker from toolbar icon <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/toolbar-icon.png" width="16" height="16" /> and selecting "Toggle Marp feature for current Markdown". (markdown.marp.toggleMarpFeature).

<p align="center"> <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/toggle.gif" alt="Toggle Marp preview" width="600" /> </p>

Features

Preview Marp Markdown

While enabled Marp features by marp: true, Marp for VS Code can preview your Marp Markdown with the same way as a built-in Markdown preview.

If you are not familiar with editing Markdown on VS Code, we recommend to learn what you can do in VS Code documentation at first.

IntelliSense for Marp directives

Directives, the inherited feature from Marpit framework, is an important syntax to write the deck in Marp.

If enabled Marp feature by marp: true, Marp for VS Code extends IntelliSense to support auto completion, syntax highlight, hover help, and diagnostics for Marp directives.

Auto completion

Marp for VS Code can suggest global/local directives supported by Marp ecosystem. We remember all so you may forget them! 😛

Hit <kbd>Ctrl</kbd> + <kbd>Space</kbd> within the front-matter or HTML comment to show the list of directives. You can peek the help of selected directive by hitting <kbd>Ctrl</kbd> + <kbd>Space</kbd> again.

<p align="center"> <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/auto-completion.gif" alt="Auto completion" width="400" /> </p>

Some directives such as theme and paginate are also supported auto completion for the value.

Highlight and hover help

The key of recognized directives are highlighted in the different color from the around. This visualization may help to find out meaningless definitions.

And you can see the help of a defined directive by hovering cursor on the recognized directive.

<p align="center"> <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/highlight-and-hover-help.png" alt="Highlight and hover help" width="426" /> </p>

Diagnostics

Marp for VS Code can detect some basic problems in Marp directives. Diagnostics will help following our recommended way for writing slides.

<p align="center"> <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/diagnostics.png" alt="Diagnostics" width="443" /> </p>
NameDescriptionQuick Fix
define-math-global-directiveRecommend to declare math typesetting library via math global directive✅
deprecated-color-setting-shorthandCheck deprecated shorthands for setting slide colors✅
deprecated-dollar-prefixCheck obsoleted directives prefixed by $✅
ignored-math-global-directiveReport ignored math global directive if disabled math by the extension setting
overloading-global-directiveFind out overloaded global directives
unknown-sizeNotify if the specified size preset was not defined in a theme
unknown-themeNotify a not recognized theme name

Export slide deck to HTML, PDF, PPTX, and image 🛡ī¸

We have integrated Marp CLI to export your deck into several formats.

To export the content of active Markdown editor, open the quick pick from Marp icon on toolbar <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/toolbar-icon.png" width="16" height="16" /> and select "Export slide deck...". (markdown.marp.export)

<p align="center"> <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/export.gif" alt="Export slide deck" width="600" /> </p>

You can also execute command from the Command Palette (<kbd>F1</kbd> or <kbd>Ctrl/Cmd+Shift+P</kbd>).

Supported file types

Default file type can choose by markdown.marp.exportType preference.

⚠ī¸ Export except HTML requires to install any one of Google Chrome, Chromium, or Microsoft Edge. You may also specify the custom path for Chrome / Chromium-based browser by preference markdown.marp.chromePath.

Use custom theme CSS 🛡ī¸

You can register and use custom theme CSS for Marpit / Marp Core by setting markdown.marp.themes, that includes remote URLs, or relative paths to local files in the current workspace.

// Please put `.vscode/settings.json` on your workspace
{
  "markdown.marp.themes": [
    "https://example.com/foo/bar/custom-theme.css",
    "./themes/your-theme.css"
  ]
}

It's very similar to a way for using custom styles in ordinary Markdown preview. The registered theme can use by specifying theme name in theme global directive.

/* @theme your-theme */

@import 'default';

section {
  background: #fc9;
}
---
marp: true
theme: your-theme
---

# Use your own theme

Markdown preview will reload updated theme CSS automatically when you edited the registered local CSS file. It's very useful for creating your own theme.

<p align="center"> <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/custom-theme.gif" alt="Use custom theme" width="600" /> </p>

Outline extension

When Marp Markdown is enabled, you can use the extended outline view like following. They are enabled by default but you may disable by markdown.marp.outlineExtension preference.

Outline view for each slide

We extend the outline view to support slide pages in Marp Markdown.

<p align="center"> <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/outline.png" alt="Outline view for each slide" width="400" /> </p>

ℹī¸ Please choose Sort By: Position from context menu of its panel if you see incorrect slide order.

Slide folding in editor

You can fold the content of slide in editor while editing Marp Markdown.

<p align="center"> <img src="https://raw.githubusercontent.com/marp-team/marp-vscode/main/docs/fold.gif" alt="Slide folding in editor" width="360" /> </p>

Security

Workspace Trust

Some features that may met malicious are restricted in the untrusted workspace/window. Please read VS Code's user guide for details.

Features may be restricted are marked by the shield icon 🛡ī¸ in this documentation. Marp for VS Code is available even if the current workspace is not trusted but you can use only a basic Marp preview and IntelliSense.

Enable HTML in Marp Markdown 🛡ī¸

You can enable previsualization of HTML code within Marp Markdown with the markdown.marp.enableHtml option.

It could allow script injection from untrusted Markdown files. Thus, this feature is disabled as a default and will be always ignored in the untrusted workspace. Use with caution.

Web extension

You can use Marp extension in VS Code for the Web environment like vscode.dev and github.dev. Try opening https://github.dev/marp-team/marp-vscode/blob/main/docs/example.md, with an environment that has installed Marp extension.

The web extension has some limitations:

Contributing

Are you interested in contributing? Please see CONTRIBUTING.md and the common contributing guideline for Marp team.

Author

Managed by @marp-team.

License

This extension releases under the MIT License.