Lzh on GitHub

Nuxt MDC

MDC 代表 Markdown 组件。这种语法增强了普通的 Markdown，可以编写与任何 Vue 组件深度交互的文档。

Nuxt MDC

MDC 代表 Markdown 组件。这种语法增强了普通的 Markdown，可以编写与任何 Vue 组件深度交互的文档。

设置

将 @nuxtjs/mdc 依赖添加到你的项目中：

npx nuxi@latest module add mdc

然后，将 @nuxtjs/mdc 添加到你的 nuxt.config.ts 文件的 modules 部分：

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/mdc']
})

搞定！你可以开始编写和渲染 markdown 文件了 ✨

实时演示

解析 Markdown

Nuxt MDC 公开了一个方便的助手函数来解析 MDC 文件。你可以从 @nuxtjs/mdc/runtime 导入 parseMarkdown 函数，并使用它来解析使用 MDC 语法编写的 markdown 文件。

Node.js

/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
})

浏览器

parseMarkdown 函数是一个通用的助手函数，你也可以在浏览器中使用它，例如在 Vue 组件内部。

mdc-test.vue
<template>
  <div>This is a test</div>
</template>

<script setup lang="ts">
import { parseMarkdown } from '@nuxtjs/mdc/runtime'

const props = defineProps({
  md: {
    type: String,
    default: () => '::alert\nMissing markdown input\n::'
  }
})

const ast = await parseMarkdown(props.md)
</script>

选项

parseMarkdown 助手函数还接受第二个参数作为选项，以控制解析器的行为。（查看 MDCParseOptions 接口︎）。

名称默认值描述
remark.plugins{}注册/配置解析器的 remark 插件。
rehype.options{}配置 remark-rehype 选项。
rehype.plugins{}注册/配置解析器的 rehype 插件。
highlightfalse控制是否高亮代码块。你也可以提供一个自定义的高亮器。
toc.depth2目录中包含的最大标题深度。
toc.searchDepth2搜索标题的最大嵌套标签深度。

查看 MDCParseOptions 类型 。

渲染 (Vue)

@nuxtjs/mdc 公开了三个用于渲染 markdown 文件的组件。

<MDCRenderer>

此组件将接收 parseMarkdown 函数的结果并渲染内容。例如，这是 浏览器部分 中示例代码的扩展版本，它使用 MDCRenderer 来渲染解析后的 markdown。

mdc-test.vue
<template>
  <MDCRenderer :body="ast.body" :data="ast.data" />
</template>

<script setup lang="ts">
import { parseMarkdown } from '@nuxtjs/mdc/runtime'

const props = defineProps({
  md: {
    type: String,
    default: () => '::alert\nMissing markdown input\n::'
  }
})

const ast = await parseMarkdown(props.md)
</script>

<MDCSlot>

此组件是 Vue 的 <slot/> 组件的替代品，专门为 MDC 设计。使用此组件，你可以在移除一个或多个包装元素的同时渲染组件的子元素。在下面的示例中，Alert 组件接收文本及其默认插槽（子元素）。但是，如果该组件使用普通的 <slot/> 渲染此插槽，它将在文本周围渲染一个 <p> 元素。

markdown.md
::alert
This is an Alert
::
Alert.vue
<template>
  <div class="alert">
    <!-- Slot will render <p> tag around the text -->
    <slot />
  </div>
</template>

Markdown 的默认行为是将每个文本都包裹在段落中。MDC 的目标不是破坏 markdown 的行为；相反，MDC 的目标是使 markdown 更加强大。在这个示例和所有类似的情况下，你可以使用 <MDCSlot /> 来移除不需要的包装器。

Alert.vue
<template>
  <div class="alert">
    <!-- MDCSlot will only render the actual text without the wrapping <p> -->
    <MDCSlot unwrap="p" />
  </div>
</template>

<MDC>

使用 <MDC>，你可以在你的组件/页面中直接解析和渲染 markdown 内容。此组件接收原始 markdown，使用 parseMarkdown 函数解析它，然后使用 <MDCRenderer> 渲染它。

<template>
  <MDC :value="md"  tag="article" />
</template>

<script setup lang="ts">
const md = `
::alert
Hello MDC
::
`
</script>

Prose 组件

Prose 组件是一个组件列表，它们将被渲染以替代常规 HTML 标签。例如，@nuxtjs/mdc 不会渲染 <p> 标签，而是渲染 <ProseP> 组件。当你想要向 markdown 文件添加额外的功能时，这非常有用。例如，你可以向代码块添加一个 copy 按钮。

你可以通过在 nuxt.config.ts 中将 prose 选项设置为 false 来禁用 prose 组件。或者扩展 prose 组件的映射以添加你自己的组件。

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/mdc'],
  mdc: {
    components: {
      prose: false, // Disable predefined prose components
      map: {
        p: 'MyCustomPComponent'
      }
    }
  }
})

以下是可用的 prose 组件列表：

标签组件来源描述
p<ProseP>ProseP.vueParagraph
h1<ProseH1>ProseH1.vueHeading 1
h2<ProseH2>ProseH2.vueHeading 2
h3<ProseH3>ProseH3.vueHeading 3
h4<ProseH4>ProseH4.vueHeading 4
h5<ProseH5>ProseH5.vueHeading 5
h6<ProseH6>ProseH6.vueHeading 6
ul<ProseUl>ProseUl.vueUnordered List
ol<ProseOl>ProseOl.vueOrdered List
li<ProseLi>ProseLi.vueList Item
blockquote<ProseBlockquote>ProseBlockquote.vueBlockquote
hr<ProseHr>ProseHr.vueHorizontal Rule
pre<ProsePre>ProsePre.vuePreformatted Text
code<ProseCode>ProseCode.vueCode Block
table<ProseTable>ProseTable.vueTable
thead<ProseThead>ProseThead.vueTable Head
tbody<ProseTbody>ProseTbody.vueTable Body
tr<ProseTr>ProseTr.vueTable Row
th<ProseTh>ProseTh.vueTable Header
td<ProseTd>ProseTd.vueTable Data
a<ProseA>ProseA.vueAnchor Link
img<ProseImg>ProseImg.vueImage
em<ProseEm>ProseEm.vueEmphasis
strong<ProseStrong>ProseStrong.vueStrong

配置

你可以在你的 nuxt.config.js 文件中提供 mdc 属性来配置模块；以下是默认选项：

nuxt.config.js
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
      }
    }
  }
})

Checkout ModuleOptions types↗︎.