MDX技术指南：如何在MDX中优雅地嵌入第三方内容-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01161/article/details/148374968

MDX技术指南：如何在MDX中优雅地嵌入第三方内容

mdx Markdown for the component era 项目地址: https://gitcode.com/gh_mirrors/md/mdx

前言

在现代内容创作中，我们经常需要在文档中嵌入第三方内容，如YouTube视频、CodePen代码演示或Twitter推文等。MDX作为Markdown的超集，虽然本身不支持直接嵌入这些内容，但提供了灵活的解决方案。本文将深入探讨在MDX中实现内容嵌入的两种主要方法：编译时嵌入和运行时嵌入。

理解MDX的嵌入机制

MDX基于CommonMark标准，默认情况下不支持直接嵌入第三方内容。这意味着简单的Markdown语法无法直接渲染出复杂的嵌入组件。为了在MDX文档中实现丰富的嵌入功能，我们需要采用额外的技术手段。

编译时嵌入方案

编译时嵌入是指在MDX转换为最终输出格式（通常是JSX或HTML）的过程中处理嵌入内容。这种方法的主要优势是：

性能优异：所有处理都在构建阶段完成
无需客户端运行时依赖
生成静态内容，利于SEO

使用@remark-embedder/core实现

@remark-embedder/core是一个强大的工具，可以在编译阶段转换URL为实际的嵌入组件。以下是典型的使用示例：

import {compile} from '@mdx-js/mdx'
import fauxRemarkEmbedder from '@remark-embedder/core'
import fauxOembedTransformer from '@remark-embedder/transformer-oembed'

const remarkEmbedder = fauxRemarkEmbedder.default
const oembedTransformer = fauxOembedTransformer.default

const code = `
看看这个视频：

https://www.youtube.com/watch?v=dQw4w9WgXcQ
`

const result = await compile(code, {
  remarkPlugins: [
    [
      remarkEmbedder,
      {transformers: [oembedTransformer]}
    ]
  ]
})

这段代码会将YouTube URL转换为一个完整的iframe嵌入组件。转换后的输出大致如下：

<>
  <p>看看这个视频：</p>
  <iframe
    width="200"
    height="113"
    src="https://www.youtube.com/embed/dQw4w9WgXcQ?feature=oembed"
    frameBorder="0"
    allowFullScreen
    title="Rick Astley - Never Gonna Give You Up"
  />
</>

编译时嵌入的优缺点

优点：

最终用户无需加载额外JavaScript
内容立即可见，无需等待客户端请求
更好的SEO表现

缺点：

构建时间可能增加
需要预先知道所有可能的嵌入类型
内容更新需要重新构建

运行时嵌入方案

运行时嵌入将处理逻辑推迟到客户端执行，这种方式提供了更大的灵活性，但可能影响性能。

使用MDX Embed实现

MDX Embed是一个专门为MDX设计的React组件库，支持多种嵌入类型。基本用法如下：

import {CodePen} from 'mdx-embed'

这是一个CodePen示例，后面是其他博客内容。

<CodePen codePenId="PNaGbb" />

全局组件注入

如果不想在每个MDX文件中显式导入组件，可以通过两种方式全局注入：

方法一：直接传递所有组件

import * as embeds from 'mdx-embed'
import Example from './example.mdx'

function App() {
  return <Example components={{...embeds}} />
}

方法二：使用MDXEmbedProvider

import {MDXEmbedProvider} from 'mdx-embed'
import Example from './example.mdx'

function App() {
  return (
    <MDXEmbedProvider>
      <Example />
    </MDXEmbedProvider>
  )
}