Docusaurus 文档站的 MDX 实战在 Markdown 中嵌入 JSX 与 React 组件基于 Vercel 仓库 fixture 的深度解析【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercelMDX 允许你在 Markdown 文件中直接书写 JSX、导出并复用 React 组件是 Docusaurus 文档站实现代码与内容同源的关键能力。本文以当前仓库packages/cli/test/dev/fixtures/23-docusaurus中的文档页面docs/mdx.md为主体逐行拆解其写法并结合 Docusaurus 配置、侧边栏注册、vercel dev集成测试与框架检测源码说明这类 MDX 页面在 Vercel 开发与部署环境中的完整运行链路。读完后你将掌握 MDX 组件导出与复用的标准写法并理解它在静态文档站构建中的底层机制。一、MDX 解决什么问题让 Markdown 具备组件能力传统 Markdown 只能表达标题、段落、列表、表格等静态内容无法渲染交互式界面。MDX 将 Markdown 与 JSX 融合Markdown 语法用于撰写正文JSX 语法用于插入 React 组件两者可以在同一文件中自由混写。本仓库的23-docusaurusfixture 就是为此而生的演示站点。它的文档目录 packages/cli/test/dev/fixtures/23-docusaurus/docs 下共有四个页面doc1.mdMarkdown 语法风格指南标题、强调、列表、链接、表格、引用、告示块等doc2.md文档间相对链接示例doc3.md正文内容示例mdx.md本篇文章的主体专门演示 MDX 能力。其中mdx.md的 frontmatter 声明了文档元信息--- id: mdx title: Powered by MDX ---id用于文档路由与侧边栏引用title决定页面标题。Docusaurus 会读取这段 frontmatter 将页面纳入文档体系。二、核心示例逐行拆解在 Markdown 中定义并复用 React 组件mdx.md正文第一句点明主题You can write JSX and use React components within your Markdown thanks to MDX.随后它完整演示了在文档中导出组件并复用的完整闭环这是 MDX 区别于普通 Markdown 的核心能力export const Highlight ({children, color}) ( span style{{ backgroundColor: color, borderRadius: 2px, color: #fff, padding: 0.2rem, }} {children} /span ); Highlight color#25c2a0Docusaurus green/Highlight and Highlight color#1877F2Facebook blue/Highlight are my favorite colors.拆解这段代码可以提炼出三个关键知识点MDX 文件本身就是模块export const Highlight ...与 ES Module 语法一致组件被导出后既可供本文件内的 JSX 使用也可以被其他文件import复用。这是文档组件化的基础——一个高亮组件可以在全站文档中反复使用。组件签名设计Highlight接收children插槽内容与color颜色参数两个 props内部渲染一个内联样式化的span。backgroundColor由调用方传入borderRadius、color、padding为固定样式调用方只需传一个颜色值即可获得统一的高亮外观。JSX 与 Markdown 混写组件标签Highlight color#25c2a0Docusaurus green/Highlight与普通 Markdown 文本and ... are my favorite colors.处于同一段落MDX 解析器会正确区分并分别渲染。文件末尾的I can write **Markdown** alongside my _JSX_!同样验证了这一点——**Markdown**与_JSX_是标准 Markdown 语法紧邻其上的却是 JSX 组件标签。实际渲染时Highlight color#25c2a0会产生一块 Teal 色Docusaurus 品牌绿背景的白色文字Highlight color#1877F2则产生 Facebook 蓝色背景的高亮块二者与正文混排直观展示Markdown 写内容、JSX 造组件的协作模式。三、MDX 页面如何进入文档站侧边栏与配置注册仅有.md文件还不够页面要出现在文档站点中需要经过侧边栏注册与构建配置两步。侧边栏注册位于 sidebars.jsmodule.exports { someSidebar: { Docusaurus: [doc1, doc2, doc3], Features: [mdx], }, };这里Features: [mdx]正是通过mdx.md中的id: mdx建立关联将 MDX 页面挂到侧边栏 Features 分组下与普通 Markdown 页面doc1/doc2/doc3平级。构建配置位于 docusaurus.config.js站点通过docusaurus/preset-classic预设启用文档功能docs.sidebarPath指向上述sidebars.jstheme.customCss指向 src/css/custom.css。这意味着 MDX 文档与普通文档共享同一套主题与样式体系不需要任何额外配置即可被 Docusaurus 编译。依赖版本可从 package.json 确认docusaurus/core与docusaurus/preset-classic均为2.0.0-alpha.48同时依赖react16.8.4与react-dom16.8.4。该 fixture 对应 Docusaurus v2 早期 alpha 版本MDX 支持已内置于核心渲染管线。四、在 Vercel 生态中的定位vercel dev 集成测试夹具23-docusaurus在仓库中并非孤立示例它作为vercel dev的集成测试 fixture 被真实执行。在 packages/cli/test/dev/integration-3.test.ts#L307-L317 中可以看到对应用例// https://linear.app/vercel/issue/ZERO-3238/unskip-tests-failing-due-to-node-16-removal test.skip( [vercel dev] 23-docusaurus, testFixtureStdio( 23-docusaurus, async (testPath: any) { await testPath(200, /, /My Site/m); }, { skipDeploy: true } ) );该用例通过testFixtureStdio启动本地 dev 服务器请求站点根路径并断言返回 HTTP 200、页面内容匹配My Site即 docusaurus.config.js 中title: My Site渲染出的站点标题。目前该用例处于test.skip状态注释指出与 Node 16 移除后的环境兼容问题相关对应 issue ZERO-3238属于测试基建层面的临时跳过不影响 fixture 本身作为 MDX 示例的有效性。五、Vercel 如何识别并构建 Docusaurus 站点框架检测源码在生产部署侧Vercel 通过框架检测器自动识别项目类型。在 packages/frameworks/src/frameworks.ts#L463-L509 中定义了Docusaurus (v2)框架条目其关键字段包括检测器detectorsmatchPackage: docusaurus/core——只要项目的package.json依赖了docusaurus/core包本例正是2.0.0-alpha.48即被识别为 Docusaurus v2 项目构建命令value: docusaurus build占位符提示亦支持npm run build开发命令value: docusaurus start --port $PORT——开发服务器需监听 Vercel 注入的$PORT环境变量这正是vercel dev场景下yarn start的等价形式输出目录value: build——构建产物目录固定为build输出目录二次探测getOutputDirName读取build目录后若其中仅有一个目录项则将该子目录作为实际部署目录返回。这意味着部分 Docusaurus 配置如自定义baseUrl或子路径部署产生的嵌套输出也能被正确识别。从源码结构看vercel dev之所以能直接服务23-docusaurus这类 fixture正是因为检测器与开发命令的配合先按docusaurus/core识别框架再以docusaurus start --port $PORT拉起开发服务器。六、本地运行与构建fixture 自带的 README.md 给出了标准操作流程可直接在packages/cli/test/dev/fixtures/23-docusaurus目录下执行安装依赖yarn等价于yarn install也支持npm install/pnpm install本地开发yarn start——启动本地开发服务器并自动打开浏览器修改文档后热更新即时生效无需手动重启构建yarn build——将站点静态化输出到build目录该目录可由任意静态托管服务承载与第五节的outputDirectory: build相互印证部署README 还提供了GIT_USERYour GitHub username USE_SSHtrue yarn deploy的 GitHub Pages 部署方式而在 Vercel 场景下则由平台按第五节的框架配置自动完成构建与发布。七、注意事项与适用边界本文示例基于 Docusaurus v2 alpha 版本fixture 锁定docusaurus/core2.0.0-alpha.48MDX 组件写法export const JSX 混排在后续 v2/v3 版本中保持兼容但具体构建配置以所用版本文档为准。组件是文件级作用域mdx.md中export的Highlight组件默认仅在该文件可见若需跨文档复用应从单独的文件导出后import引入。集成测试当前为跳过状态23-docusaurus的vercel dev测试用例因 Node 16 移除引发的环境问题被test.skip临时跳过见 integration-3.test.ts编写或验证相关能力时应注意该前提。通过本文你可以把mdx.md当作一个最小可运行的 MDX 模板复制export const组件段、以 JSX 标签调用、再在sidebars.js中登记文档id即可在 Docusaurus 文档站中复现Markdown 正文 React 组件的混合写作模式并顺畅地经由 Vercel 的框架检测与构建管线完成本地开发与线上部署。【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考