🖥️ Preview Plugin

This plugin provides the /preview note and /start live preview commands that render a note to HTML including:

• standard Markdown conversion (including referenced images)
• Mermaid diagrams (e.g. flowcharts, gantt charts, sequence diagrams ...)
• MathJax fragments or lines (for mathematical equations and notation)
• all open task and checklist types (according to user's Markdown settings) render as open tasks (using basic GFM rendering)
• some non-standard Markdown conversion (e.g. strikethrough, footnotes, tasklists and tables)
• it renders frontmatter slightly differently

It adds a 'Print (opens in system browser)' button to the preview window (on macOS). Clicking this opens the note in your default browser, where you can then select to print it. (There are limitations in the API that prevent me from making this a single button press, sorry.)

This example NotePlan note includes examples of these different capabilities.

Limitations

This is designed to be a temporary solution while we wait for similar functionality to get baked into the NotePlan app itself. To that end, I don't intend to be making many improvements to this. In particular I'm aware that:

• there are bugs in the rendering of frontmatter arising from one of the third-party libraries this uses.

Automatic updating

Use the /start live preview command to open the Preview window, and enable near-live update for this note. Under the hood this works by adding a trigger on the note so that the window will automatically refresh when you edit the note. This is the line it adds to the note's frontmatter block:

triggers: onEditorWillSave => np.Preview.updatePreview

It deliberately updates the Preview window without giving it focus, so that you can continue editing.

Preview a specified note (x-callback / other plugins)

From the Command Bar, /preview note always previews the currently open Editor note.

Other plugins and automations can preview any note (without opening it in the Editor first) by passing a note identifier as arg0:

noteplan://x-callback-url/runPlugin?pluginID=np.Preview&command=preview%20note&arg0=<encoded filename or identifier>

Examples of arg0:

• Filename: Projects/My%20Note.md
• Note title: My%20Note
• Relative date: today, yesterday, this%20week
• Calendar date string: 20260804

Optional arg1 sets the Mermaid theme (e.g. default, dark, forest). If omitted, the plugin picks default or dark from the current NotePlan theme.

If the specified note is open in the Editor, unsaved Editor content is used. Live preview (start live preview) still applies only to the note that has the trigger in the open Editor.

Mermaid charts

Mermaid is a third-party library that makes a wide variety of diagrams (including Flowcharts, Gantt, Kanban, state transition etc.) and some simple charts, using markdown-ish definitions. These definitions are placed in one or more fenced code blocks, like this:

``` mermaid
... chart definition
lines  ...
```  .

(Please ignore the closing period; it's just there to make this render in HTML.)

Please see Mermaid's own Tutorials.

Note: When online, Mermaid loads the latest v11.x from jsDelivr (mermaid@11). When offline (or if the CDN fails), the plugin falls back to a shipped official UMD snapshot in requiredFiles (currently 11.16.1). The offline file can lag behind the CDN until the next plugin release.

Developer's note: To refresh the offline snapshot for a release:

1. Bump the root package.json mermaid dependency (or download from jsDelivr).
2. Copy node_modules/mermaid/dist/mermaid.min.js to np.Preview/requiredFiles/[email protected].
3. Update that filename in plugin.json plugin.requiredFiles and the MERMAID_OFFLINE_FILENAME constant in src/previewMain.js.

If/when Mermaid releases v12, change the CDN URL major in src/previewMain.js (search for mermaid@11) and rebuild the plugin.

Theming Mermaid

The plugin automatically sets the Mermaid chart to use their 'default' or 'dark' theme according to the type of the current NotePlan theme. But you can override the theme for individual diagrams by including the following directive at the start of a Mermaid definition:

%%{init: {'theme':'forest'}}%%

MathJax rendering

This provides a way to include complex mathematical expressions either inline or in separate paragraphs, as this example shows:

When \\(a \ne 0\\), there are two solutions to \\(ax^2 + bx + c = 0\\), and they are:
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$

Thanks

To the people who've spend the time to create and maintain Mermaid, MathJax and the showdown library.

Support

If you find an issue with this plugin, or would like to suggest new features for it, please raise a Bug or Feature 'Issue' in GitHub.

If you would like to support my late-night work extending NotePlan through writing these plugins, you can through

Thanks!

Changes

Please see the CHANGELOG.