MDX

MDXMDX 更新https://mdx.ndjp.net/Tue, 07 Jul 2026 16:54:04 GMT2026-07-07T16:54:04.929Zzhzh© 2026 MDX 贡献者© 2026 MDX 贡献者mdxmarkdownjsxossreactMDX 3Titus Wormerhttps://mdx.ndjp.net/blog/v3/https://mdx.ndjp.net/blog/v3/Tue, 24 Oct 2023 00:00:00 GMT2023-10-24T00:00:00.000Z2025-01-27T00:00:00.000Z<div><div>注意：有关如何迁移的信息，请参阅我们的 <a href="/migrating/v3/">版本 3 迁移指南</a>。</div><h2 id="mdx-3"><a href="#mdx-3" class="" aria-label="Link to this section"></a>MDX 3</h2>版本 3 来了！这个主版本包含了一些小的变更。对于大多数人来说，只需要更新 Node.js 和插件即可！<h3 id="目录"><a href="#目录" class="" aria-label="Link to this section"></a>目录</h3><ul><li><a href="#%E7%A0%B4%E5%9D%8F%E6%80%A7%E5%8F%98%E6%9B%B4">破坏性变更</a></li><li><a href="#mdx-%E6%A0%BC%E5%BC%8F%E7%9A%84%E6%94%B9%E8%BF%9B">MDX 格式的改进</a><ul><li><a href="#mdx-%E4%B8%AD%E7%9B%B8%E9%82%BB%E7%9A%84%E5%9D%97%E7%BA%A7-jsx-%E5%92%8C%E8%A1%A8%E8%BE%BE%E5%BC%8F">MDX 中相邻的块级 JSX 和表达式</a></li><li><a href="#mdx-%E4%B8%AD%E7%9A%84-await">MDX 中的 await</a></li><li><a href="#mdx-%E4%B8%AD%E7%9A%84-es2024">MDX 中的 ES2024</a></li></ul></li><li><a href="#%E5%85%B6%E4%BB%96">其他</a></li><li><a href="#%E8%87%B4%E8%B0%A2">致谢</a></li></ul><h3 id="破坏性变更"><a href="#破坏性变更" class="" aria-label="Link to this section"></a>破坏性变更</h3>主要的破坏性变更是 Node.js 16 现在是最低支持的版本。在整个生态系统中，有几个小的内部破坏性变更。所有内容都已经发布了。你现在可以更新所有插件。如果你之前遇到了问题，现在应该可以正常工作了。我们还移除了一些不常用的已废弃 API。你可能不会受到影响，但如果遇到错误，请查看 <a href="/migrating/v3/">v3 迁移指南</a>。需要注意的是，当你使用不太知名但强大的 <code>evaluate</code>、<code>run</code> 或 <code>outputFormat: 'function-body'</code> API 时，请传递 <code>baseUrl</code> 选项。这样可以确保 <code>import.meta.url</code>、<code>import</code> 和 <code>export</code> 正常工作。否则，当使用这些功能时会收到运行时错误。<h3 id="mdx-格式的改进"><a href="#mdx-格式的改进" class="" aria-label="Link to this section"></a>MDX 格式的改进</h3>MDX 格式还有一些小的改进，其中一些在技术上是破坏性的。<h4 id="mdx-中相邻的块级-jsx-和表达式"><a href="#mdx-中相邻的块级-jsx-和表达式" class="" aria-label="Link to this section"></a>MDX 中相邻的块级 JSX 和表达式</h4>我们现在接受块级表达式紧挨着块级 JSX 标签：<pre><code class="language-mdx"><style>{` h1 { color: blue; } `}</style> </code></pre>以前这会产生语法错误，你必须在尖括号和花括号之间添加换行符。<h4 id="mdx-中的-await"><a href="#mdx-中的-await" class="" aria-label="Link to this section"></a>MDX 中的 await</h4>我们现在接受 <code>await</code> 语法：<div><div>MDX</div><pre><code class="language-mdx">{await Promise.resolve(42)} </code></pre></div>大多数框架不支持 Promise。这是否有效取决于框架本身。以前，当在不允许的上下文中使用 <code>await</code> 时会产生运行时错误。<h4 id="mdx-中的-es2024"><a href="#mdx-中的-es2024" class="" aria-label="Link to this section"></a>MDX 中的 ES2024</h4>你现在可以在 MDX 中使用现代 JavaScript 语法。内部使用的 Acorn 现在被指示使用 ES2024。<h3 id="其他"><a href="#其他" class="" aria-label="Link to this section"></a>其他</h3>我重构了所有文档。根据需要更新了每个使用示例。我还写了一篇关于如何从任何地方注入组件的指南： <a href="/guides/injecting-components/">§ 注入组件</a>。网站速度快了很多。还有一个改进的 playground：<a href="/playground/">试试看！»</a>。我们还在这里有了正确的语法高亮，感谢 <a href="//github.com/wooorm/markdown-tm-language"><code>wooorm/markdown-tm-language</code></a> 和 <a href="//github.com/wooorm/starry-night"><code>wooorm/starry-night</code></a>。生成的 JS 代码更干净了（移除了 JSX pragma 注释，并在需要时对对象进行排序），还使用了展开运算符代替 <code>Object.assign</code>，在需要时添加了 <code>'use strict'</code>，并且 <code>MDXContent</code> 被立即导出。<h3 id="致谢"><a href="#致谢" class="" aria-label="Link to this section"></a>致谢</h3>我们要感谢所有的贡献者和开心的用户。特别感谢北雁云依 (<a href="//github.com/BeiyanYunyi">@BeiyanYunyi</a>), Christian Murphy (<a href="//github.com/ChristianMurphy">@ChristianMurphy</a>), JokcyLou (<a href="//github.com/Jokcy">@Jokcy</a>), Maël Nison (<a href="//github.com/arcanis">@arcanis</a>), Andreas Deininger (<a href="//github.com/deining">@deining</a>), Remco Haszing (<a href="//github.com/remcohaszing">@remcohaszing</a>), Sébastien Lorber (<a href="//github.com/slorber">@slorber</a>), Víctor Fernández (<a href="//github.com/victor23k">@victor23k</a>), Titus Wormer (<a href="//github.com/wooorm">@wooorm</a>), 以及任何我们可能遗漏的人。</div>MDX 2Titus Wormerhttps://mdx.ndjp.net/blog/v2/https://mdx.ndjp.net/blog/v2/Tue, 01 Feb 2022 00:00:00 GMT2022-02-01T00:00:00.000Z2025-01-27T00:00:00.000Z<div><div>注意：这是一篇旧的博客文章。以下内容为历史目的而保留原样。</div><div>注意：有关如何迁移的信息，请参阅我们的 <a href="/migrating/v2/">版本 2 迁移指南</a>。</div><h2 id="mdx-2"><a href="#mdx-2" class="" aria-label="Link to this section"></a>MDX 2</h2>经过多年的努力，MDX 版本 2 发布了，包含了许多改进。以下是亮点：<div><ul><li>📝 改进的语法 让在 JSX 中使用 Markdown 更容易</li><li>🧑‍💻 JavaScript 表达式 将 <code>{2 * Math.PI}</code> 变成 6.283185307179586</li><li>🔌 新的 esbuild、Rollup 和 Node.js 集成</li><li>⚛️ 任何 JSX 运行时：React、Preact、Vue、Emotion，你说的出来的都支持</li><li>🌳 改进的 AST 暴露了更多更详细的信息</li><li>🏃‍♀️ 编译速度至少快了 25%</li><li>🚴 生成的代码运行速度快了两倍（快 100%）</li><li>🚄 <code>@mdx-js/mdx</code> 的打包体积小了三倍多（小 250%）</li><li>🧵 ……还有更多更多</li></ul></div>这个项目公布已经 4 年了。距离我们发布稳定的版本 1 已经过了 2 年半。 我们很自豪终于发布 v2！ 让我们深入看看！<h3 id="目录"><a href="#目录" class="" aria-label="Link to this section"></a>目录</h3><ul><li><a href="#mdx-%E6%A0%BC%E5%BC%8F%E7%9A%84%E6%94%B9%E8%BF%9B">MDX 格式的改进</a></li><li><a href="#rollupesbuild-%E5%92%8C%E5%85%B6%E4%BB%96%E9%9B%86%E6%88%90">Rollup、esbuild 和其他集成</a></li><li><a href="#%E6%9E%B6%E6%9E%84%E6%94%B9%E8%BF%9B">架构改进</a></li><li><a href="#typescript">TypeScript</a></li><li><a href="#%E6%96%87%E6%A1%A3%E5%92%8C%E7%BD%91%E7%AB%99">文档和网站</a></li><li><a href="#%E7%A0%B4%E5%9D%8F%E6%80%A7%E5%8F%98%E6%9B%B4">破坏性变更</a></li><li><a href="#%E8%87%B4%E8%B0%A2">致谢</a></li></ul><h3 id="mdx-格式的改进"><a href="#mdx-格式的改进" class="" aria-label="Link to this section"></a>MDX 格式的改进</h3>我们花了很多时间思考和尝试不同的方式来改进格式。最初，格式非常接近 Markdown 以及 Markdown 中 HTML 的工作方式。我们发现旧行为经常产生意外的结果。在版本 2 中，我们将格式稍微向 JS(X) 的工作方式靠拢。以这个 MDX 文件为例：<pre><code class="language-mdx"><div>*hi*?</div> <div> # hi? </div> <main> <div> # hi? </div> </main> </code></pre><div><div>在版本 1 中，它等价于以下 JSX：<pre><code class=""><> <div>*hi*?</div> <div> # hi? </div> <main> <div> <pre><code># hi?</code></pre> </div> </main> </> </code></pre></div><div>在版本 2 中，它等价于以下 JSX：<pre><code class=""><> <div><em>hi</em>?</div> <div> <h1>hi?</h1> </div> <main> <div> <h1>hi?</h1> </div> </main> </> </code></pre></div></div>我们认为以下行为更直观：同一行标签之间可以形成 Markdown "行内"语法如强调（第一个 <code><div></code>），如果标题在自己的行上则可以形成"块" （第二个 <code><div></code>），并且允许缩进而不是形成代码（第三个 <code><div></code>）。我们还添加了对 JavaScript 表达式的支持，例如：<div><div><div><div>expressions.mdx</div><pre><code class="language-mdx">export const authors = [ {name: 'Jane', email: 'hi@jane.com'}, {name: 'John', github: '@johno'} ] export const published = new Date('2022-02-01') Written by: {new Intl.ListFormat('en').format(authors.map(d => d.name))}. Published on: {new Intl.DateTimeFormat('en', {dateStyle: 'long'}).format(published)}. </code></pre></div></div><div><div><div>equivalent.jsx</div><pre><code class=""><> <p>Written by: Jane and John.</p> <p>Published on: February 1, 2022.</p> </> </code></pre></div></div></div>随着格式从 Markdown 稍微向 JSX 靠拢，我们添加了对加载不带我们语法扩展的 "普通" Markdown 的支持。如果你使用我们的打包器集成 <code>@mdx-js/loader</code>（或 <code>@mdx-js/rollup</code>、 <code>@mdx-js/esbuild</code> 或 <code>@mdx-js/node-loader</code>，见下一节），那么它就能直接工作：导入 <code>readme.mdx</code> 会被视为 MDX 格式，导入 <code>readme.md</code> 会被视为 Markdown，基于它们的扩展名。MDX 格式在 <a href="/docs/what-is-mdx/">§ 什么是 MDX</a> 中有描述。<h3 id="rollupesbuild-和其他集成"><a href="#rollupesbuild-和其他集成" class="" aria-label="Link to this section"></a>Rollup、esbuild 和其他集成</h3>当我们开始时，Babel、webpack 和 React 在 JavaScript 生态系统中无处不在，我们在它们之上构建了 MDX。对于版本 2，我们努力使它们变为可选。它们不再是必需的，MDX 可以更轻松地与其他工具一起使用。在打包器方面，我们添加了新的集成：<code>@mdx-js/esbuild</code> 用于 esbuild（一个极快的打包器）和 <code>@mdx-js/rollup</code> 用于 Rollup（也用于 Vite 和 WMR 的打包器）。你甚至可以使用我们新的 <code>@mdx-js/node-loader</code> 在 Node.js 中直接导入 MDX 文件。在运行时方面，我们现在可以将 JSX 编译为普通 JavaScript，不再需要框架特定的代码来将它们与 MDX 粘合在一起。现在支持任何 JSX 运行时，无论是 <a href="//reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html">classic 还是 automatic</a>。这意味着 MDX 可以与 React、Preact、Vue、Emotion、Theme UI、Ink 等一起使用，还有未来发明的任何东西！参见 <a href="/docs/getting-started/">§ 快速开始</a> 了解快速入门以及如何将 MDX 与许多不同工具集成的深入信息。<h3 id="架构改进"><a href="#架构改进" class="" aria-label="Link to this section"></a>架构改进</h3>为了使 MDX 格式的语法更好，并允许新的集成和任意 JSX 运行时，我们几乎重写了所有内容。其中一部分工作是 <a href="//github.com/micromark/micromark">micromark</a>，那是另一个故事，但这意味着我们完全符合 CommonMark（和可选的 GFM），同时还能更好地理解 MDX 文件。现在，当有拼写错误时，我们可以提前抛出错误并准确指向发生位置，而不是让 webpack 等后续打包器抱怨一个中间的、不可识别的、损坏的 JavaScript 字符串中的错误。这也意味着我们有一个新的 AST，更详细地描述了 MDX 语法—— 我们甚至暴露了嵌入的 JavaScript。这个详细的 AST 允许插件以强大的新方式增强 MDX。它还帮助解决了以前 MDX 会崩溃的边缘情况。并且它让我们可以放弃 Babel。这种新架构带来了 25% 更快 的编译速度，运行速度快两倍的生成代码（快 100%），以及 <code>@mdx-js/mdx</code> 的打包体积小了三倍多（小 250%）。参见 <a href="/packages/mdx/#architecture">¶ <code>@mdx-js/mdx</code> 中的架构</a> 了解更多关于编译器工作原理的信息。参见 <a href="/docs/extending-mdx/">§ 扩展 MDX</a> 了解几个使用新树来增强 MDX 的插件、如何使用它们和其他插件，以及如何创建插件。<h3 id="typescript"><a href="#typescript" class="" aria-label="Link to this section"></a>TypeScript</h3>所有 <a href="/packages/"><code>@mdx-js/*</code> 包</a> 现在通过 JSDoc 注释完全使用 <a href="//www.typescriptlang.org">TypeScript</a> 进行了类型标注。这意味着我们的 API 以 TypeScript 类型暴露，而且我们的项目内部也是类型安全的。我们发布了 <a href="//github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/mdx"><code>@types/mdx</code></a>，一个仅包含类型的包，可以与任何（社区）集成一起使用。如果你导入 MDX 文件，你可以使用它来为那些导入的组件进行类型标注。参见 <a href="/docs/getting-started/#types">§ 快速开始中的 ¶ TypeScript</a> 了解更多关于如何配置 TypeScript 的信息。<h3 id="文档和网站"><a href="#文档和网站" class="" aria-label="Link to this section"></a>文档和网站</h3>MDX 被大量使用和喜爱。在版本 1 之前，我们累计了 250 万次下载。现在我们每周就达到这个数字。我们的核心编译器 <code>@mdx-js/mdx</code> 被 6.1 万个项目使用。我们的 GitHub 仓库有 1.16 万 stars。很多人帮忙，通常是帮忙改进文档。自版本 1 以来，有 85 位贡献者提交了我们的仓库。我们感谢这些贡献和所有个人见解，但这些年来确实导致了一些不一致和重复内容。对于版本 2，我们从头到尾重写了文档，为新用户、做复杂 AST 和编译器的人以及介于两者之间的任何人讲述一个一致的故事。我们还做了一个新网站。它当然是用 MDX 构建的，<a href="//unifiedjs.com">unified</a> 本身，以及 <a href="//reactjs.org/blog/2020/12/21/data-fetching-with-react-server-components.html">React Server Components (RSC)</a>。虽然我们在吃自己的狗粮（前两者是我们维护的项目），而后者还非常实验性，但我们认为提前编译和混合模型，与完全服务端网站或完全客户端应用相比，对我们和 Web 的未来是明智的选择。我们的新网站经过高度优化且快速，美观（主观的，但嘿），有丰富的元数据，在 Lighthouse 和 axe 等性能和可访问性审查工具中得分很高。参见 <a href="/community/contribute/">§ 贡献</a> 了解更多关于如何帮助的信息。<h3 id="破坏性变更"><a href="#破坏性变更" class="" aria-label="Link to this section"></a>破坏性变更</h3>当你准备好迁移时，请参阅 <a href="/migrating/v2/">版本 2 迁移指南</a>。<h3 id="致谢"><a href="#致谢" class="" aria-label="Link to this section"></a>致谢</h3>我们要感谢所有的贡献者和开心的用户。特别感谢 John Otander (<a href="//github.com/johno">@johno</a>), Christian Murphy (<a href="//github.com/ChristianMurphy">@ChristianMurphy</a>), JounQin (<a href="//github.com/JounQin">@JounQin</a>), Jack Bates (<a href="//github.com/jablko">@jablko</a>), Sam Chen (<a href="//github.com/chenxsan">@chenxsan</a>), Sam Robbins (<a href="//github.com/samrobbins85">@samrobbins85</a>), Remco Haszing (<a href="//github.com/remcohaszing">@remcohaszing</a>), LB (<a href="//github.com/laurieontech">@laurieontech</a>), Gabriel Kirkley (<a href="//github.com/gdgkirkley">@gdgkirkley</a>>), Hung-I Wang (<a href="//github.com/Gowee">@Gowee</a>), Ilham Wahabi (<a href="//github.com/iwgx">@iwgx</a>), Kaito Sugimoto (<a href="//github.com/HelloRusk">@HelloRusk</a>), Karl Horky (<a href="//github.com/karlhorky">@karlhorky</a>), Katie Hughes (<a href="//github.com/glitteringkatie">@glitteringkatie</a>), Lachlan Campbell (<a href="//github.com/lachlanjc">@lachlanjc</a>), Marcy Sutton (<a href="//github.com/marcysutton">@marcysutton</a>), Marius Gundersen (<a href="//github.com/mariusGundersen">@mariusGundersen</a>), Marius-Remus Mate, Mark Skelton (<a href="//github.com/mskelton">@mskelton</a>), Martin V (<a href="//github.com/ndresx">@ndresx</a>), Matija Marohnić (<a href="//github.com/silvenon">@silvenon</a>), Michael Oliver (<a href="//github.com/michaeloliverx">@michaeloliverx</a>), Michaël De Boey (<a href="//github.com/MichaelDeBoey">@MichaelDeBoey</a>), Muescha (<a href="//github.com/muescha">@muescha</a>), Norviah (<a href="//github.com/Norviah">@Norviah</a>), Paul Scanlon (<a href="//github.com/PaulieScanlon">@PaulieScanlon</a>), Peter Mouland (<a href="//github.com/peter-mouland">@peter-mouland</a>), Prince Wilson (<a href="//github.com/maxcell">@maxcell</a>), Rafael Almeida (<a href="//github.com/rafaelalmeidatk">@rafaelalmeidatk</a>), Rodrez (<a href="//github.com/rodrez">@rodrez</a>), Rongjian Zhang (<a href="//github.com/pd4d10">@pd4d10</a>), Taeheon Kim (<a href="//github.com/lonyele">@lonyele</a>), Tom Parker-Shemilt (<a href="//github.com/palfrey">@palfrey</a>), Try Ajitiono (<a href="//github.com/imballinst">@imballinst</a>), Yamagishi Kazutoshi (<a href="//github.com/ykzts">@ykzts</a>), Yoav Kadosh (<a href="//github.com/ykadosh">@ykadosh</a>), Yordis Prieto (<a href="//github.com/Yordis">@Yordis</a>), Adrian Foong (<a href="//github.com/adrfoong">@adrfoong</a>), Dan Abramov (<a href="//github.com/gaearon">@gaearon</a>), <a href="//github.com/ihupoo">@ihupoo</a>, <a href="//github.com/nikhog">@nikhog</a>, <a href="//github.com/redallen">@redallen</a>, Akshay Kadam (<a href="//github.com/deadcoder0904">@deadcoder0904</a>), я котик пур-пур (<a href="//github.com/mvasilkov">@mvasilkov</a>), Anders D. Johnson (<a href="//github.com/AndersDJohnson">@AndersDJohnson</a>), Andrew Aylett (<a href="//github.com/andrewaylett">@andrewaylett</a>), Ankeet Maini (<a href="//github.com/ankeetmaini">@ankeetmaini</a>), Biswas Nandamuri (<a href="//github.com/Biswas-N">@Biswas-N</a>), Bret (<a href="//github.com/bcomnes">@bcomnes</a>), Chris Chinchilla (<a href="//github.com/ChrisChinchilla">@ChrisChinchilla</a>), Christopher Biscardi (<a href="//github.com/ChristopherBiscardi">@ChristopherBiscardi</a>), Dan Overton (<a href="//github.com/dan-overton">@dan-overton</a>), Domitrius (<a href="//github.com/domitriusclark">@domitriusclark</a>), Dovi Winberger (<a href="//github.com/dowi">@dowi</a>), Emmie Päivärinta (<a href="//github.com/emmiep">@emmiep</a>), Eugene Ghanizadeh (<a href="//github.com/loreanvictor">@loreanvictor</a>), 以及任何我们可能遗漏的人。</div>MDXConfJohn Otanderhttps://mdx.ndjp.net/blog/conf/https://mdx.ndjp.net/blog/conf/Fri, 31 Jul 2020 00:00:00 GMT2020-07-31T00:00:00.000Z2025-01-27T00:00:00.000Z<div><div>注意：这是一篇旧的博客文章。以下内容为历史目的而保留原样。</div><h2 id="mdxconf"><a href="#mdxconf" class="" aria-label="Link to this section"></a>MDXConf</h2>MDXConf 是为 MDX 社区举办的免费在线会议。无论你刚开始了解 MDX 还是已经是专家，都会有适合你的内容！2020 年 8 月 24 日，上午 8 点 PDT / 下午 3 点 UST 在线 • 免费<h3 id="观看"><a href="#观看" class="" aria-label="Link to this section"></a>观看</h3>会议现在已经结束，但你仍然可以观看录像！<a href="//egghead.io/playlists/mdx-conf-3fc2">观看演讲 →</a><h3 id="关于"><a href="#关于" class="" aria-label="Link to this section"></a>关于</h3>加入我们的首届 MDX 会议！我们将免费直接为你直播。自两年半前的<a href="//github.com/mdx-js/mdx/commit/dee47dc20b08d534132e3b966cdccf3b88c7bca5">第一次提交</a>以来，MDX 发展迅速。我们想庆祝迄今为止的成就，并讨论未来的方向。我们有很多计划。了解 MDX 如何提高开发者生产力，改善教育内容创作，甚至窥探幕后看看 MDX 是如何工作的。<h3 id="演讲者"><a href="#演讲者" class="" aria-label="Link to this section"></a>演讲者</h3><h4 id="chris-biscardi"><a href="#chris-biscardi" class="" aria-label="Link to this section"></a>Chris Biscardi</h4><img alt="" src="//github.com/ChristopherBiscardi.png?size=200">]主题演讲：MDX 的过去、现在和未来<h4 id="monica-powell"><a href="#monica-powell" class="" aria-label="Link to this section"></a>Monica Powell</h4><img alt="" src="//github.com/M0nica.png?size=200">迁移到 MDX<h4 id="laurie-barth"><a href="#laurie-barth" class="" aria-label="Link to this section"></a>Laurie Barth</h4><img alt="" src="//github.com/laurieontech.png?size=200">MDX v2 语法<h4 id="cole-bemis"><a href="#cole-bemis" class="" aria-label="Link to this section"></a>Cole Bemis</h4><img alt="" src="//github.com/colebemis.png?size=200">揭秘 MDX<h4 id="prince-wilson"><a href="#prince-wilson" class="" aria-label="Link to this section"></a>Prince Wilson</h4><img alt="" src="//github.com/maxcell.png?size=200">个人站点游乐场<h4 id="kathleen-mcmahon"><a href="#kathleen-mcmahon" class="" aria-label="Link to this section"></a>Kathleen McMahon</h4><img alt="" src="//github.com/resource11.png?size=200">用 MDX 魔法打造数字花园<h4 id="rodrigo-pombo"><a href="#rodrigo-pombo" class="" aria-label="Link to this section"></a>Rodrigo Pombo</h4><img alt="" src="//github.com/pomber.png?size=200">MDX 中的 X<h4 id="jonathan-bakebwa"><a href="#jonathan-bakebwa" class="" aria-label="Link to this section"></a>Jonathan Bakebwa</h4><img alt="" src="//github.com/codebender828.png?size=200">MDX 与 Vue/Nuxt<h3 id="注册"><a href="#注册" class="" aria-label="Link to this section"></a>注册</h3><div>注意：注册已关闭。</div><h3 id="常见问题"><a href="#常见问题" class="" aria-label="Link to this section"></a>常见问题</h3><h4 id="如果我-8-月-24-日不能参加怎么办"><a href="#如果我-8-月-24-日不能参加怎么办" class="" aria-label="Link to this section"></a>如果我 8 月 24 日不能参加怎么办？</h4>我们会想你的，但你不会错过！所有演讲都将被录制并在会议当天发布。你可以在方便的时候观看或重看。<h4 id="演讲会有文字记录吗"><a href="#演讲会有文字记录吗" class="" aria-label="Link to this section"></a>演讲会有文字记录吗？</h4>会的。<h4 id="有行为准则吗"><a href="#有行为准则吗" class="" aria-label="Link to this section"></a>有行为准则吗？</h4>当然有。我们致力于为每个人提供无骚扰的体验。我们不会容忍任何形式的参与者骚扰。我们采用了 <a href="//github.com/partycorgi/partycorgi/blob/corgi/CODE_OF_CONDUCT.md">Party Corgi Network 的行为准则</a>。我们将有主持人确保行为准则得到遵守。<h4 id="还有其他问题吗"><a href="#还有其他问题吗" class="" aria-label="Link to this section"></a>还有其他问题吗？</h4>请联系我们。</div>ShortcodesJohn Otanderhttps://mdx.ndjp.net/blog/shortcodes/https://mdx.ndjp.net/blog/shortcodes/Tue, 14 May 2019 00:00:00 GMT2019-05-14T00:00:00.000Z2021-11-01T00:00:00.000Z<div><div>注意：这是一篇旧的博客文章。其中描述的功能目前记录在 <a href="/docs/using-mdx/#mdx-provider">§ MDX provider</a>。以下内容为历史目的而保留原样。</div><h2 id="shortcodes"><a href="#shortcodes" class="" aria-label="Link to this section"></a>Shortcodes</h2>MDX v1 中一个令人兴奋的新功能是全局 shortcodes。它允许你将组件暴露给你的应用或网站中的所有文档。这对于常用组件（如 YouTube 嵌入、Twitter 卡片或在文档中频繁使用的其他任何内容）是一个很有用的功能。如果你有一个 MDX 文档的应用程序包装器，你可以使用 <code>MDXProvider</code> 添加组件：<div><div>src/App.js</div><pre><code class="">import React from 'react' import {MDXProvider} from '@mdx-js/react' import {TomatoBox, Twitter, YouTube} from './ui' const shortcodes = {TomatoBox, Twitter, YouTube} export default ({children}) => ( <MDXProvider components={shortcodes}>{children}</MDXProvider> ) </code></pre></div>然后，任何被 <code>App</code> 包裹的 MDX 文档都可以访问 <code>YouTube</code>、 <code>Twitter</code> 和 <code>TomatoBox</code>。 Shortcodes 只不过是组件，所以你可以在 MDX 文档的任何地方用 JSX 引用它们。<div><div>example.mdx</div><pre><code class="language-mdx"># Hello world! Here's a YouTube shortcode: <YouTube tweetId="1234" /> Here's a YouTube shortcode wrapped in TomatoBox: <TomatoBox> <YouTube videoId="1234" /> </TomatoBox> </code></pre></div>就是这样。 🎉 🚀非常感谢 <a href="//christopherbiscardi.com">Chris Biscardi</a> 构建了这个功能的大部分。</div>MDX 正式发布John Otanderhttps://mdx.ndjp.net/blog/v1/https://mdx.ndjp.net/blog/v1/Thu, 11 Apr 2019 00:00:00 GMT2019-04-11T00:00:00.000Z2025-01-27T00:00:00.000Z<div><div>注意：这是一篇旧的博客文章。 <a href="//rauchg.com/2020/vercel">ZEIT 现在是 Vercel</a>。不再需要 "<code>@mdx</code> pragma"。以下内容为历史目的而保留原样。</div><h2 id="mdx-正式发布"><a href="#mdx-正式发布" class="" aria-label="Link to this section"></a>MDX 正式发布</h2>距离第一次 MDX 提交已经一年半了，距离 MDX 在 ZEIT Day 上首次公布也一年了。 MDX 是对如何使用组件编写沉浸式内容的一次激进范式转变。它是一种开放的、<a href="//johno.com/authorable-format">可创作的格式</a>，让写作再次变得有趣。自从公布 MDX 以来，我们一直在进行大量的 bug 修复、新功能开发、更好的解析和集成测试。现在，我们认为它已经准备好了。 我们很高兴终于发布 v1！<h3 id="-有什么新内容"><a href="#-有什么新内容" class="" aria-label="Link to this section"></a>🎉 有什么新内容？</h3>以下是我们所做工作的简要概述：<h4 id="解析"><a href="#解析" class="" aria-label="Link to this section"></a>解析</h4>MDX 文档解析有了显著改进。我们不会在这里深入细节，但我们看到了 MDX 在实际项目中的使用方式，将遇到的边缘情况整合到测试套件中，现在更直观地处理 JSX、 import 和 export。如果你发现我们没有覆盖的情况，请提交 issue！😸<h4 id="remark-mdx"><a href="#remark-mdx" class="" aria-label="Link to this section"></a>remark-mdx</h4><code>remark-mdx</code> 是 remark 中 MDX 的语法扩展。它作为 <a href="//github.com/remarkjs/remark">remark</a> 插件提供 MDX 的解析功能。这听起来有点元。它的意思是，以前语法解析部分在库内部（无法从外部使用），现在它被外部化了（可以从外部使用）。如果你想检查或转换 MDX 文档，这很有用。例如，它允许 prettier 等工具使用与 MDX 核心完全相同的解析器。或者你可以将 <code>remark-mdx</code> 与 <a href="//github.com/remarkjs/remark-lint">remark-lint</a> 结合使用来检查你的 MDX。<h4 id="自定义-pragma"><a href="#自定义-pragma" class="" aria-label="Link to this section"></a>自定义 pragma</h4>在 v1 中，我们不再使用 <code>MDXTag</code>，而是使用包裹 <code>React.createElement</code> 的自定义 pragma。我们决定更新这种方法，使 JSX 输出更易读、更轻量、更可定制。 这意味着 MDX 可以与任何 React、Vue、Preact 或任何其他支持 JSX 的库一起使用。特别感谢 <a href="//github.com/christopherbiscardi">@christopherbiscardi</a> 实现了这个功能。<a href="../custom-pragma/">阅读博客文章</a><h4 id="-文档"><a href="#-文档" class="" aria-label="Link to this section"></a>📚 文档</h4>好的库需要好的文档，所以我们一直在添加内容并改进整体文档网站体验。<ul><li>搜索（感谢 Algolia）</li><li><a href="/guides/">指南</a></li><li><a href="//zeit.co">通过 ZEIT 自动部署</a></li><li><a href="//gatsbyjs.org">自定义 Gatsby 主题</a></li><li>文档重组以提高直觉性</li><li>全面重写页面以提高清晰度</li></ul>特别感谢 <a href="//github.com/jxnblks">@jxnblk</a> 和 <a href="//github.com/wooorm">@wooorm</a> 帮助改进文档和更新构建工具。<h3 id="破坏性变更"><a href="#破坏性变更" class="" aria-label="Link to this section"></a>破坏性变更</h3>为了进行一些改进，我们不得不引入一些破坏性变更。 这些是实际生产测试和反馈的结果。社区在发展，在过去一年中我们想出了更新、更好的主意。我们确保影响很小，并编写了完整的迁移指南。<ul><li>🚨<code>@mdx-js/tag</code> 被 <code>@mdx-js/react</code> 和 <code>@mdx</code> pragma 取代 — <a href="/migrating/v1#pragma">迁移指南</a></li><li>MDXProvider 现在在嵌套时合并组件上下文 — <a href="/migrating/v1#mdxprovider">迁移指南</a></li><li>React 支持现在要求 <code>@mdx-js/react</code> 中 <code>>= 16.8</code> — <a href="/migrating/v1#react">迁移指南</a></li></ul><a href="/migrating/v1">阅读完整的 v1 迁移指南</a><h4 id="废弃"><a href="#废弃" class="" aria-label="Link to this section"></a>废弃</h4>我们只需要引入一个废弃。 <code>mdPlugins</code> 和 <code>hastPlugins</code> 选项分别被重命名为 <code>remarkPlugins</code> 和 <code>rehypePlugins</code>。目前，当使用旧选项时会发出警告。在 v2 中，旧选项将被移除。<h3 id="-增长"><a href="#-增长" class="" aria-label="Link to this section"></a>📈 增长</h3>每次主要发布都是退后一步反思增长和更大社区发展的好时机。围绕 MDX 的生态系统已经增长到超出我们梦想的规模。我们还看到了我们从未想象过的项目/产品/应用。<h4 id="数据"><a href="#数据" class="" aria-label="Link to this section"></a>数据</h4><ul><li>下载量：每周 125,000 次，总计 240 万次</li><li>Stars：6,200</li><li>贡献者：50</li><li>Pull requests：281</li><li>提交：670</li></ul>贡献者的增长是这里最重要的方面之一，因为我们有众多熟悉 MDX 内部原理的社区成员。这使我们能够持续改进项目，并在不断增长的贡献者团队中分担工作。<a href="//github.com/mdx-js/mdx/graphs/contributors?from=2017-12-17&to=2019-04-11&type=c">查看贡献者图表</a><h4 id="生态系统"><a href="#生态系统" class="" aria-label="Link to this section"></a>生态系统</h4><ul><li><a href="//prettier.io">Prettier</a></li><li><a href="//github.com/pedronauck/docz">Docz</a></li><li><a href="//github.com/jxnblk/mdx-deck">MDX Deck</a></li><li><a href="//nextjs.org">Next.js</a></li><li><a href="//gatsbyjs.org">Gatsby</a></li><li><a href="//astexplorer.net">AST Explorer</a></li><li><a href="/docs/getting-started/#vue">Vue 支持（alpha）</a></li><li><a href="//frontarm.com/demoboard/">Demoboard</a></li><li><a href="/docs/getting-started/#%E7%BC%96%E8%BE%91%E5%99%A8">编辑器</a></li></ul><h3 id="-路线图"><a href="#-路线图" class="" aria-label="Link to this section"></a>🛣 路线图</h3>v1 发布后，我们制定了一个路线图，除了 bug 修复和可能遇到的解析问题外，我们将在接下来的 6 个月左右继续努力。<ul><li>MDXs：<a href="//github.com/mdx-js/mdx/issues/454">#454</a></li><li>交错：<a href="//github.com/mdx-js/mdx/issues/195">#195</a></li><li>全局 shortcodes：<a href="//github.com/mdx-js/mdx/pull/508">#508</a></li><li>稳定的 Vue 支持：<a href="//github.com/mdx-js/mdx/issues/238">#238</a></li><li>Blocks：MDX WYSIWYG：<a href="//github.com/blocks/blocks">blocks/blocks</a></li><li>受 AST Explorer 启发的 MDX playground：<a href="//github.com/mdx-js/mdx/issues/220">#220</a></li><li>新的启动页面：<a href="//github.com/mdx-js/mdx/issues/444">#444</a></li><li>展示页面：<a href="//github.com/mdx-js/mdx/issues/414">#414</a></li></ul><h4 id="vue-支持"><a href="#vue-支持" class="" aria-label="Link to this section"></a>Vue 支持</h4>支持 Vue 是 MDX 的一个重要目标，也是我们重新架构 MDX 以使用自定义 pragma 的主要原因之一。我们很高兴我们现在有一个可用的 Vue alpha 版本。我们希望 Vue 社区的任何人都能尝试一下并提供反馈。<a href="//github.com/mdx-js/mdx/tree/36cb41b/examples/vue">查看 Vue 示例</a><h4 id="blocks-项目"><a href="#blocks-项目" class="" aria-label="Link to this section"></a>Blocks 项目</h4>编写 MDX 文档的一个关键缺失方面是编辑体验。目前，除非你喜欢在文本编辑器中编写原始 Markdown/代码，否则没有一种易于上手的方式来编写 MDX。我们想解决这个问题，并已经开始开发一个 MDX "blocks 编辑器"，它是一个以内容为中心的 WYSIWYG。不仅如此，我们将尽一切努力确保编辑器从一开始就尽可能地无障碍。当我们准备好 beta 版本时，我们会将其开源并公布，敬请期待。<a href="//github.com/blocks/blocks">查看 Blocks 项目</a><h3 id="unified-集体"><a href="#unified-集体" class="" aria-label="Link to this section"></a>unified 集体</h3>MDX 是 unified 集体的一部分，这是一个处理多种内容来源的开源生态系统。 unified 项目在整个网络中被使用，如果没有我们优秀的赞助商的财务支持，这一切都不可能实现。<ul><li><a href="//zeit.co">ZEIT</a> 🥇</li><li><a href="//gatsbyjs.org">Gatsby</a> 🥇</li><li><a href="//www.holloway.com">Holloway</a> 🥉</li><li><a href="//opencollective.com/unified#budget">支持者</a> 🏆</li><li><a href="//opencollective.com/unified">你？</a>👤</li></ul><h3 id="-致谢"><a href="#-致谢" class="" aria-label="Link to this section"></a>🙏 致谢</h3>我们要感谢所有的贡献者和开心的用户。特别感谢 <a href="//github.com/wooorm">@wooorm</a>, <a href="//github.com/silvenon">@silvenon</a>, <a href="//github.com/timneutkens">@timneutkens</a>, <a href="//github.com/christopherbiscardi">@ChristopherBiscardi</a>, <a href="//github.com/jxnblk">@jxnblk</a>, <a href="//github.com/alexandernanberg">@alexandernanberg</a>, <a href="//github.com/jescalan">@jescalan</a>, <a href="//github.com/Jarred-Sumner">@Jarred-Sumner</a>, <a href="//github.com/leimonio">@leimonio</a>, <a href="//github.com/ticky">@ticky</a>, <a href="//github.com/jamesknelson">@jamesknelson</a>, <a href="//github.com/pshrmn">@pshrmn</a>, <a href="//github.com/rauchg">@rauchg</a>, <a href="//github.com/joelhooks">@joelhooks</a>, <a href="//github.com/jlengstorf">@jlengstorf</a>, <a href="//github.com/johnlindquist">@johnlindquist</a>, <a href="//github.com/kyleamathews">@kyleamathews</a>, <a href="//github.com/kentcdodds">@kentcdodds</a>, <a href="//github.com/wesbos">@wesbos</a>, <a href="//github.com/rosew">@rosew</a>, <a href="//github.com/pedronauck">@pedronauck</a>, <a href="//github.com/tayiorbeii">@tayiorbeii</a>, <a href="//github.com/nickbender">@nickbender</a>, <a href="//github.com/ntaylor89">@ntaylor89</a>, <a href="//github.com/mxstbr">@mxstbr</a>, <a href="//github.com/manovotny">@manovotny</a>, <a href="//github.com/xyc">@xyc</a>, <a href="//github.com/filoxo">@filoxo</a>, <a href="//github.com/millette">@millette</a>, <a href="//github.com/hugmanrique">@hugmanrique</a>, <a href="//github.com/johnsherrard">@johnsherrard</a>, <a href="//github.com/sw-yx">@sw-yx</a>, 以及任何我们可能遗漏的人。</div>自定义 pragmaChris Biscardihttps://mdx.ndjp.net/blog/custom-pragma/https://mdx.ndjp.net/blog/custom-pragma/Mon, 11 Mar 2019 00:00:00 GMT2019-03-11T00:00:00.000Z2021-11-01T00:00:00.000Z<div><div>注意：这是一篇旧的博客文章。其中描述的步骤不再由 MDX 执行。它现在首先使用 JavaScript AST，而不是生成 JSX 字符串。也不再需要在客户端使用将 MDX 与特定框架结合的额外胶水代码。更多信息请参见 <a href="/docs/using-mdx/#mdx-%E7%9A%84%E5%B7%A5%E4%BD%9C%E5%8E%9F%E7%90%86">§ MDX 的工作原理</a> 和 <a href="/packages/mdx/#architecture">¶ 架构</a>。以下内容为历史目的而保留原样。</div><h2 id="自定义-pragma"><a href="#自定义-pragma" class="" aria-label="Link to this section"></a>自定义 pragma</h2><code>MDXTag</code> 是 MDX 用自定义 React 组件替换 <code><pre></code> 和 <code><h1></code> 等 HTML 原语的关键部分，对于那些不了解的人来说。 <a href="//www.christopherbiscardi.com/post/codeblocks-mdx-and-mdx-utils">我之前写过</a> 关于尝试用自定义代码组件替换 <code><pre></code> 标签时 <code>MDXTag</code> 的工作方式。 <a href="//github.com/ChristopherBiscardi/gatsby-mdx/blob/00769a1b72455f40843cd2f09ee34fd63b009fb2/packages/mdx-utils/index.js">mdx-utils</a> 包含了在 <code>pre</code> 和 <code>code</code> 之间的 <code>MDXTag</code> 元素中适当传递 props 的方法论。<div><div>TypeScript</div><pre><code class="">exports.preToCodeBlock = preProps => { if ( // children is MDXTag preProps.children && // MDXTag props preProps.children.props && // if MDXTag is going to render a <code> preProps.children.props.name === 'code' ) { // we have a <pre><code> situation const { children: codeString, props: {className, ...props} } = preProps.children.props return { codeString: codeString.trim(), language: className && className.split('-')[1], ...props } } return undefined } </code></pre></div>所以 <code>MDXTag</code> 是所有其他 MDX 渲染元素中间的一个真实组件。此处包含所有代码以供参考。<div><div>TypeScript</div><pre><code class="">import React, {Component} from 'react' import {withMDXComponents} from './mdx-provider' const defaults = { inlineCode: 'code', wrapper: 'div' } class MDXTag extends Component { render() { const { name, parentName, props: childProps = {}, children, components = {}, Layout, layoutProps } = this.props const Component = components[`${parentName}.${name}`] || components[name] || defaults[name] || name if (Layout) { return ( <Layout components={components} {...layoutProps}> <Component {...childProps}>{children}</Component> </Layout> ) } return <Component {...childProps}>{children}</Component> } } export default withMDXComponents(MDXTag) </code></pre></div><code>MDXTag</code> 用于 hast 到 estree 的转换，这是 MDX AST 管道的最后一步。每个可渲染元素都被包裹在 <code>MDXTag</code> 中，<code>MDXTag</code> 负责稍后渲染元素。<div><div>TypeScript</div><pre><code class="">return `<MDXTag name="${node.tagName}" components={components}${ parentNode.tagName ? ` parentName="${parentNode.tagName}"` : '' }${props ? ` props={${props}}` : ''}>${children}</MDXTag>` </code></pre></div><h3 id="具体示例"><a href="#具体示例" class="" aria-label="Link to this section"></a>具体示例</h3>以下 MDX<div><div>MDX</div><pre><code class="language-mdx"># a title and such testing </code></pre></div>转换为以下 React 代码<div><div>TypeScript</div><pre><code class="">export default ({components, ...props}) => ( <MDXTag name="wrapper" components={components}> <MDXTag name="h1" components={components}>{`a title`}</MDXTag>{' '} <MDXTag name="pre" components={components}> <MDXTag name="code" components={components} parentName="pre" props={{metaString: null}} >{`and such `}</MDXTag> </MDXTag>{' '} <MDXTag name="p" components={components}>{`testing`}</MDXTag> </MDXTag> ) </code></pre></div>生成以下 HTML<div><div>HTML</div><pre><code class="language-html"><div> <h1>a title</h1> <pre> <code>and such</code> </pre> <p>testing</p> </div> </code></pre></div><h3 id="createelement"><a href="#createelement" class="" aria-label="Link to this section"></a>createElement</h3>使用新方法，上述 MDX 转换为这个新的 React 代码<div><div>TypeScript</div><pre><code class="">const layoutProps = {} export default function MDXContent({components, ...props}) { return ( <MDXLayout {...layoutProps} {...props} components={components} mdxType="MDXLayout" > <h1>{`a title`}</h1> <pre> <code parentName="pre" {...{}}>{`and such `}</code> </pre> <p>{`testing`}</p> </MDXLayout> ) } MDXContent.isMDXComponent = true </code></pre></div>注意现在 React 元素可以直接阅读，不再包裹 <code>MDXTag</code>。现在我们清理了中间表示，需要确保具有与旧 <code>MDXTag</code> 相同的功能。这是通过自定义 <code>createElement</code> 实现来完成的。通常使用 React 时，我们使用 <code>React.createElement</code> 来渲染屏幕上的元素。即使你使用 JSX 也是如此，因为像 <code><div></code> 这样的 JSX 标签会编译为 <code>createElement</code> 调用。所以这次我们不再使用 <code>React.createElement</code>，而是使用我们自己的。这里重现了我们的 <code>createElement</code> 函数以及我们如何决定 MDX 是否应该接管 <code>createElement</code> 调用的渲染逻辑。<div><div>TypeScript</div><pre><code class="">export default function (type, props) { const args = arguments const mdxType = props && props.mdxType if (typeof type === 'string' || mdxType) { const argsLength = args.length const createElementArgArray = new Array(argsLength) createElementArgArray[0] = MDXCreateElement const newProps = {} for (let key in props) { if (hasOwnProperty.call(props, key)) { newProps[key] = props[key] } } newProps.originalType = type newProps[TYPE_PROP_NAME] = typeof type === 'string' ? type : mdxType createElementArgArray[1] = newProps for (let i = 2; i < argsLength; i++) { createElementArgArray[i] = args[i] } return React.createElement.apply(null, createElementArgArray) } return React.createElement.apply(null, args) } </code></pre></div><h3 id="vue"><a href="#vue" class="" aria-label="Link to this section"></a>Vue</h3>使用自定义 <code>createElement</code> 的新输出格式的一个很酷的应用是，我们现在可以为 Vue 和其他框架编写它的版本。由于 pragma 插入是 webpack（或其他打包器）加载器的责任，只要我们有一个 Vue <code>createElement</code> 可以指向，在 mdx-loader 中切换 pragma 可以作为一个选项。</div>