feat: introduce mdc.componenets.customElements (#444)

Ariges770 · farnabaz · web-flow · commit 10feeecc3545 · 2026-01-14T17:45:04.000+01:00
Co-authored-by: Farnabaz &lt;farnabaz@gmail.com&gt;
diff --git a/docs/0.index.md b/docs/0.index.md
@@ -247,14 +247,76 @@ export default defineNuxtConfig({
       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
-      }
+      },
+      customElements: [], // Custom element tags to ignore at MDC runtime (ex: ['mjx-container', 'my-element'])
     }
   }
 })
 ```
 
 Checkout [`ModuleOptions` types↗︎](https://github.com/nuxt-content/mdc/blob/main/src/module.ts).
 
+## Using Custom Elements
+There are two places where “custom elements” matter:
+
+- **Vue template compiler (compile-time)**: controls whether Vue treats `<my-element>` as a component or a custom element.
+- **MDC renderer (runtime)**: controls whether MDC tries to resolve a tag as a Vue component when rendering markdown.
+
+### Vue (compile-time)
+When using custom elements in Vue templates, configure Vue to recognize them by adding `vue.compilerOptions.isCustomElement` in your `nuxt.config.ts`.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  vue: {
+    compilerOptions: {
+      isCustomElement: (tag) => tag.startsWith('mjx')
+    }
+  }
+})
+```
+
+### MDC (runtime)
+MDC does not use Vue’s template compiler options when rendering markdown. To tell MDC which tags should be treated as custom elements (and therefore **not** resolved as Vue components), add them to `mdc.components.customElements`.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  mdc: {
+    components: {
+      customElements: ['mjx-container']
+    }
+  }
+})
+```
+
+When `mdc.components.customElements` is provided and `vue.compilerOptions.isCustomElement` is not already set, MDC will also configure Vue to treat those same tags as custom elements.
+
+Now you can use custom elements as below.
+
+```html [custom-element.vue]
+<script setup>
+const mdc = `
+# Custom elements can now be used
+
+::mjx-container
+This is rendered as a custom element
+::
+`
+</script>
+
+<style>
+my-element {
+    color: red;
+}
+</style>
+
+<template>
+  <div>
+    <MDC :value="mdc" />
+    <my-element>Another custom element</my-element>
+  </div>
+</template>
+```
+
 ## Contributing
 
 You can contribute to this module online with CodeSandbox:
diff --git a/src/module.ts b/src/module.ts
@@ -53,22 +53,29 @@ export default defineNuxtModule<ModuleOptions>({
     components: {
       prose: true,
       map: {},
+      customElements: [],
     },
   },
   async setup(options, nuxt) {
     resolveOptions(options)
 
     const resolver = createResolver(import.meta.url)
 
-    nuxt.options.runtimeConfig.public.mdc = defu(nuxt.options.runtimeConfig.public.mdc, {
+    const mdc = nuxt.options.runtimeConfig.public.mdc = defu(nuxt.options.runtimeConfig.public.mdc, {
       components: {
         prose: options.components!.prose!,
         map: options.components!.map!,
+        customElements: options.components?.customElements || [],
       },
       headings: options.headings!,
       highlight: options.highlight!,
     })
 
+    if (mdc.components.customElements.length > 0 && !nuxt.options.vue.compilerOptions?.isCustomElement) {
+      nuxt.options.vue.compilerOptions ||= {}
+      nuxt.options.vue.compilerOptions.isCustomElement = (tag: string) => mdc.components.customElements.includes(tag)
+    }
+
     nuxt.options.build.transpile ||= []
     nuxt.options.build.transpile.push('yaml')
 
@@ -273,6 +280,7 @@ declare module '@nuxt/schema' {
       components: {
         prose: boolean
         map: Record<string, string>
+        customElements: string[]
       }
       headings: ModuleOptions['headings']
       highlight: ModuleOptions['highlight']
@@ -286,6 +294,7 @@ declare module '@nuxt/schema' {
           components: {
             prose: boolean
             map: Record<string, string>
+            customElements: string[]
           }
         }
         headings: ModuleOptions['headings']
diff --git a/src/runtime/components/MDCRenderer.vue b/src/runtime/components/MDCRenderer.vue
@@ -20,7 +20,8 @@ const rxOn = /^@|^v-on:/
 const rxBind = /^:|^v-bind:/
 const rxModel = /^v-model/
 const nativeInputs = ['select', 'textarea', 'input']
-const specialParentTags = ['math', 'svg']
+const specialParentTags = new Set(['math', 'svg'])
+const customElements = new Set<string>()
 
 const proseComponentMap = Object.fromEntries(['p', 'a', 'blockquote', 'code', 'pre', 'code', 'em', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'img', 'ul', 'ol', 'li', 'strong', 'table', 'thead', 'tbody', 'td', 'th', 'tr', 'script'].map(t => [t, `prose-${t}`]))
 
@@ -89,6 +90,12 @@ export default defineComponent({
     const route = $nuxt?.$route || $nuxt?._route
     const { mdc } = $nuxt?.$config?.public || {}
 
+    // Custom elements
+    const customElementTags = mdc?.components?.customElements || mdc?.components?.custom
+    if (customElementTags) {
+      customElementTags.forEach((tag: string) => customElements.add(tag))
+    }
+
     const tags = computed(() => ({
       ...(mdc?.components?.prose && props.prose !== false ? proseComponentMap : {}),
       ...(mdc?.components?.map || {}),
@@ -99,7 +106,7 @@ export default defineComponent({
     const contentKey = computed(() => {
       const components = (props.body?.children || [])
         .map(n => (n as any).tag || n.type)
-        .filter(t => !htmlTags.includes(t))
+        .filter(t => !ignoreTag(t))
 
       return Array.from(new Set(components)).sort().join('.')
     })
@@ -400,7 +407,7 @@ function propsToDataRxBind(key: string, value: any, data: any, documentMeta: MDC
  */
 const resolveComponentInstance = (component: any) => {
   if (typeof component === 'string') {
-    if (htmlTags.includes(component)) {
+    if (ignoreTag(component)) {
       return component
     }
 
@@ -463,7 +470,7 @@ function isTemplate(node: MDCNode) {
  * Check if tag is a special tag that should not be resolved to a component
  */
 function isUnresolvableTag(tag: unknown) {
-  return specialParentTags.includes(tag as string)
+  return specialParentTags.has(tag as string)
 }
 
 /**
@@ -514,7 +521,7 @@ async function resolveContentComponents(body: MDCRoot, meta: Record<string, any>
 
     const components: string[] = []
 
-    if (node.type !== 'root' && !htmlTags.includes(renderTag as any)) {
+    if (node.type !== 'root' && !ignoreTag(renderTag as any)) {
       components.push(renderTag)
     }
     for (const child of (node.children || [])) {
@@ -533,4 +540,12 @@ function findMappedTag(node: MDCElement, tags: Record<string, string>) {
 
   return tags[tag] || tags[pascalCase(tag)] || tags[kebabCase(node.tag)] || tag
 }
+
+function ignoreTag(tag: string) {
+  // Checks if input tag is an html tag or
+  const isCustomEl = (typeof tag === 'string')
+    ? customElements.has(tag)
+    : false
+  return isCustomEl || htmlTags.has(tag)
+}
 </script>
diff --git a/src/runtime/parser/handlers/paragraph.ts b/src/runtime/parser/handlers/paragraph.ts
@@ -9,7 +9,7 @@ export default function paragraph(state: State, node: Paragraph) {
   if (node.children && node.children[0] && node.children[0].type === 'html') {
     const tagName = kebabCase(getTagName(node.children[0].value) || 'div')
     // Unwrap if component
-    if (!htmlTags.includes(tagName)) {
+    if (!htmlTags.has(tagName)) {
       return state.all(node)
     }
   }
diff --git a/src/runtime/parser/utils/html-tags-list.ts b/src/runtime/parser/utils/html-tags-list.ts
@@ -1,5 +1,5 @@
 // Ref https://github.com/sindresorhus/html-tags/blob/v3.2.0/html-tags.json
-export default [
+export default new Set([
   'a',
   'abbr',
   'address',
@@ -117,4 +117,4 @@ export default [
   'var',
   'video',
   'wbr',
-]
+])
diff --git a/src/types/module.ts b/src/types/module.ts
@@ -87,5 +87,9 @@ export interface ModuleOptions {
   components?: {
     prose?: boolean
     map?: Record<string, string>
+    /**
+     * Custom element tags to ignore at MDC runtime (ex: ['mjx-container', 'my-element'])
+     */
+    customElements?: string[]
   }
 }
diff --git a/test/basic.test.ts b/test/basic.test.ts
@@ -21,4 +21,12 @@ describe('ssr', async () => {
     expect(html).toContain('[Global Paragraph]')
     expect(html).toContain('Sample paragraph')
   })
+
+  it('respects mdc.components.customElements at MDC runtime', async () => {
+    const res = await $fetch('/api/is-custom-element', { query: { tag: 'x-foo' } }) as any
+    expect(res).toEqual({ tag: 'x-foo', isCustomElement: true })
+
+    const res2 = await $fetch('/api/is-custom-element', { query: { tag: 'div' } }) as any
+    expect(res2).toEqual({ tag: 'div', isCustomElement: false })
+  })
 })
diff --git a/test/fixtures/basic/nuxt.config.ts b/test/fixtures/basic/nuxt.config.ts
@@ -4,6 +4,11 @@ export default defineNuxtConfig({
   modules: [
     NuxtMDC,
   ],
+  mdc: {
+    components: {
+      customElements: ['x-foo'],
+    },
+  },
   future: {
     compatibilityVersion: 4,
   },
diff --git a/test/fixtures/basic/server/api/is-custom-element.get.ts b/test/fixtures/basic/server/api/is-custom-element.get.ts
@@ -0,0 +1,15 @@
+import { getQuery } from 'h3'
+import { useRuntimeConfig } from '#imports'
+
+export default defineEventHandler((event) => {
+  const query = getQuery(event)
+  const tag = String(query.tag || '')
+
+  const config = useRuntimeConfig()
+  const customElements = config.public?.mdc?.components?.customElements || []
+
+  return {
+    tag,
+    isCustomElement: customElements.includes(tag),
+  }
+})

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ export default function paragraph(state: State, node: Paragraph) {`
`9`	`9`	`if (node.children && node.children[0] && node.children[0].type === 'html') {`
`10`	`10`	`const tagName = kebabCase(getTagName(node.children[0].value) \|\| 'div')`
`11`	`11`	`// Unwrap if component`
`12`		`- if (!htmlTags.includes(tagName)) {`
	`12`	`+ if (!htmlTags.has(tagName)) {`
`13`	`13`	`return state.all(node)`
`14`	`14`	`}`
`15`	`15`	`}`
Original file line number	Diff line number	Diff line change
`@@ -87,5 +87,9 @@ export interface ModuleOptions {`
`87`	`87`	`components?: {`
`88`	`88`	`prose?: boolean`
`89`	`89`	`map?: Record<string, string>`
	`90`	`+ /**`
	`91`	`+ * Custom element tags to ignore at MDC runtime (ex: ['mjx-container', 'my-element'])`
	`92`	`+ */`
	`93`	`+ customElements?: string[]`
`90`	`94`	`}`
`91`	`95`	`}`