嵌入

¥Embed

本指南探讨了如何在 Markdown 中嵌入推文、要点或代码笔等内容。 MDX 支持标准 Markdown 语法 (CommonMark)。默认情况下它不支持嵌入。

¥This guide explores how to embed things like tweets, gists or codepens in markdown. MDX supports standard markdown syntax (CommonMark). It does not support embeds by default.

有两种方法可以实现嵌入：在编译时或运行时。在编译时执行此操作意味着预先花费精力，以便读者可以获得快速的体验，因为无需向客户端发送请求。在运行时执行此操作可以将工作转移给客户端，从而提供更大的灵活性。但这可能会导致读者体验缓慢。它还取决于你使用的框架（例如特定于 React、Preact、Vue 等）

¥There are two ways to accomplish embeds: at compile time or at runtime. Doing it at compile time means the effort is spent upfront so that readers will have a fast experience as no requests have to be made on the client. Doing it at runtime gives more flexibility by moving the work to the client. This can result in a slow experience for readers though. It also depends on what framework you use (as in it’s specific to React, Preact, Vue, etc.)

编译时嵌入

¥Embeds at compile time

你可以通过执行以下操作来使用 @remark-embedder/core：

¥You can use @remark-embedder/core by doing something like this:

import {compile} from '@mdx-js/mdx'
// Note: `@remark-embedder` is currently using faux-esm.
import fauxRemarkEmbedder from '@remark-embedder/core'
import fauxOembedTransformer from '@remark-embedder/transformer-oembed'

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

const code = `
Check out this video:

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

console.log(
  String(
    await compile(code, {
      remarkPlugins: [
        [
          // @ts-expect-error: `remarkEmbedder` types are wrong.
          remarkEmbedder,
          {transformers: [oembedTransformer]}
        ]
      ]
    })
  )
)

<>
  <p>Check out this video:</p>
  <iframe
    width="200"
    height="113"
    src="https://www.youtube.com/embed/dQw4w9WgXcQ?feature=oembed"
    frameBorder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    allowFullScreen
    title="Rick Astley - Never Gonna Give You Up (Official Music Video)"
  ></iframe>
</>

在运行时嵌入

¥Embeds at run time

你可以使用 React 特定的 MDX 嵌入 将内容嵌入到 MDX 中。以下是使用不带 @mdx-js/react 的特定嵌入的示例 MDX 文件：

¥You can use the React-specific MDX Embed to embed things in MDX. Here is an example MDX file that uses a specific embed without @mdx-js/react:

import {CodePen} from 'mdx-embed'

Here’s a codepen, and some other blog post text.

<CodePen codePenId="PNaGbb" />

<>
  <p>Here’s a codepen, and some other blog post text.</p>
  <CodePen codePenId="PNaGbb" />
</>

如果你不想在 MDX 文件中使用显式导入：

¥If you don’t want to use explicit imports in MDX files:

Here’s a codepen, and some other blog post text.

<CodePen codePenId="PNaGbb" />

然后你可以传递所有组件：

¥Then you can either pass all components:

import * as embeds from 'mdx-embed'
import Example from './example.mdx' // Assumes an integration is used to compile MDX -> JS.

<Example components={...embeds} />

或者，如果你已经安装并配置了 @mdx-js/react，你也可以使用 MDXEmbedProvider：

¥Or, if you’ve installed and configured @mdx-js/react, you can also use MDXEmbedProvider:

import {MDXEmbedProvider} from 'mdx-embed'
import Example from './example.mdx' // Assumes an integration is used to compile MDX -> JS.

<MDXEmbedProvider>
  <Example />
</MDXEmbedProvider>