crossnote 0.9.20 → 0.9.21

package/README.md

@@ -92,8 +92,20 @@ const config = {
   // This is useful for adding custom styles or scripts.
   includeInHeader: "",
 
-  // Enable this option will render markdown by pandoc instead of markdown-it.
-  usePandocParser: false,
+  // Markdown parser to use for rendering.
+  // Options: 'markdown-it' (default), 'pandoc', 'markdown_yo'
+  // - 'markdown-it': built-in markdown-it renderer
+  // - 'pandoc': render via Pandoc (requires Pandoc installed)
+  // - 'markdown_yo': high-performance renderer (see below); markdown-it is
+  //   still used for token-based operations (backlink extraction, etc.)
+  markdownParser: 'markdown-it',
+
+  // Path to the markdown_yo native binary.
+  // When set and markdownParser is 'markdown_yo', crossnote invokes this binary
+  // (via stdin/stdout) instead of the bundled WASM module.
+  // See the "markdown_yo" section below for performance guidance.
+  // Supports $HOME and ~ variable substitution. Default: '' (use WASM).
+  markdownYoBinaryPath: '',
 
   // In Markdown, a single newline character doesn't cause a line break in the generated HTML. In GitHub Flavored Markdown, that is not true. Enable this config option to insert line breaks in rendered HTML for single newlines in Markdown source.
   breakOnSingleNewLine: true,
@@ -300,6 +312,44 @@ If your notebook has `.crossnote` directory, then when you run `await Notebook.i
 └── style.less
 ```
 
+## markdown_yo (Experimental)
+
+Crossnote supports an optional high-performance markdown renderer called [markdown_yo](https://github.com/shd101wyy/markdown_yo), written in the [Yo programming language](https://github.com/shd101wyy/Yo) and compiled to WebAssembly. When enabled, it replaces markdown-it for HTML rendering while markdown-it is still used for token-based operations (backlink extraction, note mention processing, etc.).
+
+To enable it, set `markdownParser: 'markdown_yo'` in your notebook config.
+
+### Performance
+
+By default, crossnote uses the **WASM** build of markdown_yo. The WASM module is initialized once per notebook and reused for all subsequent renders. The table below shows steady-state render times (WASM module already loaded) measured on an x86_64 Linux machine, compared to the native binary invoked as a subprocess:
+
+| Input Size | markdown-it | WASM (pre-init) | Native binary (spawn) |
+| ---------- | ----------- | --------------- | --------------------- |
+| 60 KB      | ~1.6 ms     | ~1 ms           | ~2 ms                 |
+| 256 KB     | ~6.7 ms     | ~4 ms           | ~3 ms                 |
+| 1 MB       | ~28.8 ms    | ~83 ms          | ~64 ms                |
+| 18 MB      | ~722 ms     | ~344 ms         | ~246 ms               |
+
+_WASM times are measured in-process with a pre-initialized renderer (typical crossnote usage). Native binary times include process spawn + stdin/stdout I/O overhead._
+
+For very large files (≥1 MB), the native binary is ~1.3× faster than WASM because WASM's memory overhead grows with document size. For small files (<256 KB), WASM is comparable or slightly faster since there is no subprocess overhead.
+
+### Native Binary
+
+Pre-built binaries for Linux, macOS, and Windows are available at [github.com/shd101wyy/markdown_yo/releases](https://github.com/shd101wyy/markdown_yo/releases).
+
+To use a native binary instead of WASM, set `markdownYoBinaryPath`:
+
+```yaml
+markdownParser: markdown_yo
+markdownYoBinaryPath: /path/to/markdown_yo
+```
+
+Supports `$HOME` and `~` variable substitution. The `breakOnSingleNewLine` option is not supported by the native binary CLI and is silently ignored when this path is set.
+
+### Supported Features
+
+markdown_yo supports CommonMark, GFM tables, strikethrough, and these extensions: subscript, superscript, mark/highlight, math ($..$ / $$..$$), emoji shortcodes, wikilinks, CriticMarkup, abbreviations, definition lists, admonitions, callouts, footnotes, source maps, and line breaks.
+
 ## Development
 
 1.  Clone this project.