@md-plugins/vite-md-plugin 0.1.0-alpha.9 → 0.1.0-beta.1

package/README.md

@@ -1,5 +1,7 @@
 # @md-plugins/viteMdPlugin
 
+See the [documentation](https://md-plugins.netlify.app/vite-plugins/vite-md-plugin/overview) for more details.
+
 An **opinionated Vite plugin** that transforms Markdown files into Vue Single File Components (SFCs). This plugin integrates Markdown processing directly into your Vite-based Vue project, enabling seamless Markdown-to-Vue workflows.
 
 ## Features
@@ -32,12 +34,12 @@ The `viteMdPlugin` is built on top of the following plugins:
 Install the plugin via your preferred package manager:
 
 ```bash
-# With npm:
-npm install @md-plugins/vite-md-plugin
-# Or with Yarn:
-yarn add @md-plugins/vite-md-plugin
-# Or with pnpm:
+# with pnpm:
 pnpm add @md-plugins/vite-md-plugin
+# with Yarn:
+yarn add @md-plugins/vite-md-plugin
+# with npm:
+npm install @md-plugins/vite-md-plugin
 ```
 
 ## Usage
@@ -49,7 +51,7 @@ To use the `viteMdPlugin`, configure it in your Vite project:
 ```js
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
-import { viteMdPlugin } from 'vite-md-plugin'
+import { viteMdPlugin } from '@md-plugins/vite-md-plugin'
 
 const menu = [] // Define your navigation menu structure here
 const basePath = '/docs' // Base path prefix
@@ -65,38 +67,30 @@ If you’re using the Quasar Framework, additional configuration is needed to en
 
 1. Update `quasar.config.(js|ts)`:
 
-```js
-import { viteMdPlugin } from '@md-plugins/vite-md-plugin';
-import { menu } from './src/.q-press/assets/menu'; // be sure to create this file
-
-export default defineConfig((ctx) => {
-  // ...
-```
+- ```js
+  import { viteMdPlugin, type MenuItem, type MarkdownOptions } from '@md-plugins/vite-md-plugin'
+  import { menu } from './src/assets/menu' // be sure to create this file
 
-```js
-build: {
-  vueRouterMode: 'history', // Required for proper hash link handling
-
-  viteVuePluginOptions: {
-    include: [/\.(vue|md)$/], // Include Markdown files
-  },
-
-  vitePlugins: [
-      [
-        viteMdPlugin,
-        {
+  export default defineConfig((ctx) => {
+    // ...
+    build: {
+      vueRouterMode: 'history', // Required for proper hash link handling
+      viteVuePluginOptions: {
+        include: [/\.(vue|md)$/], // Include Markdown files
+      },
+      vitePlugins: [
+        viteMdPlugin({
           path: ctx.appPaths.srcDir + '/markdown',
-          menu: sidebar as MenuItem[],
-        },
+          menu: menu as MenuItem[],
+          // config: myOptions as MarkdownOptions,
+        }),
+        // ...
       ],
-    // ...
-  ],
-},
-
-framework: {
-  autoImportVueExtensions: ['vue', 'md'], // Enable auto-import for Markdown extensions
-},
-```
+    },
+    framework: {
+      autoImportVueExtensions: ['vue', 'md'], // Enable auto-import for Markdown extensions
+    },
+  ```
 
 2. Ensure that your routes and hash links are compatible with Vue Router's history mode.
 
@@ -106,8 +100,8 @@ The `viteMdPlugin` allows you to define a navigation structure that can be updat
 
 ```js
 const menu = [
-  { title: 'Home', path: '/home' },
-  { title: 'About', path: '/about' },
+  { name: 'Home', path: '/home' },
+  { name: 'About', path: '/about' },
 ]
 ```
 
@@ -117,10 +111,10 @@ This menu is passed as a parameter to the plugin and can be used to build a dyna
 
 The `viteMdPlugin` accepts the following parameters:
 
-| Parameter | Type       | Description                                                                                |
-| --------- | ---------- | ------------------------------------------------------------------------------------------ |
-| path      | string     | The base path prefix for routing or file resolution.                                       |
-| menu      | MenuItem[] | An array representing the navigation menu structure. Each item should have title and path. |
+| Parameter | Type       | Description                                                                               |
+| --------- | ---------- | ----------------------------------------------------------------------------------------- |
+| path      | string     | The base path prefix for routing or file resolution.                                      |
+| menu      | MenuItem[] | An array representing the navigation menu structure. Each item should have name and path. |
 
 ## MenuItem Type
 
@@ -149,6 +143,10 @@ To run the tests for this plugin, use the following command:
 pnpm test
 ```
 
+## Documentation
+
+In case this README falls out of date, please refer to the [documentation](https://md-plugins.netlify.app/vite-plugins/vite-md-plugin/overview) for the latest information.
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.

package/dist/index.d.mts

@@ -1,5 +1,31 @@
 import { Plugin } from 'vite';
+import { Options } from 'markdown-it';
+import { MarkdownItEnv } from '@md-plugins/shared';
+import { BlockquotePluginOptions } from '@md-plugins/md-plugin-blockquote';
+import { CodeblockPluginOptions } from '@md-plugins/md-plugin-codeblocks';
+import { FrontmatterPluginOptions } from '@md-plugins/md-plugin-frontmatter';
+import { HeadersPluginOptions } from '@md-plugins/md-plugin-headers';
+import { ImagePluginOptions } from '@md-plugins/md-plugin-image';
+import { InlineCodePluginOptions } from '@md-plugins/md-plugin-inlinecode';
+import { LinkPluginOptions } from '@md-plugins/md-plugin-link';
+import { TablePluginOptions } from '@md-plugins/md-plugin-table';
 
+interface MarkdownOptions extends Options {
+    html?: boolean;
+    linkify?: boolean;
+    typographer?: boolean;
+    breaks?: boolean;
+    blockquotePlugin?: BlockquotePluginOptions;
+    codeblockPlugin?: CodeblockPluginOptions;
+    frontmatterPlugin?: FrontmatterPluginOptions;
+    headersPlugin?: HeadersPluginOptions | boolean;
+    imagePlugin?: ImagePluginOptions;
+    inlineCodePlugin?: InlineCodePluginOptions;
+    linkPlugin?: LinkPluginOptions;
+    tablePlugin?: TablePluginOptions;
+    preProcess?: (env: MarkdownItEnv) => void;
+    postProcess?: (env: MarkdownItEnv) => void;
+}
 interface MenuItem {
     name: string;
     path?: string;
@@ -37,6 +63,7 @@ interface RelatedItem {
 interface UserConfig {
     path: string;
     menu: MenuItem[];
+    config?: MarkdownOptions;
 }
 
 /**
@@ -46,8 +73,10 @@ interface UserConfig {
  * @param userConfig - The configuration object for the Vite Markdown plugin.
  * @param userConfig.path - The base path prefix to be used for routing or file resolution.
  * @param userConfig.menu - An array of MenuItem objects representing the navigation menu structure.
+ * @param userConfig.config - Additional configuration options for the Markdown processing.
  * @returns A Vite Plugin object pre-configured with the provided settings for Markdown processing.
  */
 declare function viteMdPlugin(userConfig: UserConfig): Plugin;
 
-export { type FlatMenu, type FlatMenuEntry, type MenuItem, type MenuNode, type NavItem, type RelatedItem, type UserConfig, viteMdPlugin };
+export { viteMdPlugin };
+export type { FlatMenu, FlatMenuEntry, MarkdownOptions, MenuItem, MenuNode, NavItem, RelatedItem, UserConfig };

package/dist/index.d.ts

@@ -1,5 +1,31 @@
 import { Plugin } from 'vite';
+import { Options } from 'markdown-it';
+import { MarkdownItEnv } from '@md-plugins/shared';
+import { BlockquotePluginOptions } from '@md-plugins/md-plugin-blockquote';
+import { CodeblockPluginOptions } from '@md-plugins/md-plugin-codeblocks';
+import { FrontmatterPluginOptions } from '@md-plugins/md-plugin-frontmatter';
+import { HeadersPluginOptions } from '@md-plugins/md-plugin-headers';
+import { ImagePluginOptions } from '@md-plugins/md-plugin-image';
+import { InlineCodePluginOptions } from '@md-plugins/md-plugin-inlinecode';
+import { LinkPluginOptions } from '@md-plugins/md-plugin-link';
+import { TablePluginOptions } from '@md-plugins/md-plugin-table';
 
+interface MarkdownOptions extends Options {
+    html?: boolean;
+    linkify?: boolean;
+    typographer?: boolean;
+    breaks?: boolean;
+    blockquotePlugin?: BlockquotePluginOptions;
+    codeblockPlugin?: CodeblockPluginOptions;
+    frontmatterPlugin?: FrontmatterPluginOptions;
+    headersPlugin?: HeadersPluginOptions | boolean;
+    imagePlugin?: ImagePluginOptions;
+    inlineCodePlugin?: InlineCodePluginOptions;
+    linkPlugin?: LinkPluginOptions;
+    tablePlugin?: TablePluginOptions;
+    preProcess?: (env: MarkdownItEnv) => void;
+    postProcess?: (env: MarkdownItEnv) => void;
+}
 interface MenuItem {
     name: string;
     path?: string;
@@ -37,6 +63,7 @@ interface RelatedItem {
 interface UserConfig {
     path: string;
     menu: MenuItem[];
+    config?: MarkdownOptions;
 }
 
 /**
@@ -46,8 +73,10 @@ interface UserConfig {
  * @param userConfig - The configuration object for the Vite Markdown plugin.
  * @param userConfig.path - The base path prefix to be used for routing or file resolution.
  * @param userConfig.menu - An array of MenuItem objects representing the navigation menu structure.
+ * @param userConfig.config - Additional configuration options for the Markdown processing.
  * @returns A Vite Plugin object pre-configured with the provided settings for Markdown processing.
  */
 declare function viteMdPlugin(userConfig: UserConfig): Plugin;
 
-export { type FlatMenu, type FlatMenuEntry, type MenuItem, type MenuNode, type NavItem, type RelatedItem, type UserConfig, viteMdPlugin };
+export { viteMdPlugin };
+export type { FlatMenu, FlatMenuEntry, MarkdownOptions, MenuItem, MenuNode, NavItem, RelatedItem, UserConfig };

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { join } from 'node:path';
 import MarkdownIt from 'markdown-it';
 import { frontmatterPlugin } from '@md-plugins/md-plugin-frontmatter';
 import { importsPlugin } from '@md-plugins/md-plugin-imports';
@@ -10,87 +11,6 @@ import { blockquotePlugin } from '@md-plugins/md-plugin-blockquote';
 import { tablePlugin } from '@md-plugins/md-plugin-table';
 import { titlePlugin } from '@md-plugins/md-plugin-title';
 import { containersPlugin } from '@md-plugins/md-plugin-containers';
-import { join } from 'node:path';
-
-const createContainer = (container, containerType, defaultTitle) => {
-  const containerTypeLen = containerType.length;
-  return [
-    container,
-    containerType,
-    {
-      render(tokens, idx) {
-        const token = tokens[idx];
-        if (!token) {
-          return "";
-        }
-        const title = token.info.trim().slice(containerTypeLen).trim() || defaultTitle;
-        if (containerType === "details") {
-          return token.nesting === 1 ? `<details class="markdown-note markdown-note--${containerType}"><summary class="markdown-note__title">${title}</summary>
-` : "</details>\n";
-        }
-        return token.nesting === 1 ? `<div class="markdown-note markdown-note--${containerType}"><p class="markdown-note__title">${title}</p>
-` : "</div>\n";
-      }
-    }
-  ];
-};
-function createMarkdownRenderer(options = {}) {
-  const md2 = new MarkdownIt({
-    html: true,
-    linkify: true,
-    typographer: true,
-    ...options,
-    breaks: true
-  });
-  md2.use(frontmatterPlugin);
-  md2.use(importsPlugin);
-  md2.use(titlePlugin);
-  md2.use(headersPlugin, { level: [2, 3] });
-  const containers = [
-    { type: "tip", defaultTitle: "TIP" },
-    { type: "warning", defaultTitle: "WARNING" },
-    { type: "danger", defaultTitle: "WARNING" },
-    { type: "details", defaultTitle: "Details" }
-  ];
-  md2.use(containersPlugin, containers, createContainer);
-  md2.use(blockquotePlugin, { blockquoteClass: "markdown-note" });
-  md2.use(tablePlugin, {
-    tableClass: "markdown-table",
-    tableHeaderClass: "text-left",
-    tableToken: "q-markup-table",
-    tableAttributes: [
-      [":wrap-cells", "true"],
-      [":flat", "true"],
-      [":bordered", "true"]
-    ]
-  });
-  md2.use(codeblocksPlugin, {
-    containerComponent: "MarkdownPrerender",
-    copyButtonComponent: "MarkdownCopyButton",
-    pageScripts: [
-      "import MarkdownPrerender from 'src/.q-press/components/MarkdownPrerender'",
-      "import MarkdownCopyButton from 'src/.q-press/components/MarkdownCopyButton.vue'"
-    ]
-  });
-  md2.use(linkPlugin);
-  md2.use(inlinecodePlugin);
-  md2.use(imagePlugin);
-  return {
-    // env: Environment for storing metadata
-    render(code, env = {}) {
-      const html = md2.render(code, env);
-      return {
-        html,
-        frontmatter: env.frontmatter || {},
-        // comes from md_plugin_frontmatter
-        title: env.title || "",
-        // comes from md_plugin_title
-        env
-      };
-    }
-  };
-}
-const md = createMarkdownRenderer();
 
 let prev = null;
 function menuWalk(prefix, menuNodes, node, path, parentName) {
@@ -245,7 +165,7 @@ function getVueComponent(rendered, code, id, prefix, menu) {
 import { copyHeading } from 'src/.q-press/components/markdown-utils'
 ${examples !== false ? `
 import { provide } from 'vue'
-provide('_markdown_examples_', process.env.CLIENT
+	provide('_markdown_examples_', import.meta.env.QUASAR_CLIENT
   ? { name: '${examples}', list: import('examples:${examples}') }
   : { name: '${examples}' })
 ` : ""}
@@ -257,58 +177,139 @@ ${pageScripts}
 <\/script>`;
 }
 
+const createContainer = (container, containerType, defaultTitle, md) => {
+  const containerTypeLen = containerType.length;
+  return [
+    container,
+    containerType,
+    {
+      render(tokens, idx) {
+        const token = tokens[idx];
+        if (!token) {
+          return "";
+        }
+        const rawTitle = token.info.trim().slice(containerTypeLen).trim() || defaultTitle;
+        const titleHtml = md ? md.renderInline(rawTitle) : rawTitle;
+        if (containerType === "details") {
+          return token.nesting === 1 ? `<details class="markdown-note markdown-note--${containerType}"><summary class="markdown-note__title">${titleHtml}</summary>
+` : "</details>\n";
+        }
+        return token.nesting === 1 ? `<div class="markdown-note markdown-note--${containerType}"><p class="markdown-note__title">${titleHtml}</p>
+` : "</div>\n";
+      }
+    }
+  ];
+};
+function createMarkdownRenderer(options = {}) {
+  const md = new MarkdownIt({
+    html: true,
+    linkify: true,
+    typographer: true,
+    breaks: true,
+    ...options
+  });
+  md.use(frontmatterPlugin, { ...options });
+  md.use(importsPlugin);
+  md.use(titlePlugin);
+  md.use(headersPlugin, { level: [2, 3], ...options });
+  const containers = [
+    { type: "tip", defaultTitle: "TIP" },
+    { type: "warning", defaultTitle: "WARNING" },
+    { type: "danger", defaultTitle: "WARNING" },
+    { type: "details", defaultTitle: "Details" }
+  ];
+  md.use(containersPlugin, containers, createContainer, md);
+  md.use(blockquotePlugin, { blockquoteClass: "markdown-note", ...options });
+  md.use(tablePlugin, {
+    tableClass: "markdown-table",
+    tableHeaderClass: "text-left",
+    tableToken: "q-markup-table",
+    tableAttributes: [
+      [":wrap-cells", "true"],
+      [":flat", "true"],
+      [":bordered", "true"]
+    ],
+    ...options
+  });
+  md.use(codeblocksPlugin, {
+    containerComponent: "MarkdownPrerender",
+    copyButtonComponent: "MarkdownCopyButton",
+    pageScripts: [
+      "import MarkdownPrerender from 'src/.q-press/components/MarkdownPrerender'",
+      "import MarkdownCopyButton from 'src/.q-press/components/MarkdownCopyButton.vue'"
+    ],
+    ...options
+  });
+  md.use(linkPlugin, { ...options });
+  md.use(inlinecodePlugin, { ...options });
+  md.use(imagePlugin, { ...options });
+  return {
+    // env: Environment for storing metadata
+    render(code, env = {}) {
+      const html = md.render(code, env);
+      return {
+        html,
+        frontmatter: env.frontmatter || {},
+        // comes from md_plugin_frontmatter
+        title: env.title || "",
+        // comes from md_plugin_title
+        env
+      };
+    }
+  };
+}
+
 const markdownLinkRE = /<MarkdownLink /;
 const markdownApiRE = /<MarkdownApi /;
-const markdownInstallationRE = /<MarkdownInstallation /;
 const markdownTreeRE = /<MarkdownTree /;
-function mdParse(code, id, prefix, menu) {
+function mdParse(code, id, prefix, menu, options = {}) {
   const env = {
-    frontmatter: {
-      id
-    },
+    frontmatter: { id },
     pageScripts: /* @__PURE__ */ new Set()
   };
   env.pageScripts.add("import MarkdownPage from 'src/.q-press/layouts/MarkdownPage.vue'");
-  if (markdownApiRE.test(code) === true) {
+  if (markdownApiRE.test(code)) {
     env.pageScripts.add("import MarkdownApi from 'src/.q-press/components/MarkdownApi.vue'");
   }
-  if (markdownInstallationRE.test(code) === true) {
-    env.pageScripts.add(
-      "import MarkdownInstallation from 'src/.q-press/components/MarkdownInstallation.vue'"
-    );
-  }
-  if (markdownTreeRE.test(code) === true) {
+  if (markdownTreeRE.test(code)) {
     env.pageScripts.add("import MarkdownTree from 'src/.q-press/components/MarkdownTree.vue'");
   }
+  if (typeof options.preProcess === "function") {
+    options.preProcess(env);
+  }
+  const md = createMarkdownRenderer(options);
   const results = md.render(code, env);
   if (env.frontmatter.examples !== void 0) {
     env.pageScripts.add(
       "import MarkdownExample from 'src/.q-press/components/MarkdownExample.vue'"
     );
   }
-  if (markdownLinkRE.test(code) === true) {
+  if (markdownLinkRE.test(code)) {
     env.pageScripts.add("import MarkdownLink from 'src/.q-press/components/MarkdownLink.vue'");
   }
+  if (typeof options.postProcess === "function") {
+    options.postProcess(env);
+  }
   const component = getVueComponent(results, code, id, prefix, menu);
-  return {
-    code: component,
-    map: null
-    // No source map provided
-  };
+  return { code: component };
 }
 
 const mdRE = /\.md$/;
 let globalMenu = [];
 let globalPrefix = "";
+let globalConfig = {};
 function transform(code, id) {
   if (!mdRE.test(id)) return null;
   try {
-    const result = mdParse(code, id, globalPrefix, globalMenu);
+    const result = mdParse(code, id, globalPrefix, globalMenu, globalConfig);
     return result.code;
   } catch (err) {
     console.error(`Error processing Markdown file: ${id}`, err);
     throw new Error(
-      `Markdown transform failed: ${err instanceof Error ? err.message : String(err)}`
+      `Markdown transform failed: ${err instanceof Error ? err.message : String(err)}`,
+      {
+        cause: err
+      }
     );
   }
 }
@@ -336,13 +337,14 @@ const mdPlugins = {
   transform,
   hotUpdate
 };
-function viteMdPlugin2(path, menu) {
+function viteMdPlugin2(path, menu, config) {
   globalMenu = menu;
   globalPrefix = path;
+  globalConfig = config;
   return mdPlugins;
 }
 function viteMdPlugin(userConfig) {
-  return viteMdPlugin2(userConfig.path, userConfig.menu);
+  return viteMdPlugin2(userConfig.path, userConfig.menu, userConfig.config || {});
 }
 
 export { viteMdPlugin };

package/package.json

@@ -1,26 +1,31 @@
 {
   "name": "@md-plugins/vite-md-plugin",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.0-beta.1",
   "description": "A very opinionated Vite plugin for @md-plugins.",
   "keywords": [
     "markdown-it",
     "quasarframework",
-    "vue",
     "utils",
     "vite",
-    "vite-plugin"
+    "vite-plugin",
+    "vue"
   ],
   "homepage": "https://github.com/md-plugins",
   "bugs": {
     "url": "https://github.com/md-plugins/md-plugins/issues"
   },
+  "license": "MIT",
+  "author": "hawkeye64 <galbraith64@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/md-plugins/md-plugins.git"
   },
-  "license": "MIT",
-  "author": "hawkeye64 <galbraith64@gmail.com>",
+  "files": [
+    "./dist"
+  ],
   "type": "module",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": {
@@ -29,36 +34,31 @@
       }
     }
   },
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "./dist"
-  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
-    "@md-plugins/md-plugin-blockquote": "0.1.0-alpha.9",
-    "@md-plugins/md-plugin-codeblocks": "0.1.0-alpha.9",
-    "@md-plugins/md-plugin-containers": "0.1.0-alpha.9",
-    "@md-plugins/md-plugin-headers": "0.1.0-alpha.9",
-    "@md-plugins/md-plugin-frontmatter": "0.1.0-alpha.9",
-    "@md-plugins/md-plugin-image": "0.1.0-alpha.9",
-    "@md-plugins/md-plugin-imports": "0.1.0-alpha.9",
-    "@md-plugins/md-plugin-link": "0.1.0-alpha.9",
-    "@md-plugins/md-plugin-inlinecode": "0.1.0-alpha.9",
-    "@md-plugins/md-plugin-table": "0.1.0-alpha.9",
-    "@md-plugins/shared": "0.1.0-alpha.9",
-    "@md-plugins/md-plugin-title": "0.1.0-alpha.9"
+    "markdown-it": "^14.1.1",
+    "@md-plugins/md-plugin-blockquote": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-frontmatter": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-headers": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-imports": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-image": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-inlinecode": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-link": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-title": "0.1.0-beta.1",
+    "@md-plugins/shared": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-containers": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-table": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-codeblocks": "0.1.0-beta.1"
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.2",
-    "markdown-it": "^14.1.0",
-    "vite": "^6.0.7"
+    "vite": "^8.0.12"
   },
   "peerDependencies": {
     "markdown-it": "^14.1.0"
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "scripts": {
     "build": "unbuild",
     "clean": "rm -rf dist/ node_modules/"