@md-plugins/md-plugin-codeblocks 0.1.0-alpha.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024-present, Jeff Galbraith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# 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.
+
+## Features
+
+- **Syntax Highlighting**: Automatically highlights code blocks using **Prism.js**.
+- **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.
+- **Customizable Components**: Supports custom wrapper and copy button components.
+- **Fallback for Unsupported Languages**: Gracefully handles code blocks written in unsupported languages.
+
+## Installation
+
+Install the plugin via your preferred package manager:
+
+```bash
+# With npm:
+npm install @md-plugins/md-plugin-codeblocks
+# Or with Yarn:
+yarn add @md-plugins/md-plugin-codeblocks
+# Or with pnpm:
+pnpm add @md-plugins/md-plugin-codeblocks
+```
+
+## Usage
+
+### Basic Setup
+
+```js
+import MarkdownIt from 'markdown-it';
+import { codeblocksPlugin } from '@md-plugins/md-plugin-codeblocks';
+
+const md = new MarkdownIt();
+md.use(codeblocksPlugin, {
+  containerComponent: 'MarkdownPrerender',
+  copyButtonComponent: '<MarkdownCopyButton',
+  preClass: 'markdown-code',
+  pageScripts: [
+    "import MarkdownPrerender from 'src/components/md/MarkdownPrerender'",
+    "import MarkdownCopyButton from 'src/components/md/MarkdownCopyButton.vue'",
+  ],
+});
+```
+
+## Example Markdown Input
+
+```javascript
+console.log('Hello, world!');
+```
+
+### Example Output
+
+The rendered output will include syntax-highlighted code wrapped in customizable components:
+
+```html
+<markdown-prerender>
+  <pre v-pre class="markdown-code language-javascript">
+    <code>
+      console<span class="token punctuation">.</span>
+      <span class="token function">log</span>
+      <span class="token punctuation">(</span>
+      <span class="token string">'Hello, world!'</span>
+      <span class="token punctuation">)</span>
+      <span class="token punctuation">;</span>
+    </code>
+  </pre>
+  <markdown-copy-button></markdown-copy-button>
+</markdown-prerender>
+```
+
+## Options
+
+The `md-plugin-codeblocks` plugin supports the following options:
+
+| Option              | Type   | Default                | Description                                                    |
+| ------------------- | ------ | ---------------------- | -------------------------------------------------------------- |
+| defaultLang         | string | 'markup'               | Default language for code blocks without a specified language. |
+| containerComponent  | string | 'markdown-prerender'   | Custom wrapper component for code blocks.                      |
+| copyButtonComponent | string | 'markdown-copy-button' | Custom copy button component.                                  |
+| preClass            | string | 'markdown-code'        | CSS class for the `<pre>` element.                             |
+| codeClass           | string | ''                     | CSS class for the `<code>` element.                            |
+| linePrefixClass     | string | 'line-'                | Prefix for classes used in line annotations.                   |
+| tabPanelTagName     | string | 'q-tab-panel'          | Tag name for the tab panels.                                   |
+| tabPanelTagClass    | string | 'q-pa-none'            | CSS class for the tab panels.                                  |
+
+## Advanced Features
+
+### Line Numbering
+
+The plugin supports magic comments for inline annotations:
+
+```js [numbered]
+// All lines will be numbered
+console.log('Line 1');
+console.log('Line 2');
+console.log('Line 3');
+```
+
+### Line Highlighting and Annotations
+
+````markdown
+```js [highlight=2]
+console.log('Line 1');
+console.log('Line 2'); // This line will be highlighted
+console.log('Line 3');
+```
+````
+
+````markdown
+```js
+console.log('Line 1');
+console.log('Line 2');
+[[highlight]]; // This line will be highlighted
+console.log('Line 3');
+```
+````
+
+````markdown
+```js [add=2]
+console.log('Line 1');
+console.log('Line 2'); // This line will be accented and prefixed with a '+'
+console.log('Line 3');
+```
+````
+
+````markdown
+```js [rem=2]
+console.log('Line 1');
+console.log('Line 2'); // This line will be accented and prefixed with a '-'
+console.log('Line 3');
+```
+````
+
+#### Combining Annotations
+
+````markdown
+```js [numbered highlight=1 rem=2 add=3]
+console.log('Line 1'); // This line will be highlighted
+console.log('Line 2'); // This line will be accented and prefixed with a '-'
+console.log('Line 3'); // This line will be accented and prefixed
+```
+````
+
+### Using Ranges
+
+Additonally, with the exception of `numbered`, you can use ranges to annotate multiple lines:
+
+```markdown
+[highlight=1,10-11 add=4,7-9 rem=12-14]
+```
+
+### Tabbed Code Blocks
+
+Easily create tabbed interfaces for multiple code examples:
+
+````markdown
+```tabs
+<<|js Tab 1|>>
+console.log('Hello from Tab 1');
+
+<<|ts Tab 2|>>
+console.log('Hello from Tab 2');
+```
+````
+
+## Testing
+
+Run the unit tests with `Vitest`:
+
+```bash
+pnpm test
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.

package/dist/index.d.mts

@@ -0,0 +1,77 @@
+import { PluginWithOptions } from 'markdown-it';
+
+interface CodeblockPluginOptions {
+    /**
+     * The default language to use if none is detected.
+     * @default 'markup'
+     */
+    defaultLang?: string;
+    /**
+     * The component used to wrap code blocks.
+     * @default 'markdown-prerender'
+     */
+    containerComponent?: string;
+    /**
+     * The component used to render the copy button.
+     * @default 'markdown-copy-button'
+     */
+    copyButtonComponent?: string;
+    /**
+     * The comonent name for the tab panel.
+     * @default 'q-tab-panel'
+     */
+    tabPanelTagName?: string;
+    /**
+     * The class(es) to be used with the tab panel.
+     * @default 'q-pa-none'
+     */
+    tabPanelTagClass?: string;
+    /**
+     * The class to be used for the line added.
+     * @default 'line-add'
+     */
+    lineAddClass?: string;
+    /**
+     * The prefix to be used for magic classes.
+     * The 3 magic classes are `add`, `rem`, and `highlight`.
+     * Classes in your code are then prefixed with this prefix.
+     * @default 'line-'
+     * The final class names would be: `line-add`, `line-rem`, `line-highlight`.
+     */
+    linePrefixClass?: string;
+    /**
+     * The class to be used for the pre tag.
+     * @default 'markdown-pre'
+     */
+    preClass?: string;
+    /**
+     * The class to be used for the code tag (ok to be empty).
+     * @default 'markdown-code'
+     */
+    codeClass?: string;
+    /**
+     * An array of page scripts to be included.
+     */
+    pageScripts?: string[];
+    /**
+     * Optional Prism 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?: Array<{
+        name: string;
+        aliases?: string;
+        customCopy?: boolean;
+    }>;
+}
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * An array of page script (import statements) to be included.
+         */
+        pageScripts?: Set<string>;
+    }
+}
+
+declare const codeblocksPlugin: PluginWithOptions<CodeblockPluginOptions>;
+
+export { type CodeblockPluginOptions, codeblocksPlugin };

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import { PluginWithOptions } from 'markdown-it';
+
+interface CodeblockPluginOptions {
+    /**
+     * The default language to use if none is detected.
+     * @default 'markup'
+     */
+    defaultLang?: string;
+    /**
+     * The component used to wrap code blocks.
+     * @default 'markdown-prerender'
+     */
+    containerComponent?: string;
+    /**
+     * The component used to render the copy button.
+     * @default 'markdown-copy-button'
+     */
+    copyButtonComponent?: string;
+    /**
+     * The comonent name for the tab panel.
+     * @default 'q-tab-panel'
+     */
+    tabPanelTagName?: string;
+    /**
+     * The class(es) to be used with the tab panel.
+     * @default 'q-pa-none'
+     */
+    tabPanelTagClass?: string;
+    /**
+     * The class to be used for the line added.
+     * @default 'line-add'
+     */
+    lineAddClass?: string;
+    /**
+     * The prefix to be used for magic classes.
+     * The 3 magic classes are `add`, `rem`, and `highlight`.
+     * Classes in your code are then prefixed with this prefix.
+     * @default 'line-'
+     * The final class names would be: `line-add`, `line-rem`, `line-highlight`.
+     */
+    linePrefixClass?: string;
+    /**
+     * The class to be used for the pre tag.
+     * @default 'markdown-pre'
+     */
+    preClass?: string;
+    /**
+     * The class to be used for the code tag (ok to be empty).
+     * @default 'markdown-code'
+     */
+    codeClass?: string;
+    /**
+     * An array of page scripts to be included.
+     */
+    pageScripts?: string[];
+    /**
+     * Optional Prism 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?: Array<{
+        name: string;
+        aliases?: string;
+        customCopy?: boolean;
+    }>;
+}
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * An array of page script (import statements) to be included.
+         */
+        pageScripts?: Set<string>;
+    }
+}
+
+declare const codeblocksPlugin: PluginWithOptions<CodeblockPluginOptions>;
+
+export { type CodeblockPluginOptions, codeblocksPlugin };

package/dist/index.mjs

@@ -0,0 +1,229 @@
+import prism from 'prismjs';
+import loadLanguages from 'prismjs/components/index.js';
+
+const defaultLangList = [
+  { name: "markup" },
+  { name: "bash", customCopy: true },
+  { name: "javascript", aliases: "javascript|js" },
+  { name: "typescript", aliases: "typescript|ts" },
+  { name: "sass" },
+  { name: "scss" },
+  { name: "css" },
+  { name: "json" },
+  { name: "xml" },
+  { name: "nginx" },
+  { name: "html" },
+  // special grammars:
+  { name: "diff" }
+];
+const codeblocksPlugin = (md, {
+  defaultLang = "markup",
+  containerComponent = "MarkdownPrerender",
+  copyButtonComponent = "MarkdownCopyButton",
+  preClass = "markdown-code",
+  codeClass = "",
+  linePrefixClass = "line-",
+  tabPanelTagName = "q-tab-panel",
+  tabPanelTagClass = "q-pa-none",
+  pageScripts = [
+    "import MarkdownPrerender from 'src/components/md/MarkdownPrerender'",
+    // ts file
+    "import MarkdownCopyButton from 'src/components/md/MarkdownCopyButton.vue'"
+  ],
+  langList = defaultLangList
+} = {}) => {
+  const customCopyLangList = langList.filter((l) => l.customCopy).map((l) => l.name);
+  loadLanguages(langList.map((l) => l.name));
+  const langMatch = langList.map((l) => l.aliases || l.name).join("|");
+  const definitionLineRE = new RegExp(
+    `^(?<lang>(tabs|${langMatch}))(\\s+\\[(?<attrs>[^\\]]+)\\])?(\\s+(?<title>.+))?$`
+  );
+  const tabsLineRE = new RegExp(
+    `^<<\\|\\s*(?<lang>${langMatch})(?:\\s+\\[(?<attrs>[^\\]]+)\\])?(?:\\s+(?<title>.+?))?\\s*\\|>>$`
+    // ends with "|>>" + optional spaces
+  );
+  const magicCommentList = ["highlight", "rem", "add"];
+  const magicCommentRE = new RegExp(
+    ` *\\[\\[! (?<type>(${magicCommentList.join("|")}))\\]\\] *`
+  );
+  const magicCommentGlobalRE = new RegExp(magicCommentRE, "g");
+  function parseAttrs(rawAttrs) {
+    if (rawAttrs === null) return {};
+    const acc = {};
+    const attrList = rawAttrs.split(/\s+/);
+    for (const attr of attrList) {
+      const [key, value] = attr.split("=");
+      if (key !== void 0) {
+        const normalizedValue = value !== void 0 ? value.trim().replace(/^['"]|['"]$/g, "") : true;
+        acc[key.trim()] = normalizedValue;
+      }
+    }
+    return acc;
+  }
+  function extractTabs(content) {
+    const list = [];
+    const tabMap = {};
+    let currentTabName = null;
+    for (const line of content.split("\n").map((line2) => line2.trim())) {
+      if (line.startsWith("<<|")) {
+        const tabsMatch = line.match(tabsLineRE);
+        if (tabsMatch !== null) {
+          const { groups } = tabsMatch;
+          const lang = groups?.lang;
+          const attrs = groups?.attrs;
+          const title = groups?.title;
+          currentTabName = title?.trim() || `Tab ${list.length + 1}`;
+          if (currentTabName) {
+            list.push(currentTabName);
+            tabMap[currentTabName] = {
+              attrs: {
+                ...parseAttrs(attrs?.trim() || null),
+                lang
+              },
+              content: []
+            };
+          }
+        }
+      } else if (currentTabName !== null) {
+        tabMap[currentTabName]?.content.push(line);
+      }
+    }
+    if (list.length === 0) return;
+    return {
+      param: `[ ${list.map((tab) => `'${tab}'`).join(", ")} ]`,
+      content: list.map((tabName) => {
+        const props = tabMap[tabName];
+        if (props) {
+          return `<${tabPanelTagName} class="${tabPanelTagClass}" name="${tabName}">` + getHighlightedContent(props.content.join("\n"), props.attrs) + `</${tabPanelTagName}>`;
+        }
+        return "";
+      }).join("\n")
+    };
+  }
+  function extractCodeLineProps(lines, attrs) {
+    const acc = {};
+    for (const type of magicCommentList) {
+      acc[type] = attrs[type] !== void 0 ? attrs[type].split(",") : [];
+    }
+    lines.forEach((line, lineIndex) => {
+      const match = line.match(magicCommentRE);
+      if (match !== null && match.groups) {
+        const { type } = match.groups;
+        if (type && type in acc) {
+          acc[type].push("" + (lineIndex + 1));
+        }
+      }
+    });
+    return acc;
+  }
+  function parseCodeLine(content, attrs) {
+    const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    const lines = normalized.split("\n");
+    const props = extractCodeLineProps(lines, attrs);
+    const acc = lines.map(() => ({ prefix: [], classList: [] }));
+    const hasRemOrAdd = (props.rem?.length || 0) > 0 || (props.add?.length || 0) > 0;
+    for (const type of magicCommentList) {
+      const target = props[type];
+      if (target) {
+        for (const value of target) {
+          const [fromStr, toStr] = value.split("-");
+          const from = parseInt(String(fromStr), 10);
+          const to = toStr ? parseInt(toStr, 10) : from;
+          if (!isNaN(from) && !isNaN(to)) {
+            for (let i = from; i <= to; i++) {
+              if (acc[i - 1]) {
+                acc[i - 1].classList.push(`${linePrefixClass}${type}`);
+              }
+            }
+          }
+        }
+      }
+    }
+    if (attrs.numbered === true) {
+      const lineCount = String(lines.length).length;
+      lines.forEach((_, lineIndex) => {
+        if (acc[lineIndex]) {
+          acc[lineIndex].prefix.push(
+            String(lineIndex + 1).padStart(lineCount, " ")
+          );
+        }
+      });
+    }
+    if (hasRemOrAdd) {
+      lines.forEach((_, lineIndex) => {
+        const target = acc[lineIndex];
+        if (target) {
+          target.prefix.push(
+            target.classList.includes(`${linePrefixClass}add`) ? "+" : target.classList.includes(`${linePrefixClass}rem`) ? "-" : " "
+          );
+        }
+      });
+    }
+    return acc;
+  }
+  function getHighlightedContent(rawContent, attrs) {
+    const { lang = defaultLang, maxheight } = attrs;
+    const content = rawContent.trim();
+    const lineList = parseCodeLine(content, attrs);
+    const grammar = prism.languages[lang || defaultLang];
+    const html = prism.highlight(content.replace(magicCommentGlobalRE, ""), grammar, lang).split("\n").map((line, lineIndex) => {
+      const target = lineList[lineIndex];
+      let lineHtml = "";
+      if (target) {
+        if (target.classList.length !== 0) {
+          lineHtml += `<span class="c-line ${target.classList.join(" ")}"></span>`;
+        }
+        if (target.prefix.length !== 0) {
+          lineHtml += `<span class="c-lpref">${target.prefix.join(" ")}</span>`;
+        }
+      }
+      lineHtml += line;
+      return lineHtml;
+    }).join("\n");
+    const langClass = lang === "css" ? " language-css" : ` language-${lang}`;
+    const preAttrs = maxheight !== void 0 ? ` style="max-height:${maxheight}"` : "";
+    const langProp = customCopyLangList.includes(lang) === true ? ` lang="${lang}"` : "";
+    const results = `<pre v-pre class="${preClass}${langClass}"${preAttrs}><code${codeClass ? ` class="${codeClass}"` : ""}>${!!grammar ? html : rawContent}</code></pre>` + (copyButtonComponent ? `<${copyButtonComponent} ${langProp} />` : "");
+    return results;
+  }
+  function parseDefinitionLine(token) {
+    const match = token.info.trim().match(definitionLineRE);
+    if (match === null) {
+      return {
+        lang: defaultLang,
+        title: null
+      };
+    }
+    const { groups } = match;
+    const acc = {
+      ...parseAttrs(groups?.attrs?.trim() || null),
+      lang: groups?.lang || defaultLang,
+      title: groups?.title?.trim() || null
+    };
+    if (acc.lang === "tabs") {
+      const tabs = extractTabs(token.content);
+      if (tabs) {
+        acc.tabs = tabs;
+      }
+    }
+    return acc;
+  }
+  md.renderer.rules.fence = (tokens, idx, _options, env) => {
+    const token = tokens[idx];
+    if (!token) {
+      return "";
+    }
+    const attrs = parseDefinitionLine(token);
+    if (pageScripts.length > 0) {
+      if (!env.pageScripts) {
+        env.pageScripts = /* @__PURE__ */ new Set();
+      }
+      for (const script of pageScripts) {
+        env.pageScripts.add(script);
+      }
+    }
+    return `<${containerComponent}${attrs.title !== null ? ` title="${attrs.title}"` : ""}${"tabs" in attrs && attrs.tabs !== void 0 ? ` :tabs="${attrs.tabs.param}"` : ""}>` + ("tabs" in attrs && attrs.tabs !== void 0 ? attrs.tabs.content : getHighlightedContent(token.content, attrs)) + `</${containerComponent}>`;
+  };
+};
+
+export { codeblocksPlugin };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@md-plugins/md-plugin-codeblocks",
+  "version": "0.1.0-alpha.1",
+  "description": "A markdown-it plugin for code blocks.",
+  "keywords": [
+    "markdown-it",
+    "quasarframework",
+    "vue",
+    "types"
+  ],
+  "homepage": "https://github.com/md-plugins",
+  "bugs": {
+    "url": "https://github.com/md-plugins/md-plugins/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/md-plugins/md-plugins.git"
+  },
+  "license": "MIT",
+  "author": "hawkeye64 <galbraith64@gmail.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "./dist"
+  ],
+  "dependencies": {
+    "markdown-it": "^14.1.0",
+    "prismjs": "^1.29.0",
+    "@md-plugins/shared": "0.1.0-alpha.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "@types/prismjs": "^1.26.5"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "clean": "rm -rf dist",
+    "test": "vitest"
+  }
+}