Initial Commit

2026-08-20 22:51:22 -03:00
commit 8a597e19a8
13 changed files with 5055 additions and 0 deletions
@@ -0,0 +1,92 @@
+# 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.