@md-plugins/md-plugin-codeblocks 0.1.0-beta.2 → 0.1.0-beta.20

package/README.md

@@ -1,10 +1,11 @@
 # md-plugin-codeblocks
 
-A **Markdown-It** plugin that enhances code block rendering by providing syntax highlighting, line numbering, and support for advanced features like tabbed code blocks. It integrates with Prism.js for syntax highlighting and allows customization for various use cases.
+A **Markdown-It** plugin that enhances code block rendering by providing syntax highlighting, line numbering, and support for advanced features like tabbed code blocks. It integrates with Shiki for syntax highlighting and allows customization for various use cases.
 
 ## Features
 
-- **Syntax Highlighting**: Automatically highlights code blocks using **Prism.js**.
+- **Syntax Highlighting**: Automatically highlights code blocks using **Shiki**.
+- **TwoSlash Hovers**: Opt in to TypeScript-powered hover and query output for richer examples.
 - **Line Numbering**: Optionally adds line numbers to code blocks.
 - **Magic Comments**: Supports special comments like `[[! highlight]]`, `[[! add]]`, and `[[! rem]]` for inline code annotations.
 - **Tabbed Code Blocks**: Enables the creation of tabbed code blocks for multi-language or multi-file examples.
@@ -18,6 +19,8 @@ Install the plugin via your preferred package manager:
 ```bash
 # with pnpm:
 pnpm add @md-plugins/md-plugin-codeblocks
+# with bun:
+bun add @md-plugins/md-plugin-codeblocks
 # with Yarn:
 yarn add @md-plugins/md-plugin-codeblocks
 # with npm:
@@ -38,8 +41,8 @@ md.use(codeblocksPlugin, {
   copyButtonComponent: '<MarkdownCopyButton',
   preClass: 'markdown-code',
   pageScripts: [
-    "import MarkdownPrerender from 'src/.q-press/components/MarkdownPrerender'",
-    "import MarkdownCopyButton from 'src/.q-press/components/MarkdownCopyButton.vue'",
+    "import MarkdownPrerender from '@/.q-press/components/MarkdownPrerender'",
+    "import MarkdownCopyButton from '@/.q-press/components/MarkdownCopyButton.vue'",
   ],
 })
 ```
@@ -99,6 +102,17 @@ console.log('Line 3')
 ```
 ````
 
+### TwoSlash Type Hovers
+
+Add the `twoslash` attribute to TypeScript or JavaScript examples when you want inferred type information, compiler diagnostics, or `^?` query output.
+
+````markup
+```ts [twoslash]
+const count = 1
+//    ^?
+```
+````
+
 ### Line Highlighting and Annotations
 
 ````markup
@@ -177,6 +191,13 @@ pnpm test
 
 In case this README falls out of date, please refer to the [documentation](https://md-plugins.netlify.app/md-plugins/codeblocks/overview) for the latest information.
 
+## Support
+
+If md-plugin-codeblocks is useful in your workflow and you want to support ongoing maintenance:
+
+GitHub Sponsors: https://github.com/sponsors/hawkeye64
+PayPal: https://paypal.me/hawkeye64
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.

package/dist/index.d.mts

@@ -46,7 +46,7 @@ interface CodeblockPluginOptions {
      */
     pageScripts?: string[];
     /**
-     * Optional Prism languages configuration array. This allows you to override or add custom language definitions.
+     * Optional Shiki languages configuration array. This allows you to override or add custom language definitions.
      * Each item can have a `name`, optional `aliases`, and `customCopy` boolean.
      */
     langList?: Lang[];

package/dist/index.d.ts

@@ -46,7 +46,7 @@ interface CodeblockPluginOptions {
      */
     pageScripts?: string[];
     /**
-     * Optional Prism languages configuration array. This allows you to override or add custom language definitions.
+     * Optional Shiki languages configuration array. This allows you to override or add custom language definitions.
      * Each item can have a `name`, optional `aliases`, and `customCopy` boolean.
      */
     langList?: Lang[];

package/dist/index.mjs

@@ -1,5 +1,6 @@
-import prism from 'prismjs';
-import loadLanguages from 'prismjs/components/index.js';
+import { addClassToHast } from 'shiki/core';
+import { createHighlighter } from 'shiki';
+import { transformerNotationHighlight, transformerNotationDiff, transformerNotationFocus, transformerNotationErrorLevel, transformerNotationWordHighlight } from '@shikijs/transformers';
 
 function resolvePluginOptions(options, key, defaults) {
   if (options && typeof options === "object" && key in options) {
@@ -8,11 +9,175 @@ function resolvePluginOptions(options, key, defaults) {
   return { ...defaults, ...options };
 }
 
+const shikiLangs = [
+  "bash",
+  "css",
+  "diff",
+  "html",
+  "javascript",
+  "json",
+  "nginx",
+  "sass",
+  "scss",
+  "typescript",
+  "vue",
+  "xml",
+  "yaml"
+];
+const shikiLangAlias = {
+  js: "javascript",
+  markup: "html",
+  shell: "bash",
+  sh: "bash",
+  ts: "typescript",
+  yml: "yaml"
+};
+const highlighter = await createHighlighter({
+  themes: ["github-light", "github-dark"],
+  langs: shikiLangs,
+  langAlias: shikiLangAlias
+});
+const debugEnvValue = process.env.DEBUG;
+delete process.env.DEBUG;
+const twoslashModule = await import('@shikijs/twoslash').finally(() => {
+  if (debugEnvValue !== void 0) {
+    process.env.DEBUG = debugEnvValue;
+  }
+});
+const { rendererRich, transformerTwoslash } = twoslashModule;
+const supportedLangSet = new Set(highlighter.getLoadedLanguages());
+const themeOptions = {
+  themes: {
+    light: "github-light",
+    dark: "github-dark"
+  },
+  defaultColor: false
+};
+function normalizeShikiLang(lang) {
+  return supportedLangSet.has(lang) ? lang : "text";
+}
+function buildCodeBlockTransformers({
+  codeClass,
+  lineList,
+  maxheight,
+  preClass,
+  twoslash
+}) {
+  return [
+    preClassTransformer(preClass, maxheight),
+    codeClassTransformer(codeClass),
+    ...twoslash === true ? [twoslashTransformer] : [],
+    transformerNotationHighlight(),
+    transformerNotationDiff(),
+    transformerNotationFocus(),
+    transformerNotationErrorLevel(),
+    transformerNotationWordHighlight(),
+    lineDecorTransformer(lineList)
+  ];
+}
+const twoslashTransformer = transformerTwoslash({
+  renderer: rendererRich({
+    queryRendering: "line"
+  }),
+  twoslashOptions: {
+    compilerOptions: {
+      traceResolution: false
+    }
+  }
+});
+function preClassTransformer(preClass, maxheight) {
+  return {
+    name: "md-plugins:pre-class",
+    pre(node) {
+      addClassToHast(node, preClass);
+      if (maxheight !== void 0) {
+        const style = typeof node.properties?.style === "string" ? node.properties.style : "";
+        node.properties = {
+          ...node.properties,
+          style: `${style}${style.length > 0 ? ";" : ""}max-height:${maxheight}`
+        };
+      }
+    }
+  };
+}
+function codeClassTransformer(codeClass) {
+  return {
+    name: "md-plugins:code-class",
+    code(node) {
+      if (codeClass !== void 0 && codeClass.length > 0) {
+        addClassToHast(node, codeClass);
+      }
+    }
+  };
+}
+function lineDecorTransformer(lineList) {
+  return {
+    name: "md-plugins:line-decor",
+    code(codeNode) {
+      const lines = codeNode.children.filter(
+        (child) => child.type === "element" && child.tagName === "span" && lineHasClass(child, "line")
+      );
+      lines.forEach((line, index) => {
+        const target = lineList[index];
+        const classList = [...target?.classList ?? []];
+        const prefix = target?.prefix ?? [];
+        if (this.options.lang === "diff") {
+          const first = lineTextContent(line).charAt(0);
+          if (first === "+") {
+            classList.push("line-add");
+          } else if (first === "-") {
+            classList.push("line-rem");
+          }
+        }
+        if (classList.length > 0) {
+          line.children?.unshift({
+            type: "element",
+            tagName: "span",
+            properties: { class: ["c-line", ...classList] },
+            children: []
+          });
+        }
+        if (prefix.length > 0) {
+          line.children?.unshift({
+            type: "element",
+            tagName: "span",
+            properties: { class: "c-lpref" },
+            children: [{ type: "text", value: prefix.join(" ") }]
+          });
+        }
+      });
+    }
+  };
+}
+function lineHasClass(line, className) {
+  const classValue = line.properties?.class;
+  if (typeof classValue === "string") {
+    return classValue.split(/\s+/).includes(className);
+  }
+  if (Array.isArray(classValue)) {
+    return classValue.includes(className);
+  }
+  return false;
+}
+function lineTextContent(line) {
+  let acc = "";
+  const walk = (node) => {
+    if (node.type === "text") {
+      acc += node.value ?? "";
+      return;
+    }
+    node.children?.forEach(walk);
+  };
+  line.children?.forEach(walk);
+  return acc;
+}
+
 const defaultLangList = [
   { name: "markup" },
   { name: "bash", customCopy: true },
   { name: "javascript", aliases: "javascript|js" },
   { name: "typescript", aliases: "typescript|ts" },
+  { name: "yaml", aliases: "yaml|yml" },
   { name: "sass" },
   { name: "scss" },
   { name: "css" },
@@ -20,6 +185,7 @@ const defaultLangList = [
   { name: "xml" },
   { name: "nginx" },
   { name: "html" },
+  { name: "vue" },
   { name: "diff" }
   // special grammars
 ];
@@ -32,8 +198,8 @@ const DEFAULT_CODEBLOCK_PLUGIN_OPTIONS = {
   tabPanelTagName: "q-tab-panel",
   tabPanelTagClass: "q-pa-none",
   pageScripts: [
-    "import MarkdownPrerender from 'src/.q-press/components/MarkdownPrerender'",
-    "import MarkdownCopyButton from 'src/.q-press/components/MarkdownCopyButton.vue'"
+    "import MarkdownPrerender from '@/.q-press/components/MarkdownPrerender'",
+    "import MarkdownCopyButton from '@/.q-press/components/MarkdownCopyButton.vue'"
   ],
   langList: defaultLangList
 };
@@ -54,7 +220,6 @@ const codeblocksPlugin = (md, options) => {
     pageScripts = DEFAULT_CODEBLOCK_PLUGIN_OPTIONS.pageScripts,
     langList = defaultLangList
   } = resolvedOptions;
-  loadLanguages(langList.map((l) => l.name));
   const customCopyLangList = langList.filter((l) => l.customCopy === true).map((l) => l.name);
   const langMatch = langList.map((l) => l.aliases || l.name).join("|");
   const definitionLineRE = new RegExp(
@@ -71,11 +236,13 @@ const codeblocksPlugin = (md, options) => {
       const tabsMatch = line.match(tabsLineRE);
       if (tabsMatch !== null) {
         const { lang, attrs, title } = tabsMatch.groups || {};
-        currentTabName = title?.trim() || `Tab ${list.length + 1}`;
+        const bareAttrs = extractBareAttrs(title?.trim() || null);
+        currentTabName = bareAttrs.title ?? `Tab ${list.length + 1}`;
         list.push(currentTabName);
         tabMap[currentTabName] = {
           attrs: {
             ...parseAttrs(attrs?.trim() || null),
+            ...bareAttrs.attrs,
             lang
           },
           content: []
@@ -94,6 +261,7 @@ const codeblocksPlugin = (md, options) => {
     };
   }
   const magicCommentList = ["highlight", "rem", "add"];
+  const bareAttrList = ["twoslash"];
   const magicCommentRE = new RegExp(` *\\[\\[! (?<type>(${magicCommentList.join("|")}))\\]\\] *`);
   const magicCommentGlobalRE = new RegExp(magicCommentRE, "g");
   function extractCodeLineProps(lines, attrs) {
@@ -152,35 +320,25 @@ const codeblocksPlugin = (md, options) => {
     }
     return acc;
   }
-  function renderCodeBlock(html, codeClass2) {
-    return `<code${codeClass2 ? ` class="${codeClass2}"` : ""}>${html}</code>`;
-  }
-  function getPrismHighlightedContent(rawContent, lang) {
-    const content = rawContent.trim();
-    return prism.highlight(content, prism.languages[lang], lang);
-  }
   function getHighlightedContent(rawContent, attrs) {
-    const { lang, maxheight } = attrs;
+    const { lang, maxheight, twoslash } = attrs;
     let content = rawContent.trim();
     const lineList = parseCodeLine(content, attrs);
     if (lang !== "markup") {
       content = content.trim().replace(magicCommentGlobalRE, "");
     }
-    const html = getPrismHighlightedContent(content, lang).split("\n").map((line, lineIndex) => {
-      const target = lineList[lineIndex];
-      if (target === void 0) return line;
-      let lineHtml = "";
-      lineHtml += target.classList.length !== 0 ? `<span class="c-line ${target.classList.join(" ")}"></span>` : "";
-      lineHtml += target.prefix.length !== 0 ? `<span class="c-lpref">${target.prefix.join(" ")}</span>` : "";
-      lineHtml += line;
-      return lineHtml;
-    }).join("\n");
-    const preAttrs = maxheight !== void 0 ? ` style="max-height:${maxheight}"` : "";
     const langProp = customCopyLangList.includes(lang) === true ? ` lang="${lang}"` : "";
-    return (
-      // `<pre v-pre class="${preClass}${langClass}"${preAttrs}>` +
-      `<pre v-pre class="${preClass}"${preAttrs}>` + renderCodeBlock(html, codeClass) + `</pre><${copyButtonComponent}${langProp} />`
-    );
+    return highlighter.codeToHtml(content, {
+      lang: normalizeShikiLang(lang),
+      ...themeOptions,
+      transformers: buildCodeBlockTransformers({
+        codeClass,
+        lineList,
+        maxheight,
+        preClass: preClass ?? "markdown-code",
+        twoslash: twoslash === true || twoslash === "true"
+      })
+    }).replace("<pre ", "<pre v-pre ") + `<${copyButtonComponent}${langProp} />`;
   }
   function parseAttrs(rawAttrs) {
     if (rawAttrs === null) return {};
@@ -192,6 +350,27 @@ const codeblocksPlugin = (md, options) => {
     }
     return acc;
   }
+  function extractBareAttrs(title) {
+    if (title === null) {
+      return {
+        attrs: {},
+        title: null
+      };
+    }
+    const attrs = {};
+    const remainingTitle = [];
+    for (const chunk of title.split(/\s+/)) {
+      if (remainingTitle.length === 0 && bareAttrList.includes(chunk)) {
+        attrs[chunk] = true;
+        continue;
+      }
+      remainingTitle.push(chunk);
+    }
+    return {
+      attrs,
+      title: remainingTitle.length > 0 ? remainingTitle.join(" ") : null
+    };
+  }
   function parseDefinitionLine(token) {
     const match = token.info.trim().match(definitionLineRE);
     if (match === null) {
@@ -201,10 +380,12 @@ const codeblocksPlugin = (md, options) => {
       };
     }
     const { lang, attrs, title } = match.groups || {};
+    const bareAttrs = extractBareAttrs(title?.trim() || null);
     const acc = {
       ...parseAttrs(attrs?.trim() || null),
+      ...bareAttrs.attrs,
       lang,
-      title: title?.trim() || null
+      title: bareAttrs.title
     };
     if (acc.lang === "tabs") {
       acc.tabs = extractTabs(token.content);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@md-plugins/md-plugin-codeblocks",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.20",
   "description": "A markdown-it plugin for code blocks.",
   "keywords": [
     "markdown-it",
@@ -35,16 +35,18 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@shikijs/transformers": "^4.1.0",
+    "@shikijs/twoslash": "^4.1.0",
+    "shiki": "^4.1.0"
+  },
   "devDependencies": {
     "@types/markdown-it": "^14.1.2",
-    "@types/prismjs": "^1.26.6",
-    "markdown-it": "^14.1.1",
-    "prismjs": "^1.30.0",
-    "@md-plugins/shared": "0.1.0-beta.2"
+    "markdown-it": "^14.2.0",
+    "@md-plugins/shared": "0.1.0-beta.20"
   },
   "peerDependencies": {
-    "markdown-it": "^14.1.0",
-    "prismjs": "^1.29.0"
+    "markdown-it": "^14.2.0"
   },
   "scripts": {
     "build": "unbuild",