@nuxtjs/mdc 0.2.7 → 0.2.9

package/README.md

@@ -44,48 +44,241 @@ export default defineNuxtConfig({
 })
 ```
 
-## Use
+That's it! You can start writing and rendering markdown files ✨
 
-Parse MDC content in any environment:
+## Rendering
 
-```ts [parse-mdc.ts]
-import { parseMarkdown } from '@nuxtjs/mdc/runtime'
-
-async function main(mdc: string) {
-  const ast = await parseMarkdown(mdc)
+`@nuxtjs/mdc` exposes three components to render markdown files.
 
-  // Do your magic with parsed AST tree
-
-  return ast
-}
-```
+### `<MDC>`
 
-Render MDC content with `<MDC>` component:
+Using `<MDC>`, you can parse and render markdown contents right inside your components/pages. This component takes raw markdown, parses it using the `parseMarkdown` function, and then renders it with `<MDCRenderer>`.
 
 ```html
+<script setup lang="ts">
+const md = `
+::alert
+Hello MDC
+::
+`
+</script>
+
 <template>
   <MDC :value="md" tag="article" />
 </template>
+```
+
+Note that `::alert` will use the `components/global/Alert.vue` component.
+
+### `<MDCRenderer>`
+
+This component will take the result of [`parseMarkdown`](#parsing-markdown) function and render the contents. For example, this is an extended version of the sample code in the [Browser section](#browser) which uses `MDCRenderer` to render the parsed markdown.
 
+```html [mdc-test.vue]
 <script setup lang="ts">
-const md = `
+import { parseMarkdown } from '@nuxtjs/mdc/runtime'
+
+const ast = await useAsyncData('markdown', () => parseMarkdown('::alert\nMissing markdown input\n::'))
+</script>
+
+<template>
+  <MDCRenderer :body="ast.body" :data="ast.data" />
+</template>
+```
+
+### `<MDCSlot>`
+
+This component is a replacement for Vue's `<slot/>` component, specifically designed for MDC. Using this component, you can render a component's children while removing one or multiple wrapping elements. In the below example, the Alert component receives text and its default slot (children). But if the component renders this slot using the normal `<slot/>`, it will render a `<p>` element around the text.
+
+```md [markdown.md]
 ::alert
-Hello MDC
+This is an Alert
 ::
-`
+```
+
+```html [Alert.vue]
+<template>
+  <div class="alert">
+    <!-- Slot will render <p> tag around the text -->
+    <slot />
+  </div>
+</template>
+```
+
+It is the default behavior of markdown to wrap every text inside a paragraph. MDC didn't come to break markdown behavior; instead, the goal of MDC is to make markdown powerful. In this example and all similar situations, you can use `<MDCSlot />` to remove unwanted wrappers.
+
+```html [Alert.vue]
+<template>
+  <div class="alert">
+    <!-- MDCSlot will only render the actual text without the wrapping <p> -->
+    <MDCSlot unwrap="p" />
+  </div>
+</template>
+```
+
+### Prose Components
+
+Prose components are a list of components that will be rendered instead of regular HTML tags. For example, instead of rendering a `<p>` tag, `@nuxtjs/mdc` renders a `<ProseP>` component. This is useful when you want to add extra features to your markdown files. For example, you can add a `copy` button to your code blocks.
+
+You can disable prose components by setting the `prose` option to `false` in `nuxt.config.ts`. Or extend the map of prose components to add your own components.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/mdc'],
+  mdc: {
+    components: {
+      prose: false, // Disable predefined prose components
+      map: {
+        p: 'MyCustomPComponent'
+      }
+    }
+  }
+})
+```
+
+Here is the list of available prose components:
+
+| Tag | Component | Source | Description |
+| -- | -- | -- | -- |
+| `p` | `<ProseP>` | [ProseP.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseP.vue) | Paragraph |
+| `h1` | `<ProseH1>` | [ProseH1.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseH1.vue) | Heading 1 |
+| `h2` | `<ProseH2>` | [ProseH2.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseH2.vue) | Heading 2 |
+| `h3` | `<ProseH3>` | [ProseH3.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseH3.vue) | Heading 3 |
+| `h4` | `<ProseH4>` | [ProseH4.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseH4.vue) | Heading 4 |
+| `h5` | `<ProseH5>` | [ProseH5.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseH5.vue) | Heading 5 |
+| `h6` | `<ProseH6>` | [ProseH6.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseH6.vue) | Heading 6 |
+| `ul` | `<ProseUl>` | [ProseUl.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseUl.vue) | Unordered List |
+| `ol` | `<ProseOl>` | [ProseOl.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseOl.vue) | Ordered List |
+| `li` | `<ProseLi>` | [ProseLi.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseLi.vue) | List Item |
+| `blockquote` | `<ProseBlockquote>` | [ProseBlockquote.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseBlockquote.vue) | Blockquote |
+| `hr` | `<ProseHr>` | [ProseHr.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseHr.vue) | Horizontal Rule |
+| `pre` | `<ProsePre>` | [ProsePre.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProsePre.vue) | Preformatted Text |
+| `code` | `<ProseCode>` | [ProseCode.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseCode.vue) | Code Block |
+| `table` | `<ProseTable>` | [ProseTable.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseTable.vue) | Table |
+| `thead` | `<ProseThead>` | [ProseThead.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseThead.vue) | Table Head |
+| `tbody` | `<ProseTbody>` | [ProseTbody.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseTbody.vue) | Table Body |
+| `tr` | `<ProseTr>` | [ProseTr.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseTr.vue) | Table Row |
+| `th` | `<ProseTh>` | [ProseTh.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseTh.vue) | Table Header |
+| `td` | `<ProseTd>` | [ProseTd.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseTd.vue) | Table Data |
+| `a` | `<ProseA>` | [ProseA.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseA.vue) | Anchor Link |
+| `img` | `<ProseImg>` | [ProseImg.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseImg.vue) | Image |
+| `em` | `<ProseEm>` | [ProseEm.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseEm.vue) | Emphasis |
+| `strong` | `<ProseStrong>` | [ProseStrong.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseStrong.vue) | Strong |
+
+## Parsing Markdown
+
+Nuxt MDC exposes a handy helper to parse MDC files. You can import the `parseMarkdown` function from `@nuxtjs/mdc/runtime` and use it to parse markdown files written with MDC syntax.
+
+### Node.js
+
+```ts
+// server/api/parse-mdc.ts
+import { parseMarkdown } from '@nuxtjs/mdc/runtime'
+
+export default eventHandler(async () => {
+  const mdc = [
+    '# Hello MDC',
+    '',
+    '::alert',
+    'This is an Alert',
+    '::'
+  ].join('\n')
+
+  const ast = await parseMarkdown(mdc)
+
+  return ast
+})
+```
+
+### Browser
+
+The `parseMarkdown` function is a universal helper, and you can also use it in the browser, for example inside a Vue component.
+
+```vue
+<script setup lang="ts">
+import { parseMarkdown } from '@nuxtjs/mdc/runtime'
+
+const ast = await useAsyncData('markdown', () => parseMarkdown('::alert\nMissing markdown input\n::'))
 </script>
+
+<template>
+  <MDCRenderer :body="ast.body" :data="ast.data" />
+</template>
+```
+
+### Options
+
+The `parseMarkdown` helper also accepts options as the second argument to control the parser's behavior. (Checkout [`MDCParseOptions` interface↗︎](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/types/parser.ts)).
+
+| Name | Default | Description |
+| --  | -- | -- |
+| `remark.plugins` | `{}` | Register / Configure parser's remark plugins. |
+| `rehype.options` | `{}` | Configure `remark-rehype` options.  |
+| `rehype.plugins` | `{}` | Register / Configure parser's rehype plugins. |
+| `highlight` | `false` | Control whether code blocks should highlight or not. You can also provide a custom highlighter.  |
+| `toc.depth` | `2` | Maximum heading depth to include in the table of contents.  |
+| `toc.searchDepth` | `2` | Maximum depth of nested tags to search for heading. |
+
+Checkout [`MDCParseOptions` types↗︎](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/types/parser.ts).
+
+## Configurations
+
+You can configure the module by providing the `mdc` property in your `nuxt.config.js`; here are the default options:
+
+```ts
+import { defineNuxtConfig } from 'nuxt/config'
+
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/mdc'],
+  mdc: {
+    remarkPlugins: {
+      plugins: {
+        // Register/Configure remark plugin to extend the parser
+      }
+    },
+    rehypePlugins: {
+      options: {
+        // Configure rehype options to extend the parser
+      },
+      plugins: {
+        // Register/Configure rehype plugin to extend the parser
+      }
+    },
+    headings: {
+      anchorLinks: {
+        // Enable/Disable heading anchor links. { h1: true, h2: false }
+      }
+    },
+    highlight: false, // Control syntax highlighting
+    components: {
+      prose: false, // Add predefined map to render Prose Components instead of HTML tags, like p, ul, code
+      map: {
+        // This map will be used in `<MDCRenderer>` to control rendered components
+      }
+    }
+  }
+})
 ```
 
-## 💻 Development
+Checkout [`ModuleOptions` types↗︎](https://github.com/nuxt-modules/mdc/blob/main/src/types.ts).
+
+## Contributing
 
-- Clone repository
-- Install dependencies using `pnpm install`
-- Prepare using `pnpm dev:prepare`
-- Try playground using `pnpm dev`
+You can contribute to this module online with CodeSandbox:
+
+[![Edit @nuxtjs/mdc](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/github/nuxt-modules/mdc/tree/main/?fontsize=14&hidenavigation=1&theme=dark)
+
+Or locally:
+
+1. Clone this repository
+2. Install dependencies using `pnpm install`
+3. Start the development server using `pnpm dev`
 
 ## License
 
-[MIT](./LICENSE) - Made with 💚
+[MIT License](https://github.com/nuxt-modules/mdc/blob/main/LICENSE)
+
+Copyright (c) NuxtLabs
 
 <!-- Badges -->
 [npm-version-src]: https://img.shields.io/npm/v/@nuxtjs/mdc/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
@@ -97,5 +290,6 @@ Hello MDC
 [license-src]: https://img.shields.io/github/license/nuxt-modules/mdc.svg?style=flat&colorA=18181B&colorB=28CF8D
 [license-href]: https://github.com/nuxt-modules/mdc/blob/main/LICENSE
 
+
 [nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
 [nuxt-href]: https://nuxt.com

package/dist/module.json

@@ -1,5 +1,5 @@
 {
   "name": "@nuxtjs/mdc",
   "configKey": "mdc",
-  "version": "0.2.7"
+  "version": "0.2.9"
 }

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { createResolver, extendViteConfig, defineNuxtModule, addServerHandler, addTemplate, addComponent, addImports, addComponentsDir } from '@nuxt/kit';
+import { createResolver, extendViteConfig, defineNuxtModule, addServerHandler, addTemplate, addComponent, addImports, addServerImports, addComponentsDir } from '@nuxt/kit';
 import fs from 'fs';
 import { pascalCase } from 'scule';
 import { defu } from 'defu';
@@ -123,14 +123,15 @@ const module = defineNuxtModule({
       } : {}
     });
     nuxt.hook("vite:extendConfig", (viteConfig) => {
-      viteConfig.optimizeDeps?.include?.push(
-        "is-buffer",
-        "debug",
-        "flat",
-        "node-emoji",
-        "extend",
-        "hast-util-raw"
-      );
+      const optimizeList = ["is-buffer", "debug", "flat", "node-emoji", "extend", "hast-util-raw"];
+      viteConfig.optimizeDeps ||= {};
+      viteConfig.optimizeDeps.include ||= [];
+      const list = viteConfig.optimizeDeps.include;
+      optimizeList.forEach((pkg) => {
+        if (!list.includes(pkg)) {
+          list.push(pkg);
+        }
+      });
     });
     if (options.highlight) {
       nuxt.options.nitro.experimental = nuxt.options.nitro.experimental || {};
@@ -138,7 +139,7 @@ const module = defineNuxtModule({
       addServerHandler({ route: "/api/_mdc/highlight", handler: resolver.resolve("./runtime/shiki/event-handler") });
       options.rehypePlugins = options.rehypePlugins || {};
       options.rehypePlugins.highlight = options.rehypePlugins.highlight || {};
-      options.rehypePlugins.highlight.src = options.rehypePlugins.highlight.src || resolver.resolve("./runtime/shiki/index");
+      options.rehypePlugins.highlight.src = options.rehypePlugins.highlight.src || await resolver.resolvePath("./runtime/shiki/index");
     }
     const { dst: templatePath } = addTemplate({ filename: "mdc-imports.mjs", getContents: mdcImportTemplate, options, write: true });
     nuxt.options.alias["#mdc-imports"] = process.env.NODE_ENV === "development" ? pathToFileURL(templatePath).href : templatePath;
@@ -148,6 +149,8 @@ const module = defineNuxtModule({
     addComponent({ name: "MDCRenderer", filePath: resolver.resolve("./runtime/components/MDCRenderer") });
     addComponent({ name: "MDCSlot", filePath: resolver.resolve("./runtime/components/MDCSlot") });
     addImports({ from: resolver.resolve("./runtime/utils/node"), name: "flatUnwrap", as: "unwrapSlot" });
+    addImports({ from: resolver.resolve("./runtime/parser"), name: "parseMarkdown", as: "parseMarkdown" });
+    addServerImports([{ from: resolver.resolve("./runtime/parser"), name: "parseMarkdown", as: "parseMarkdown" }]);
     if (options.components?.prose) {
       addComponentsDir({
         path: resolver.resolve("./runtime/components/prose"),

package/dist/runtime/components/MDCRenderer.vue.d.ts

@@ -76,9 +76,9 @@ declare const _default: DefineComponent<{
         default: () => {};
     };
 }>>, {
-    tag: string | boolean;
     data: Record<string, any>;
-    components: Record<string, string | DefineComponent<any, any, any>>;
+    tag: string | boolean;
     prose: boolean;
+    components: Record<string, string | DefineComponent<any, any, any>>;
 }, {}>;
 export default _default;

package/dist/runtime/components/prose/ProsePre.vue

@@ -32,7 +32,5 @@ defineProps({
 </script>
 
 <style>
-pre code .line {
-  display: block;
-}
+pre code .line{display:block}
 </style>

package/dist/runtime/shiki/highlighter.mjs

@@ -42,7 +42,15 @@ export const useShikiHighlighter = createSingleton((opts) => {
         await Promise.all(themeNames.map((theme3) => highlighter.loadTheme(theme3)));
       }
       if (lang && !highlighter.getLoadedLanguages().includes(lang)) {
-        await highlighter.loadLanguage(lang);
+        try {
+          await highlighter.loadLanguage(lang);
+        } catch (error) {
+          if (highlights.length) {
+            console.warn("[@nuxtjs/mdc] Defaulting to no language to be able to highlight lines:", error.message);
+            lang = "";
+          } else
+            throw error;
+        }
       }
       const root = highlighter.codeToHast(code.trimEnd(), {
         lang,
@@ -56,15 +64,16 @@ export const useShikiHighlighter = createSingleton((opts) => {
             }
             node.properties.line = line;
             if (code?.includes("\n")) {
-              if (node.children.length === 0) {
-                node.children.push({
+              if (node.children.length === 0 || node.children.length === 1 && node.children[0].type === "element" && node.children[0].children.length === 1 && node.children[0].children[0].type === "text" && node.children[0].children[0].value === "") {
+                node.children = [{
                   type: "element",
                   tagName: "span",
                   properties: {
                     emptyLinePlaceholder: true
                   },
-                  children: [{ type: "text", value: "" }]
-                });
+                  children: [{ type: "text", value: "\n" }]
+                }];
+                return;
               }
               const last = node.children.at(-1);
               if (last?.type === "element" && last.tagName === "span") {
@@ -109,7 +118,7 @@ export const useShikiHighlighter = createSingleton((opts) => {
         style: styles.join("")
       };
     } catch (error) {
-      console.warn("[@nuxtjs/mdc] Failed to highlight code block", error.message);
+      console.warn("[@nuxtjs/mdc] Failed to highlight code block:", error.message);
       return {
         tree: [{ type: "text", value: code }],
         className: "",

package/dist/runtime/shiki/index.mjs

@@ -7,7 +7,7 @@ const defaults = {
   },
   async highlighter(code, lang, theme, highlights) {
     if (process.browser && window.sessionStorage.getItem("mdc-shiki-highlighter") === "browser") {
-      return import("./highlighter").then(({ useShikiHighlighter }) => {
+      return import("./highlighter.mjs").then(({ useShikiHighlighter }) => {
         return useShikiHighlighter().getHighlightedAST(code, lang, theme, { highlights });
       });
     }
@@ -37,7 +37,7 @@ export function rehypeShiki(opts = {}) {
     const styles = [];
     visit(
       tree,
-      (node) => ["pre", "code"].includes(node.tagName) && !!node.properties?.language,
+      (node) => ["pre", "code"].includes(node.tagName) && !!(node.properties?.language || node.properties?.highlights),
       (node) => {
         const _node = node;
         const task = options.highlighter(

package/dist/types.d.mts

@@ -1,7 +1,8 @@
 
-import {  } from './module'
+import type {  } from './module'
 
 
 
 
-export { default } from './module'
+
+export type { default } from './module'

package/dist/types.d.ts

@@ -1,7 +1,8 @@
 
-import {  } from './module'
+import type {  } from './module'
 
 
 
 
-export { default } from './module'
+
+export type { default } from './module'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/mdc",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Nuxt MDC module",
   "repository": "nuxt-modules/mdc",
   "license": "MIT",
@@ -22,11 +22,11 @@
     "dist"
   ],
   "scripts": {
-    "prepack": "nuxi prepare playground; nuxt-module-build",
-    "build": "nuxi prepare playground; nuxt-module-build build",
+    "prepack": "nuxt-module-build prepare; nuxt-module-build",
+    "build": "nuxt-module-build prepare; nuxt-module-build build",
     "dev": "nuxi dev playground",
     "dev:build": "nuxi build playground",
-    "dev:prepare": "nuxt-module-build build --stub && nuxi prepare playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
     "dev:docs": "nuxi dev docs",
     "release": "release-it",
     "lint": "eslint .",
@@ -34,10 +34,10 @@
     "test:watch": "vitest watch"
   },
   "dependencies": {
-    "@nuxt/kit": "^3.8.0",
-    "@types/hast": "^3.0.2",
-    "@types/mdast": "^4.0.2",
-    "@vue/compiler-core": "^3.3.7",
+    "@nuxt/kit": "^3.8.2",
+    "@types/hast": "^3.0.3",
+    "@types/mdast": "^4.0.3",
+    "@vue/compiler-core": "^3.3.11",
     "consola": "^3.2.3",
     "defu": "^6.1.3",
     "destr": "^2.0.2",
@@ -47,41 +47,41 @@
     "mdast-util-to-hast": "^13.0.2",
     "micromark-util-sanitize-uri": "^2.0.0",
     "ohash": "^1.1.3",
-    "property-information": "^6.3.0",
+    "property-information": "^6.4.0",
     "rehype-external-links": "^3.0.0",
     "rehype-raw": "^6.1.1",
     "rehype-slug": "^6.0.0",
     "rehype-sort-attribute-values": "^5.0.0",
     "rehype-sort-attributes": "^5.0.0",
-    "remark-emoji": "^4.0.0",
+    "remark-emoji": "^4.0.1",
     "remark-gfm": "^3.0.1",
     "remark-mdc": "^2.1.0",
     "remark-parse": "^10.0.2",
     "remark-rehype": "^10.1.0",
-    "scule": "^1.1.0",
-    "shikiji": "^0.6.10",
-    "ufo": "^1.3.1",
-    "unified": "^11.0.3",
+    "scule": "^1.1.1",
+    "shikiji": "^0.9.3",
+    "ufo": "^1.3.2",
+    "unified": "^11.0.4",
     "unist-builder": "^4.0.0",
     "unist-util-visit": "^5.0.0"
   },
   "devDependencies": {
     "@nuxt/devtools": "latest",
     "@nuxt/eslint-config": "^0.2.0",
-    "@nuxt/module-builder": "^0.5.2",
-    "@nuxt/schema": "^3.8.0",
-    "@nuxt/test-utils": "^3.8.0",
-    "@nuxthq/ui": "^2.7.0",
-    "@types/mdurl": "^1.0.4",
-    "@types/node": "^20.8.9",
+    "@nuxt/module-builder": "^0.5.4",
+    "@nuxt/schema": "^3.8.2",
+    "@nuxt/test-utils": "^3.8.1",
+    "@nuxt/ui": "^2.11.1",
+    "@types/mdurl": "^1.0.5",
+    "@types/node": "^20.10.4",
     "changelogen": "^0.5.5",
-    "eslint": "^8.52.0",
-    "nuxt": "^3.8.0",
+    "eslint": "^8.55.0",
+    "nuxt": "^3.8.2",
     "rehype": "^13.0.1",
-    "release-it": "^16.2.1",
-    "vitest": "^0.34.6"
+    "release-it": "^17.0.1",
+    "vitest": "^1.0.4"
   },
-  "packageManager": "pnpm@8.9.2",
+  "packageManager": "pnpm@8.12.1",
   "release-it": {
     "git": {
       "commitMessage": "chore(release): release v${version}"