MDX Deck 快速上手指南：基于 Markdown 与 React 构建演示文稿

MDX Deck 快速上手指南基于 Markdown 与 React 构建演示文稿【免费下载链接】mdx-deck♠️ React MDX-based presentation decks项目地址: https://gitcode.com/gh_mirrors/md/mdx-deckMDX Deck 是一个基于 React 与 MDX 的演示文稿Presentation Deck构建工具核心思路是用 Markdown 写内容、用 React 组件做交互、用零配置 CLI 跑起来。本文以 packages/mdx-deck/README.md 为主线完整讲解从安装、分页编写、主题定制、内置组件、自定义布局到演讲者模式与 CLI 参数的实战流程并结合仓库源码说明其底层实现读完即可上手打造自己的幻灯片。快速开始Getting StartedMDX Deck 通过npm以开发依赖方式安装npm i -D mdx-deck安装后创建一个.mdx文件例如deck.mdx并使用---三个连字符组成的水平线将每一页幻灯片分隔开# Hello --- ## This is my deck --- ## The End接着在package.json中添加一条运行脚本使用 MDX Deck 的 CLI 指向该.mdx文件即可启动开发服务器scripts: { start: mdx-deck deck.mdx }启动开发服务器npm start启动后使用键盘的左右方向键即可在幻灯片之间前后导航。从package.json的bin字段见 packages/mdx-deck/package.json可以看到mdx-deck命令实际映射到./cli.js而cli.js内部通过execa调用 Gatsby 的develop命令并透传--host、--port与--open参数详见 packages/mdx-deck/cli.js也就是说开发服务器本质上是基于 Gatsby 的。使用 MDX在幻灯片中内联 React 组件MDX 同时支持 Markdown 语法并允许在文档中直接以 JSX 形式渲染 React 组件。导入组件Imports导入组件使用标准的 ES import 语法但必须在 import 语句与任何 markdown / JSX 内容之间留出空行否则会被当作普通文本解析import { Box } from theme-ui Box colortomatoHello/Box导出主题与更多除了组件导入MDX Deck 还允许在 MDX 文件中通过export导出theme见下文 Theming 一节。仓库自带的演示文件 packages/mdx-deck/hello.mdx 以及 examples/basic/deck.mdx 都是可以直接运行的分页示例适合作为最小可运行模板参考。主题定制ThemingMDX Deck 的样式体系建立在 Theme UI 与 Emotion 之上因此幻灯片中几乎任何一部分都可以通过主题定制。仓库还内置了多套主题用于快速改变演示文稿的外观。内置主题的完整列表与效果图见 docs/themes.md详细定制方法见 docs/theming.md。启用内置主题在 MDX 文件中通过export const theme ...即可启用主题import { themes } from mdx-deck export const theme themes.dark # Dark Theme仓库内置主题包括dark、future、condensed、yellow、swiss、poppins、book、script、comic、notes、code、lobster以及用于语法高亮的highlight与prism导出定义见 packages/themes/index.js。也可以按需单独引入import { big } from mdx-deck/themes自定义主题自定义主题同样是导出theme对象主题基于 Theme UI可定制字体、颜色、布局与各类元素样式import myTheme from ./theme export const theme myTheme # Hello// 示例 theme.js export default { fonts: { body: Roboto, sans-serif, monospace: Roboto Mono, monospace, }, colors: { text: white, background: black, primary: blue, }, }组合主题需要组合多套主题时将多个主题对象合并merge成一个对象再导出即可。Google Fonts主题对象中可以指定googleFont字段MDX Deck 会自动在文档head中添加对应的link标签也可以改用Head /组件手动添加自定义link标签。语法高亮默认情况下围栏代码块fenced code block不包含任何语法高亮。主题可以通过提供一组自定义的 MDX 组件包括替换默认code组件的实现来接入语法高亮例如配合react-syntax-highlighter。MDX Deck 为此内置了两套高亮主题highlight与prismimport { themes } from mdx-deck export const theme { ...themes.prism }由于 MDX 本身支持内联 React 组件也可以直接在幻灯片中引入高亮组件import Highlighter from react-syntax-highlighter Highlighter languagejavascript {export const hello hi} /Highlighter样式化 Markdown 元素通过theme.styles对象可以针对具体 Markdown 元素如标题、引用统一样式// 示例主题 export default { styles: { h1: { textTransform: uppercase, letterSpacing: 0.1em, }, blockquote: { fontStyle: italic, }, } }主题字段参考ReferencecolorsMDX 组件使用的颜色对象text根前景色background根背景色primary主色fonts.body基础字体族fonts.heading标题字体族fonts.monospacepre与code的字体族text.heading所有标题的统一样式styles作用于 MDX 元素的 Theme UI 样式styles.Slide包裹内容的 Slide 组件样式styles.HeaderHeader 组件样式styles.FooterFooter 组件样式componentsMDX 组件映射对象googleFont用于加载 Google 字体的样式表 URL各内置主题的具体实现可参考 packages/themes/ 目录下的base.js、dark.js、future.js等文件base.js为空对象仅作向后兼容保留。内置组件ComponentsMDX Deck 内置了一系列辅助演示文稿制作的组件这些组件通过 MDX 的shortcodes机制提供无需显式 import即可使用。完整说明见 docs/components.md。Head设置文档头部用Head组件写入head中的内容例如配置 Twitter Card 分享信息Head titleMy Presentation/title meta nametwitter:card contentsummary_large_image / meta nametwitter:site contentjxnblk / meta nametwitter:title contentMy Presentation / meta nametwitter:description contentA really great presentation / meta nametwitter:image contenthttps://example.com/card.png / /HeadNotes演讲者备注Notes组件添加的备注只在演讲者模式presenter mode下显示对观众不可见。内容支持 Markdown 语法但需要在内容前后保留空行# Slide Content Notes - Only visible in presenter mode - Markdown syntax can be used with empty lines around the content /NotesHeader / Footer全篇页眉页脚Header与Footer组件分别在整个演示文稿的顶部 / 底部渲染跨页持久显示的内容适合放 Logo、账号标识等Header Put a logo, handle, or something else here... /Header # My PresentationSteps单页内分步呈现Steps旧称Appear组件让单个幻灯片内的子元素逐一出现配合左右方向键逐步切换Steps - One - Two - Three - Four /Steps从源码结构看Steps内部使用useSteps这个 hook实现位于 packages/gatsby-plugin/src/use-steps.js因此你也可以基于useSteps构建行为类似的自定义组件。第三方组件以下可选库专为 MDX Deck 设计可按需配合使用CodeSurfer用于代码的滚动、缩放与高亮展示的 React 组件。mdx-code面向 MDX Deck 的可运行代码沙箱playground。mdx-deck-live-code在幻灯片中进行 React / JS 实时编码。注意使用这些第三方库时请先确认与当前 MDX Deck 版本的兼容性。布局Layouts每一页幻灯片都可以包裹一个自定义布局组件作为该页的模板用于在视觉上区分不同类型的幻灯片。示例见 examples/layouts/deck.mdx。自定义布局// 示例 Layout.js import React from react export default ({ children }) ( div style{{ width: 100vw, height: 100vh, backgroundColor: tomato, }} {children} /div )import Layout from ./Layout # No Layout --- Layout # Custom Layout /Layout布局组件会包裹该页幻灯片内的所有 MDX 元素因此你可以在布局内使用嵌套的 ThemeProvider或用 CSS-in-JS 定向样式化子元素。注意布局组件内子内容前后必须保留换行否则内容会被当作原始文本而非 Markdown 解析。内置布局Invert反转主题的前景色与背景色import { Invert } from mdx-deck # Normal --- Invert # Inverted /InvertSplit水平布局第一个子元素靠左其余子元素靠右import { Split } from mdx-deck Split  ## Meow /SplitSplitRight与Split相同但第一个子元素渲染在右侧。Horizontal类似 Split 系列但将所有子元素并排渲染。FullScreenCode将代码块全屏渲染import { FullScreenCode } from mdx-deck FullScreenCode jsx ButtonBeep/Button /FullScreenCode上述内置布局的底层实现可以在 packages/gatsby-theme/src/components/ 目录中对应找到如invert.js、split.js、split-right.js、horizontal.js、full-screen-code.js。演讲者模式Presenter Mode按下Option P即可切换演讲者模式该模式会显示下一页幻灯片的预览、计时器以及演讲者备注演讲者模式的关键特性是演示文稿可以在两个独立窗口中同时打开且两个窗口之间保持同步——演讲者在自己窗口内翻页观众窗口随之切换。具体操作流程参见 docs/presenting.md按Opt P进入演讲者模式点击页面底部的链接在另一个标签页打开演示文稿将该标签页移动到观众可见的屏幕或投影仪窗口在原始窗口控制翻页记得隐藏鼠标光标避免出现在观众屏幕上。键盘快捷键Keyboard Shortcuts按键说明左方向键、Page Up、Shift Space回到上一页或 Steps 中的上一步右方向键、Page Down、Space进入下一页或 Steps 中的下一步Option P切换演讲者模式Option O切换总览模式Overview ModeOption G切换网格模式Grid ModeCLI 选项CLI Optionsmdx-deck命令支持以下参数对应实现见 packages/mdx-deck/cli.js-p --port Dev server port -h --host Host the dev server listens to --no-open Prevent from opening in default browser各参数的默认值同样可以在cli.js中确认--port/-p开发服务器端口默认8000--host/-h开发服务器监听的主机名默认localhost--open/-o是否自动在默认浏览器打开默认开启可用--no-open关闭。除开发命令外CLI 还支持构建生产版本mdx-deck build deck.mdx。从cli.js的build分支可以看到构建会先执行gatsby clean清理缓存再运行gatsby build最后把 Gatsby 生成的public目录复制到当前工作目录下而开发模式则调用gatsby develop并透传上述 host / port / open 参数。该 CLI 在package.json中登记了start、build、help三个脚本分别对应./cli.js hello.mdx、./cli.js build hello.mdx与./cli.js可自行运行查看效果。仓库示例与延伸阅读仓库在 examples/ 目录下提供了多种可直接运行的示例是理解各功能的最佳入口基础示例最小的分页演示文稿语法高亮示例代码块高亮Steps 示例单页内分步呈现Head 示例文档头部定制页眉页脚示例跨页 Header / Footer主题示例 与 Provider 示例主题与全局 Provider 定制多文件示例通过deck.js聚合多个 MDX 文件Gatsby 集成示例将 MDX Deck 作为 Gatsby 站点的一部分使用。如需进一步深入可继续阅读仓库内文档组件文档、主题文档、主题定制文档、布局文档、导出文档 与 API 文档。MDX Deck 的核心功能分布在 packages/mdx-deck/CLI 与配置、packages/gatsby-plugin/Gatsby 插件实现与 packages/themes/内置主题三个包中配合本文即可从会用走向知其所以然。【免费下载链接】mdx-deck♠️ React MDX-based presentation decks项目地址: https://gitcode.com/gh_mirrors/md/mdx-deck创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考