Mdc · Nuxt 模块 - Nuxt 框架

Nuxt MDC

MDC 将普通 Markdown 增强，使其能够编写与任何 Vue 组件深度交互的文档。MDC 代表 Markdown 组件。

特性

混合使用 Markdown 语法和 HTML 标签或 Vue 组件
展开任何生成的內容（例如：每个 Markdown 段落添加的 <p>）
使用带有命名插槽的 Vue 组件
支持内联组件
向内联 HTML 标签添加属性和类

在 https://content.nuxtjs.org/guide/writing/mdc 上了解有关 MDC 语法的更多信息

！注意您可以在 Nuxt 项目（标准配置）或任何 Vue 项目中使用此包。
请参阅以下在您的 Vue 项目中渲染以获取更多信息。

安装

npx nuxi@latest module add mdc

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

nuxt.config.ts

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

就是这样！您可以在 Nuxt 项目中开始编写和渲染 Markdown 文件 ✨

渲染

@nuxtjs/mdc 公开了三个组件来渲染 Markdown 文件。

`<MDC>`

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

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

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

请注意，::alert 将使用 components/global/Alert.vue 组件。

`<MDCRenderer>`

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

mdc-test.vue

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

const { data: ast } = await useAsyncData('markdown', () => parseMarkdown('::alert\nMissing markdown input\n::'))
</script>

<template>
  <MDCRenderer :body="ast.body" :data="ast.data" />
</template>

`<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>

散文组件

散文组件是一系列组件，这些组件将代替常规 HTML 标签进行渲染。例如，@nuxtjs/mdc 渲染 <ProseP> 组件而不是渲染 <p> 标签。当您想要向 Markdown 文件添加额外功能时，这非常有用。例如，您可以向代码块添加“复制”按钮。

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

nuxt.config.ts

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

以下是可用散文组件的列表

标签	组件	源文件	描述
`p`	`<ProseP>`	ProseP.vue	段落
`h1`	`<ProseH1>`	ProseH1.vue	标题 1
`h2`	`<ProseH2>`	ProseH2.vue	标题 2
`h3`	`<ProseH3>`	ProseH3.vue	标题 3
`h4`	`<ProseH4>`	ProseH4.vue	标题 4
`h5`	`<ProseH5>`	ProseH5.vue	标题 5
`h6`	`<ProseH6>`	ProseH6.vue	标题 6
`ul`	`<ProseUl>`	ProseUl.vue	无序列表
`ol`	`<ProseOl>`	ProseOl.vue	有序列表
`li`	`<ProseLi>`	ProseLi.vue	列表项
`blockquote`	`<ProseBlockquote>`	ProseBlockquote.vue	块引用
`hr`	`<ProseHr>`	ProseHr.vue	水平线
`pre`	`<ProsePre>`	ProsePre.vue	预格式化文本
`code`	`<ProseCode>`	ProseCode.vue	代码块
`table`	`<ProseTable>`	ProseTable.vue	表格
`thead`	`<ProseThead>`	ProseThead.vue	表头
`tbody`	`<ProseTbody>`	ProseTbody.vue	表体
`tr`	`<ProseTr>`	ProseTr.vue	表格行
`th`	`<ProseTh>`	ProseTh.vue	表头单元格
`td`	`<ProseTd>`	ProseTd.vue	表格数据单元格
`a`	`<ProseA>`	ProseA.vue	锚链接
`img`	`<ProseImg>`	ProseImg.vue	图片
`em`	`<ProseEm>`	ProseEm.vue	强调
`strong`	`<ProseStrong>`	ProseStrong.vue	加粗

解析 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 组件内部。

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

const { data: ast } = await useAsyncData('markdown', () => parseMarkdown('::alert\nMissing markdown input\n::'))
</script>

<template>
  <MDCRenderer :body="ast.body" :data="ast.data" />
</template>

选项

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

名称	默认值	描述
`remark.plugins`	`{}`	注册/配置解析器的 remark 插件。
`rehype.options`	`{}`	配置 `remark-rehype` 选项。
`rehype.plugins`	`{}`	注册/配置解析器的 rehype 插件。
`highlight`	`false`	控制代码块是否应高亮显示。您也可以提供自定义高亮显示器。
`toc.depth`	`2`	要包含在目录中的最大标题深度。
`toc.searchDepth`	`2`	搜索标题的嵌套标签的最大深度。

查看 MDCParseOptions 类型↗︎。

配置

您可以通过在 nuxt.config.js 中提供 mdc 属性来配置模块；以下为默认选项

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

查看 ModuleOptions 类型↗︎。

在您的 Vue 项目中渲染

<MDCRenderer> 组件结合一些导出的包实用程序也可以在普通的（非 Nuxt）Vue 项目中使用。

要在标准 Vue 项目中实现，请按照以下说明操作。

安装包

按照上面安装说明操作，忽略将 Nuxt 模块添加到 nuxt.config.ts 文件中的步骤。

存根 Nuxt 模块导入

由于您没有使用 Nuxt，因此需要在 Vue 项目的 Vite 配置文件中存根一些模块的导入。这对于在模块尝试访问 Nuxt 特定导入时避免错误是必要的。

在 Vue 项目的根目录中创建一个新文件，例如 stub-mdc-imports.js，并添加以下内容

// stub-mdc-imports.js
export default {}

接下来，更新 Vue 项目的 Vite 配置文件（例如 vite.config.ts）以将模块的导入别名指向存根文件

import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '#mdc-imports': path.resolve(__dirname, './stub-mdc-imports.js'),
      '#mdc-configs': path.resolve(__dirname, './stub-mdc-imports.js'),
    }
  }
})

用法

接下来，让我们创建一个新的 Vue 组合式 API 来处理解析 Markdown 内容，以及使用 Shiki 为代码块添加语法高亮。

// composables/useMarkdownParser.ts
// Import package exports
import {
  createMarkdownParser,
  rehypeHighlight,
  createShikiHighlighter,
} from '@nuxtjs/mdc/runtime'
// Import desired Shiki themes and languages
import MaterialThemePalenight from 'shiki/themes/material-theme-palenight.mjs'
import HtmlLang from 'shiki/langs/html.mjs'
import MdcLang from 'shiki/langs/mdc.mjs'
import TsLang from 'shiki/langs/typescript.mjs'
import VueLang from 'shiki/langs/vue.mjs'
import ScssLang from 'shiki/langs/scss.mjs'
import YamlLang from 'shiki/langs/yaml.mjs'

export default function useMarkdownParser() {
  let parser: Awaited<ReturnType<typeof createMarkdownParser>>

  const parse = async (markdown: string) => {
    if (!parser) {
      parser = await createMarkdownParser({
        rehype: {
          plugins: {
            highlight: {
              instance: rehypeHighlight,
              options: {
                // Pass in your desired theme(s)
                theme: 'material-theme-palenight',
                // Create the Shiki highlighter
                highlighter: createShikiHighlighter({
                  bundledThemes: {
                    'material-theme-palenight': MaterialThemePalenight,
                  },
                  // Configure the bundled languages
                  bundledLangs: {
                    html: HtmlLang,
                    mdc: MdcLang,
                    vue: VueLang,
                    yml: YamlLang,
                    scss: ScssLang,
                    ts: TsLang,
                    typescript: TsLang,
                  },
                }),
              },
            },
          },
        },
      })
    }
    return parser(markdown)
  }

  return parse
}

现在，将我们刚刚创建的 useMarkdownParser 组合式 API 以及一个导出的类型接口导入到主机项目的 Vue 组件中，并使用它们来处理原始 Markdown 并初始化 <MDCRenderer> 组件。

<script setup lang="ts">
import { onBeforeMount, ref, watch } from 'vue'
// Import package exports
import MDCRenderer from '@nuxtjs/mdc/runtime/components/MDCRenderer.vue'
import type { MDCParserResult } from '@nuxtjs/mdc'
import useMarkdownParser from './composables/useMarkdownParser';

const md = ref(`
# Just a Vue app

This is markdown content rendered via the \`<MDCRenderer>\` component, including MDC below.

::alert
Hello MDC
::

\`\`\`ts
const a = 1;
\`\`\`
`);

const ast = ref<MDCParserResult | null>(null)
const parse = useMarkdownParser()

onBeforeMount(async () => {
  ast.value = await parse(md.value)
})
</script>

<template>
  <Suspense>
    <MDCRenderer v-if="ast?.body" :body="ast.body" :data="ast.data" />
  </Suspense>
</template>

贡献

您可以使用 StackBlitz 在线深入了解此模块

或在本地

克隆此仓库
使用 pnpm install 安装依赖项
使用 pnpm dev 启动开发服务器

许可证

MIT 许可证