vite-plugin-svelte-md 0.3.0 → 0.4.0

package/README.md

@@ -16,7 +16,7 @@ _`vite-plugin-svelte-md` is heavily inspired by [vite-plugin-md](https://github.
 
 ## 📛 Features
 
-This plugin converts markdown files to Svelte component templates.  
+This plugin converts markdown files to Svelte component templates.<br>
 Combined with [the Svelte plugin](https://github.com/sveltejs/vite-plugin-svelte), you can convert markdown files to Svelte components.
 
 For example, Input:
@@ -135,6 +135,7 @@ import svelteMd from "vite-plugin-svelte-md";
 svelteMd({
   headEnabled: true,
   markdownItOptions: {},
+  use: (md) => { /* ... */ },
   markdownItUses: [],
   wrapperClasses: "markdown-body",
 });
@@ -146,12 +147,28 @@ Enables head tag generation from frontmatter. The default is `true`.
 
 #### `markdownItOptions`
 
-[markdown-it](https://github.com/markdown-it/markdown-it)'s option.
-See [markdown-it's docs](https://markdown-it.github.io/markdown-it/) for more details.
+[markdown-exit](https://github.com/serkodev/markdown-exit)'s option.
+See [markdown-exit's docs](https://markdown-exit.pages.dev/reference/api/Interface.MarkdownExitOptions.html) for more details.
+
+markdown-exit is a TypeScript rewrite of [markdown-it](https://github.com/markdown-it/markdown-it), designed as a drop-in replacement. The name `markdownItOptions` was preserved for backwards compatibility.
+
+#### `use`
+
+A hook to register [markdown-exit](https://github.com/serkodev/markdown-exit) or [markdown-it](https://github.com/markdown-it/markdown-it) plugins, in a type-safe way.
+
+Example:
+
+```js
+svelteMd({
+  use: (md) => md.use(plugin1).use(plugin2, options),
+});
+```
+
+Note: you may encounter benign type errors when using markdown-it plugins that are not yet compatible with markdown-exit.
 
 #### `markdownItUses`
 
-An array of [markdown-it](https://github.com/markdown-it/markdown-it)'s plugins.
+An array of [markdown-exit](https://github.com/serkodev/markdown-exit) or [markdown-it](https://github.com/markdown-it/markdown-it) plugins.
 
 Example:
 
@@ -161,10 +178,112 @@ svelteMd({
 });
 ```
 
+You should favor `use` over `markdownItUses` as it enables better auto-completion and type-safety.
+
 #### `wrapperClasses`
 
 The class name of the div that wraps the content.
 
+## 🎏 Comparison
+
+`vite-plugin-svelte-md` is not the only library that converts Markdown to Svelte components:
+
+<table>
+  <tr>
+    <th></th>
+    <th>
+      <a href="https://github.com/ota-meshi/vite-plugin-svelte-md">ota-meshi/vite-plugin-svelte-md</a>
+    </th>
+    <th>
+      <a href="https://github.com/pngwn/MDsveX">pngwn/MDsveX</a>
+    </th>
+  </tr>
+  <tr>
+    <td>Popularity</td>
+    <td><a href="https://npmx.dev/package/vite-plugin-svelte-md"><img alt="NPM Downloads" src="https://img.shields.io/npm/dw/vite-plugin-svelte-md?style=flat-square&color=d73d36"></a> <a href="https://github.com/ota-meshi/vite-plugin-svelte-md"><img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/ota-meshi/vite-plugin-svelte-md?style=flat-square&color=eac54f"></a></td>
+    <td><a href="https://npmx.dev/package/mdsvex"><img alt="NPM Downloads" src="https://img.shields.io/npm/dw/mdsvex?style=flat-square&color=d73d36"></a> <a href="https://github.com/pngwn/MDsveX"><img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/pngwn/MDsveX?style=flat-square&color=eac54f"></a></td>
+  </tr>
+  <tr>
+    <td>License</td>
+    <td><a href="https://github.com/ota-meshi/vite-plugin-svelte-md/blob/main/LICENSE">MIT</a></td>
+    <td><a href="https://github.com/pngwn/MDsveX/blob/main/LICENSE">MIT</a></td>
+  </tr>
+  <tr>
+    <th colspan="3">Architecture</th>
+  </tr>
+  <tr>
+    <td>Markdown parser</td>
+    <td><a href="https://npmx.dev/package/markdown-exit">markdown-exit</a> (supports sync and async plugins)</td>
+    <td><a href="https://npmx.dev/package/remark">remark</a> + <a href="https://npmx.dev/package/rehype">rehype</a>  (supports plugins)</td>
+  </tr>
+  <tr>
+    <td>Transformation step</td>
+    <td>Vite plugin (compatible with other Vite plugins, e.g. <a href="https://svelte.dev/docs/kit/images#sveltejs-enhanced-img"><code>@sveltejs/enhanced-img</code></a>)</td>
+    <td>Svelte preprocessor</td>
+  </tr>
+  <tr>
+    <th colspan="3">Features</th>
+  </tr>
+  <tr>
+    <td>Frontmatter</td>
+    <td><a href="https://npmx.dev/package/gray-matter">✅ (YAML, JSON or JS)</a><br>
+    Accessible through <code>{frontmatter.variable}</code></td>
+    <td>✅ (YAML, <a href="https://mdsvex.pngwn.io/docs#frontmatter">can be changed</a>)<br>
+    Accessible through <code>{variable}</code>
+    </td>
+  </tr>
+  <tr>
+    <td><code>&lt;head></code> tag generation</td>
+    <td>✅ (from frontmatter, <a href="#headenabled">can be disabled</a>)</td>
+    <td>⚙️ (possible with layouts)</td>
+  </tr>
+  <tr>
+    <td>Syntax highlighting</td>
+    <td>⚙️ (bring your own in <a href="https://github.com/markdown-it/markdown-it#syntax-highlighting"><code>markdownItOptions.highlight</code></a>)</td>
+    <td>✅ (defaults to <a href="https://github.com/PrismJS/prism/">Prism</a>, <a href="https://mdsvex.pngwn.io/docs#highlight">can be changed</a>)</td>
+  </tr>
+  <tr>
+    <td>Replace any HTML tag after Markdown processing</td>
+    <td>❌</td>
+    <td><a href="https://mdsvex.pngwn.io/docs#custom-components">✅</a></td>
+  </tr>
+  <tr>
+    <td>Layout</td>
+    <td>Optional wrapper <code>&lt;div></code> with classes</td>
+    <td>Svelte components, configurable in frontmatter</td>
+  </td>
+  <tr>
+    <td>Fancy typography replacements<br>(e.g. <code>...</code> → <code>…</code>)</td>
+    <td>✅</td>
+    <td>✅</td>
+  </tr>
+  <tr>
+    <td>+page.md (in SvelteKit)</td>
+    <td>✅</td>
+    <td>✅</td>
+  </tr>
+</table>
+
+## 🍊 Svelte Compatibility
+
+You might encounter issues with markdown-it plugins that produce invalid Svelte code, e.g. a TeX plugin that outputs unescaped `{` and `}` characters. In this case, the simplest workaround is to wrap the plugin output in a Svelte [`{@html ...}`](https://svelte.dev/docs/svelte/@html) tag:
+
+```js
+import { tex } from '@mdit/plugin-tex';
+import katex from 'katex';
+
+mdSvelte({
+  use: (md) =>
+    md.use(tex, {
+      // `katex.renderToString` produces HTML with unescaped `{` and `}` characters,
+      // wrap its output with {@html JSON.stringify(...)} to avoid Svelte parsing errors.
+      render: (content, displayMode) =>
+        `{@html ${JSON.stringify(katex.renderToString(content, { displayMode }))}}`,
+    }),
+});
+
+```
+
 ## :beers: Contributing
 
 Welcome contributing!

package/lib/markdown-it-svelte-curly-braces-escape/index.d.ts

@@ -1,5 +1,5 @@
-import type MarkdownIt from "markdown-it";
+import type { MarkdownExit } from "markdown-exit";
 /**
  * Escape curly braces in code block plugin
  */
-export default function plugin(md: MarkdownIt): void;
+export default function plugin(md: MarkdownExit): void;

package/lib/markdown-it-svelte-curly-braces-escape/index.js

@@ -4,15 +4,15 @@ import { escapeBraces } from "../utils.js";
  */
 export default function plugin(md) {
     const originalCodeBlock = md.renderer.rules.code_block;
-    md.renderer.rules.code_block = (...args) => {
-        return escapeBraces(originalCodeBlock(...args));
+    md.renderer.rules.code_block = async (...args) => {
+        return escapeBraces(await originalCodeBlock(...args));
     };
     const originalCodeInline = md.renderer.rules.code_inline;
-    md.renderer.rules.code_inline = (...args) => {
-        return escapeBraces(originalCodeInline(...args));
+    md.renderer.rules.code_inline = async (...args) => {
+        return escapeBraces(await originalCodeInline(...args));
     };
     const originalFence = md.renderer.rules.fence;
-    md.renderer.rules.fence = (...args) => {
-        return escapeBraces(originalFence(...args));
+    md.renderer.rules.fence = async (...args) => {
+        return escapeBraces(await originalFence(...args));
     };
 }

package/lib/markdown-it-svelte-tags/index.d.ts

@@ -1,5 +1,5 @@
-import type MarkdownIt from "markdown-it";
+import type { MarkdownExit } from "markdown-exit";
 /**
  * Svelte tags (e.g. `<svelte:head>`) plugin
  */
-export default function plugin(md: MarkdownIt): void;
+export default function plugin(md: MarkdownExit): void;

package/lib/markdown.d.ts

@@ -1,5 +1,5 @@
 import type { ResolvedOptions } from "./options.ts";
-export type MarkdownProcessor = (id: string, text: string) => string;
+export type MarkdownProcessor = (id: string, text: string) => Promise<string>;
 /**
  * Creates md processor
  */

package/lib/markdown.js

@@ -1,4 +1,4 @@
-import MarkdownIt from "markdown-it";
+import { createMarkdownExit } from "markdown-exit";
 import grayMatter from "gray-matter";
 import markdownItSvelteTags from "./markdown-it-svelte-tags/index.js";
 import markdownItSvelteCurlyBracesEscape from "./markdown-it-svelte-curly-braces-escape/index.js";
@@ -69,14 +69,13 @@ function parseHtml(html) {
  * Creates md processor
  */
 export function createMarkdownProcessor(options) {
-    const markdownIt = new MarkdownIt({
+    const markdownIt = createMarkdownExit({
         html: true,
         linkify: true,
         typographer: true,
         ...options.markdownItOptions,
     });
     markdownIt.linkify.set({ fuzzyLink: false });
-    // eslint-disable-next-line @typescript-eslint/unbound-method -- ignore
     const originalValidateLink = markdownIt.validateLink;
     markdownIt.validateLink = (url) => {
         if (!originalValidateLink(url)) {
@@ -85,16 +84,17 @@ export function createMarkdownProcessor(options) {
         return !IS_SVELTE_TAG_NAME_RE.test(url);
     };
     markdownIt.use(markdownItSvelteTags).use(markdownItSvelteCurlyBracesEscape);
+    options.use?.(markdownIt);
     options.markdownItUses.forEach((e) => {
         const [plugin, ...opts] = toArray(e);
         markdownIt.use(plugin, ...opts);
     });
-    return (id, text) => {
+    return async (id, text) => {
         const raw = text.trimEnd();
         const { wrapperClasses, headEnabled } = options;
         const parsedFrontmatter = grayMatter(raw);
         const plainMarkdown = parsedFrontmatter?.content ?? raw;
-        let html = markdownIt.render(plainMarkdown, { id });
+        let html = await markdownIt.renderAsync(plainMarkdown, { id });
         if (wrapperClasses) {
             html = `<div class="${wrapperClasses}">${html}</div>`;
         }

package/lib/options.d.ts

@@ -1,4 +1,4 @@
-import type * as MarkdownIt from "markdown-it";
+import type { MarkdownExit, MarkdownExitOptions } from "markdown-exit";
 export interface Options {
     /**
      * Enable head support
@@ -7,13 +7,22 @@ export interface Options {
      */
     headEnabled?: boolean;
     /**
-     * Options passed to Markdown It
+     * Options passed to Markdown Exit
      */
-    markdownItOptions?: MarkdownIt.Options;
+    markdownItOptions?: MarkdownExitOptions;
     /**
-     * Plugins for Markdown It
+     * Plugins for Markdown Exit
+     *
+     * @example
+     *    use: (md) => md.use(plugin1).use(plugin2, options)
+     */
+    use?: (md: MarkdownExit) => void;
+    /**
+     * Plugins for Markdown Exit
+     *
+     * Prefer the `use` option for better type safety
      */
-    markdownItUses?: (MarkdownIt.PluginSimple | [MarkdownIt.PluginSimple | MarkdownIt.PluginWithOptions, any] | any)[];
+    markdownItUses?: any[];
     /**
      * Class names for wrapper div
      *
@@ -23,7 +32,7 @@ export interface Options {
     include?: (string | RegExp)[] | string | RegExp | undefined;
     exclude?: (string | RegExp)[] | string | RegExp | undefined;
 }
-export type ResolvedOptions = Required<Omit<Options, "include" | "exclude">> & Pick<Options, "include" | "exclude"> & {
+export type ResolvedOptions = Required<Omit<Options, "include" | "exclude" | "use">> & Pick<Options, "include" | "exclude" | "use"> & {
     wrapperClasses: string;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-svelte-md",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Vite plugin to convert markdown to svelte template",
   "files": [
@@ -40,7 +40,8 @@
     "vite-plugin",
     "svelte",
     "markdown",
-    "markdown-it"
+    "markdown-it",
+    "markdown-exit"
   ],
   "author": "Yosuke Ota",
   "funding": "https://github.com/sponsors/ota-meshi",
@@ -53,8 +54,10 @@
     "vite": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-beta.0"
   },
   "dependencies": {
+    "@types/linkify-it": "^5.0.0",
+    "@types/mdurl": "^2.0.0",
     "gray-matter": "^4.0.3",
-    "markdown-it": "^14.0.0"
+    "markdown-exit": "^1.0.0-beta.8"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.5",
@@ -62,7 +65,6 @@
     "@ota-meshi/eslint-plugin": "^0.20.0",
     "@svitejs/changesets-changelog-github-compact": "^1.2.0",
     "@types/escape-html": "^1.0.1",
-    "@types/markdown-it": "^14.0.0",
     "@types/node": "^24.0.0",
     "@types/prismjs": "^1.16.6",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -73,9 +75,9 @@
     "eslint-config-prettier": "^10.0.0",
     "eslint-plugin-jsdoc": "^62.0.0",
     "eslint-plugin-json-schema-validator": "^6.0.0",
-    "eslint-plugin-jsonc": "^2.0.0",
+    "eslint-plugin-jsonc": "^3.0.0",
     "eslint-plugin-n": "^17.0.0",
-    "eslint-plugin-node-dependencies": "^1.0.0",
+    "eslint-plugin-node-dependencies": "^2.0.0",
     "eslint-plugin-prettier": "^5.0.0",
     "eslint-plugin-regexp": "^3.0.0",
     "prettier": "^3.0.0",