93 lines
4.2 KiB
Markdown
93 lines
4.2 KiB
Markdown
# Mermaid Preview
|
|
|
|
Preview Markdown as rendered HTML in a Nova preview tab, with Mermaid diagrams
|
|
drawn inline.
|
|
|
|
Nova already previews Markdown, but its renderer is static HTML and CSS — there
|
|
is no way to run a diagram library inside it. This extension takes the other
|
|
route: it renders your Markdown into an ordinary HTML page inside the workspace
|
|
and lets Nova preview *that*, which means anything a web page can do, the
|
|
preview can do.
|
|
|
|
## Using it
|
|
|
|
Open a Markdown file and choose **Extensions → Mermaid Preview → Preview
|
|
Markdown** (⌃⇧M), or right-click in the editor.
|
|
|
|
The generated page opens as a tab. Switch it to Preview once — **Editor →
|
|
Preview**, or the preview button in the tab bar — and Nova remembers that choice
|
|
for the file. From then on the tab stays a preview and refreshes itself as the
|
|
extension rewrites the page underneath it.
|
|
|
|
Split the two tabs side by side for the VS Code arrangement: source on the left,
|
|
preview on the right.
|
|
|
|
`.mmd` and `.mermaid` files are previewed as a single diagram.
|
|
|
|
## What gets rendered
|
|
|
|
CommonMark plus tables, strikethrough and autolinking, and:
|
|
|
|
- ```` ```mermaid ```` blocks, drawn as diagrams. Each one renders on its own, so
|
|
a diagram that fails to parse shows its error and its source in place instead
|
|
of blanking the document.
|
|
- Task lists, as real checkboxes.
|
|
- Headings, with ids, so a table of contents in the document links correctly.
|
|
- Images and links relative to the Markdown file, rewritten so they still
|
|
resolve from wherever the generated page lives.
|
|
- YAML front matter, hidden.
|
|
- Inline HTML, as written.
|
|
|
|
## Settings
|
|
|
|
| Setting | Default | |
|
|
| --- | --- | --- |
|
|
| Update preview | On save | On save, as you type, or only when asked. |
|
|
| Remove the generated page when its tab closes | On | Closing the preview, or the Markdown file, deletes the page. The shared assets go with the last one. |
|
|
| Theme | Auto | Auto follows the system appearance. Diagrams follow the same choice. |
|
|
| Content width | 860 | Maximum width of the text column, in pixels. Diagrams and tables may exceed it. |
|
|
| Generated files | `.nova/MermaidPreview` | Where generated pages and assets are written, relative to the preview root. |
|
|
|
|
**Extensions → Mermaid Preview → Remove Generated Files** deletes the lot.
|
|
|
|
## How it works, and what that costs
|
|
|
|
Nova has no API for contributing a previewer — an extension cannot supply the
|
|
contents of a preview tab. What it can do is write a file and open it, and Nova's
|
|
HTML preview is a real WebView that runs JavaScript. So:
|
|
|
|
1. The command writes `<preview root>/.nova/MermaidPreview/<name>-<hash>.html`,
|
|
containing your Markdown as data plus a few script tags.
|
|
2. Alongside it, once per project, go `markdown-it` and `mermaid` and this
|
|
extension's own stylesheet and page script (about 3.7 MB, copied only when
|
|
missing or out of date).
|
|
3. Nova previews that page. Rendering happens in the WebView, where Mermaid has
|
|
the DOM it needs to measure text and lay a diagram out.
|
|
4. Saving rewrites step 1 only — a couple of kilobytes — and the preview reloads.
|
|
5. Closing either tab deletes the page, and closing the last preview takes the
|
|
assets and the directory with it.
|
|
|
|
The consequences worth knowing about:
|
|
|
|
- **Generated files live in your project.** They have to: Nova's preview server
|
|
only serves what is under the preview root. They are deleted again when the
|
|
preview closes, but add `.nova/MermaidPreview/` to `.gitignore` anyway — a
|
|
crash or a force quit has no chance to tidy up.
|
|
- **The preview is a second tab**, not an alternate view of the Markdown file.
|
|
Nova's own Markdown preview still exists and is unchanged.
|
|
- **No scroll sync.** There is no way to reach into the preview WebView from an
|
|
extension. Scroll position does survive a reload.
|
|
- **Unsaved and remote files are not previewed** — there is no path to resolve
|
|
their images and links against.
|
|
|
|
## Installing
|
|
|
|
Run `./install.sh` with Nova quit; it copies the extension into Nova's user
|
|
extension directory and registers it. During development, **Extensions →
|
|
Activate Project as Extension** is quicker.
|
|
|
|
## Credits
|
|
|
|
Bundles [markdown-it](https://github.com/markdown-it/markdown-it) and
|
|
[Mermaid](https://mermaid.js.org), both MIT licensed.
|