MDX Deck 快速上手指南:基于 Markdown 与 React 构建演示文稿
MDX Deck 快速上手指南:基于 Markdown 与 React 构建演示文稿
MDX Deck 是一个基于 React 与 MDX][] 的演示文稿(Presentation Deck)构建工具,核心思路是"用 Markdown 写内容、用 React 组件做交互、用零配置 CLI 跑起来"。本文以 [packages/mdx-deck/README.md 为主线,完整讲解从安装、分页编写、主题定制、内置组件、自定义布局到演讲者模式与 CLI 参数的实战流程,并结合仓库源码说明其底层实现,读完即可上手打造自己的幻灯片。
快速开始(Getting Started)
MDX 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 color="tomato">Hello</Box>
导出主题与更多
除了组件导入,MDX Deck 还允许在 MDX 文件中通过 export 导出 theme(见下文 Theming 一节)。仓库自带的演示文件 packages/mdx-deck/hello.mdx 以及 examples/basic/deck.mdx 都是可以直接运行的分页示例,适合作为最小可运行模板参考。
主题定制(Theming)
MDX 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 与 prism:
import { themes } from 'mdx-deck'
export const theme = {
...themes.prism
}
由于 MDX 本身支持内联 React 组件,也可以直接在幻灯片中引入高亮组件:
import Highlighter from 'react-syntax-highlighter'
<Highlighter language='javascript'>
{`export const hello = 'hi'`}
</Highlighter>
样式化 Markdown 元素
通过 theme.styles 对象可以针对具体 Markdown 元素(如标题、引用)统一样式:
// 示例主题
export default {
styles: {
h1: {
textTransform: 'uppercase',
letterSpacing: '0.1em',
},
blockquote: {
fontStyle: 'italic',
},
}
}
主题字段参考(Reference)
colors:MDX 组件使用的颜色对象text:根前景色background:根背景色primary:主色
fonts.body:基础字体族fonts.heading:标题字体族fonts.monospace:<pre>与<code>的字体族text.heading:所有标题的统一样式styles:作用于 MDX 元素的 Theme UI 样式styles.Slide:包裹内容的 Slide 组件样式styles.Header:Header 组件样式styles.Footer:Footer 组件样式components:MDX 组件映射对象googleFont:用于加载 Google 字体的样式表 URL
各内置主题的具体实现可参考 packages/themes/ 目录下的 base.js、dark.js、future.js 等文件(base.js 为空对象,仅作向后兼容保留)。
内置组件(Components)
MDX Deck 内置了一系列辅助演示文稿制作的组件,这些组件通过 MDX 的 shortcodes 机制提供,无需显式 import 即可使用。完整说明见 docs/components.md。
Head:设置文档头部
用 Head 组件写入 <head> 中的内容,例如配置 Twitter Card 分享信息:
<Head>
<title>My Presentation</title>
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@jxnblk" />
<meta name="twitter:title" content="My Presentation" />
<meta name="twitter:description" content="A really great presentation" />
<meta name="twitter:image" content="https://example.com/card.png" />
</Head>
Notes:演讲者备注
Notes 组件添加的备注只在演讲者模式(presenter mode)下显示,对观众不可见。内容支持 Markdown 语法,但需要在内容前后保留空行:
# Slide Content
<Notes>
- Only visible in presenter mode
- Markdown syntax can be used with empty lines around the content
</Notes>
Header / Footer:全篇页眉页脚
Header 与 Footer 组件分别在整个演示文稿的顶部 / 底部渲染跨页持久显示的内容,适合放 Logo、账号标识等:
<Header>
Put a logo, handle, or something else here...
</Header>
# My Presentation
Steps:单页内分步呈现
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
</Invert>
- Split:水平布局,第一个子元素靠左,其余子元素靠右:
import { Split } from 'mdx-deck'
<Split>

## Meow
</Split>
- SplitRight:与
Split相同,但第一个子元素渲染在右侧。 - Horizontal:类似 Split 系列,但将所有子元素并排渲染。
- FullScreenCode:将代码块全屏渲染:
import { FullScreenCode } from 'mdx-deck'
<FullScreenCode>
```jsx
<Button>Beep</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 Mode) |
| Option + G | 切换网格模式(Grid Mode) |
CLI 选项(CLI Options)
mdx-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/(内置主题)三个包中,配合本文即可从"会用"走向"知其所以然"。
