marp-vscode

# Marp for VS Code **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!

See the documentation of [Marpit Markdown](https://marpit.marp.app/markdown) and [the features of Marp Core](https://github.com/marp-team/marp-core#features) about how to write. > Please refer **[https://marp.app/][marp]** for more details of Marp ecosystem. We have powerful tools for Marp Markdown: [Marpit Framework](https://marpit.marp.app/), [Marp Core](https://github.com/marp-team/marp-core), [CLI tool](https://github.com/marp-team/marp-cli) and so on. [marp]: https://marp.app/ ## Usage Marp features will be enabled when `marp: true` is written in a front-matter of Markdown document. ```markdown --- marp: true --- # Your slide deck Start writing! ``` You can create a new Marp Markdown document from **"New File..."** menu (Alt + Ctrl + Win + N / Alt + Cmd + Ctrl + N) to start writing a slide deck quickly.

`marp: true` also can toggle by opening the quick picker from toolbar icon and selecting **"Toggle Marp feature for current Markdown"**. (`markdown.marp.toggleMarpFeature`).

## 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](https://code.visualstudio.com/docs/languages/markdown#_markdown-preview). In the preview, an active slide is highlighted based on the current position of the editor, as like as the regular Markdown preview. To disable this highlight, you can set `markdown.preview.markEditorSelection` setting to `false`. > [!NOTE] > If you are not familiar with editing Markdown on VS Code, we recommend to learn what you can do in [VS Code documentation](https://code.visualstudio.com/docs/languages/markdown) at first. ### IntelliSense for Marp directives [Directives](https://marpit.marp.app/directives), the inherited feature from [Marpit framework](https://marpit.marp.app/), is an important syntax to write the deck in Marp. If enabled Marp feature by `marp: true`, Marp for VS Code extends [IntelliSense](https://code.visualstudio.com/docs/editor/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 Ctrl + Space within [the front-matter](https://marpit.marp.app/directives?id=front-matter) or [HTML comment](https://marpit.marp.app/directives?id=html-comment) to show the list of directives. You can peek the help of selected directive by hitting Ctrl + Space again.

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.

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

| Name | Description | [Quick Fix] | | :----------------------------------- | :------------------------------------------------------------------------------------------------- | :---------: | | `define-math-global-directive` | Recommend to declare math typesetting library via [`math` global directive][math global directive] | ✅ | | `deprecated-color-setting-shorthand` | Check [obsoleted shorthands for setting slide colors][color setting shorthand] | ✅ | | `deprecated-dollar-prefix` | Check [obsoleted directives prefixed by `$`][dollar-prefix] | ✅ | | `ignored-math-global-directive` | Report ignored `math` global directive if disabled math by the extension setting | | | `overloading-global-directive` | Find out overloaded global directives | | | `unknown-size` | Notify if the specified [size preset] was not defined in a theme | | | `unknown-theme` | Notify a not recognized theme name | | [quick fix]: https://code.visualstudio.com/docs/editor/refactoring#_code-actions-quick-fixes-and-refactorings [dollar-prefix]: https://github.com/marp-team/marpit/issues/182 [color setting shorthand]: https://github.com/marp-team/marpit/issues/331 [math global directive]: https://github.com/marp-team/marp-core#math-global-directive [size preset]: https://github.com/marp-team/marp-core/tree/main/themes#size-name-width-height ##### Experimental diagnostics Some of diagnostics are experimental. You can enable or disable them in the extension settings. Refer to ["Experimental settings"](#experimental-settings). | Name | Description | [Quick Fix] | | :-------------------------- | :---------------------------------------------------------------------------------------------- | :---------: | | `slide-content-overflow` | Warn when the slide content in a preview overflows the safe area defined by the slide’s padding | | ### Export slide deck to HTML, PDF, PPTX, and image ️ We have integrated [Marp CLI][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 and select **"Export slide deck..."**. (`markdown.marp.export`)

You can also execute command from the Command Palette (F1 or Ctrl/Cmd+Shift+P). [marp-cli]: https://github.com/marp-team/marp-cli/ #### Supported file types - **HTML** - **PDF** - **PPTX** (PowerPoint document) - **PNG** (_First slide only)_ - **JPEG** (_First slide only)_ - **TXT** (_Notes only)_ Default file type can choose by the `markdown.marp.exportType` setting. > [!IMPORTANT] > Exporting PDF, PPTX, and image formats requires to install any one of [Google Chrome](https://www.google.com/chrome/), [Chromium](https://www.chromium.org/), [Microsoft Edge](https://www.microsoft.com/edge), or [Firefox](https://www.mozilla.org/firefox/). You may control using browser and the custom path for the browser by `markdown.marp.browser` and `markdown.marp.browserPath` settings. > [!NOTE] > A legacy setting `markdown.marp.chromePath` is deprecated since v2. Please use `markdown.marp.browserPath` instead. #### Integration with AI agent Marp for VS Code also provides [the export tool](https://code.visualstudio.com/docs/chat/chat-tools) to [VS Code built-in AI agent](https://code.visualstudio.com/docs/agents/overview). By instructing in chat to export Markdown in the specified file format, AI agent can process the export using preferences in the current workspace.

### Use custom theme CSS ️ You can register and use [custom theme CSS for Marpit](https://marpit.marp.app/theme-css) / [Marp Core](https://github.com/marp-team/marp-core/tree/main/themes#readme) by setting `markdown.marp.themes`, that includes remote URLs, or relative paths to local files in the current workspace. ```javascript // 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](https://code.visualstudio.com/docs/languages/markdown#_using-your-own-css). The registered theme can use by specifying theme name in [`theme` global directive](https://marpit.marp.app/directives?id=theme). ```css /* @theme your-theme */ @import 'default'; section { background: #fc9; } ``` ```markdown --- 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.

### Outline extension When Marp Markdown is enabled, you can use the extended [outline view](https://code.visualstudio.com/docs/languages/markdown#_outline-view) like following. They are enabled by default but you may disable by the `markdown.marp.outlineExtension` setting. #### Outline view for each slide We extend the outline view to support slide pages in Marp Markdown.

> [!TIP] > > 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.

### Security #### [Workspace Trust] Some features that may met malicious are restricted in the untrusted workspace/window. Please read [VS Code's user guide][workspace trust] 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. [workspace trust]: https://code.visualstudio.com/docs/editing/workspaces/workspace-trust #### HTML elements in Markdown ️ In the trusted workspace, if Marp Markdown was included HTML elements, [only selectivity HTML elements by Marp](https://github.com/marp-team/marp-core/blob/main/src/html/allowlist.ts) can render by default. You can control which HTML elements will be rendered by setting the `markdown.marp.html` option, You can control which HTML elements will be rendered by setting the `markdown.marp.html` option. You can set it as `all` to allow all HTML elements, but could allow script injection from untrusted Markdown files. Use with caution. In the untrusted workspace, HTML elements in Marp Markdown will be always ignored regardless of the selected option in `markdown.marp.html`. > [!NOTE] > A legacy setting `markdown.marp.enableHtml` is deprecated since v2. Please use `markdown.marp.html` instead. ## Experimental settings Some of settings are marked as experimental. These feature may be unstable and change the spec in the future. ### [`markdown.marp.diagnostics.slideContentOverflow`](https://github.com/marp-team/marp-vscode/issues/519) Enables a diagnostic that warns when slide content overflows the safe area defined by the slide’s padding. This diagnostic is only available while the Markdown preview is open. It is helpful for identifying some potential presentation issues, such as cropped content, excessive content on a single page, and an unnatural layouts. ### [`markdown.marp.openExportedHtmlInIntegratedBrowser`](https://github.com/marp-team/marp-vscode/pull/555) Use [VS Code integrated browser](https://code.visualstudio.com/docs/debugtest/integrated-browser) to open the exported HTML file when `markdown.marp.exportAutoOpen` setting is enabled. It requires VS Code v1.109 and later. This allows users to play presentations in VS Code tabs or external windows. - `off`: The exported HTML will open in the external browser app. - `tab`: The exported HTML will open in VS Code integrated browser as a new tab. - `window`: The exported HTML