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

原创2026-09-22 20:58:151,729 阅读
文章标签:开发工具前端

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>

![](kitten.png)

## 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:

  1. 按 Opt + P 进入演讲者模式;
  2. 点击页面底部的链接,在另一个标签页打开演示文稿;
  3. 将该标签页移动到观众可见的屏幕或投影仪窗口;
  4. 在原始窗口控制翻页;
  5. 记得隐藏鼠标光标,避免出现在观众屏幕上。

键盘快捷键(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/ 目录下提供了多种可直接运行的示例,是理解各功能的最佳入口:

如需进一步深入,可继续阅读仓库内文档:组件文档、主题文档、主题定制文档、布局文档、导出文档 与 API 文档。MDX Deck 的核心功能分布在 packages/mdx-deck/(CLI 与配置)、packages/gatsby-plugin/(Gatsby 插件实现)与 packages/themes/(内置主题)三个包中,配合本文即可从"会用"走向"知其所以然"。

登录后查看全文
mdx-deck