+++
title = '让文章里的示例动起来：在 Hugo 博客中使用 MDX'
date = 2026-09-12T13:43:00+08:00
lastmod = 2026-09-12T14:53:00+08:00
description = '用一个可以调节参数的阅读时间估算器，介绍 MDX 的组件导入、属性、状态、组件包裹 Markdown、正文导出变量，以及 Stark 如何预渲染正文并接入 Hugo 的静态部署流程。'
slug = 'mdx-interactive-articles'
tags = ['MDX', 'React', 'Hugo']
images = ['images/share.png']
draft = false
+++
import ReadingTime from './ReadingTime.jsx'
import Callout from './Callout.jsx'
import ReaderNote from './ReaderNote.jsx'
写技术文章时，有些关系很适合让读者自己调参数。比如文章有多少字、每分钟读多少字、估算时间怎样变化。静态表格可以列出几组结果，但读者想试另一个数字时，还是得自己算。
这篇文章本身使用 MDX 编写。下面的估算器是直接导入正文的 React 组件，可以调节速度、增加字数，再恢复初始值。后面还会出现包住 Markdown 的容器组件、由数组生成的列表，以及把内容保存在浏览器本地的组件。
## 先试一个能改变状态的示例
这里的计算规则是「字数 ÷ 每分钟阅读字数，向上取整」。初始值是 1800 字、每分钟 300 字，因此显示 6 分钟。把速度调到每分钟 600 字，结果变成 3 分钟。
这只是演示用的估算模型，没有计入代码、图表和回读的时间。它也不会改变文章顶部由 Hugo 计算的阅读时长。这里值得观察的是：正文中的一个组件可以接收参数，并根据读者操作更新自己的显示结果。
## Markdown、JSX 和表达式写在同一个文件里
[MDX](https://mdxjs.com/docs/using-mdx/) 可以把 Markdown 内容编译成组件，并支持导入组件、传递属性和使用 JavaScript 表达式。本博客选择 React 作为运行时；MDX 本身并不限定只能使用 React。
普通段落、列表、链接和代码块仍然按 Markdown 编写。需要交互的地方，再放入组件：
```mdx
import ReadingTime from './ReadingTime.jsx'
## 阅读时间估算
调节下面的参数，看看结果怎样变化。
```
`import` 指向与文章放在一起的组件文件。`initialWords` 和 `initialSpeed` 是组件的属性，也就是作者传给组件的初始参数。大括号中的 `1800` 和 `300` 是 JavaScript 数值，而不是字符串。
表达式也可以直接出现在正文里。例如下面这一行的计算结果就是由 MDX 表达式生成的：
**1800 字 ÷ 每分钟 300 字 = {1800 / 300} 分钟。**
对应的源码是：
```mdx
**1800 字 ÷ 每分钟 300 字 = {1800 / 300} 分钟。**
```
## 组件也能包住 Markdown
前面的组件是正文里的一个叶子节点。反过来也可以：把 Markdown 写在组件标签内部，作为子元素传进去。下面这个提示框就是这种用法。
这里的 **粗体**、`行内代码`、[链接](https://mdxjs.com/) 和下面的列表，都是普通的 Markdown 写法。
- 列表项由 Markdown 生成
- 组件只负责外层的标题和边框
组件本身不解析 Markdown，它只渲染传进来的 `children`：
```jsx
import './callout.css';
export default function Callout({ title, tone = 'note', children }) {
return (
);
}
```
编译器先把标签内部的 Markdown 编译成 React 元素，再交给组件。因此组件不需要知道 Markdown 的存在，作者也可以在这个结构里继续用熟悉的写法。`tone` 是另一个属性，用字符串换一种外框样式：
`tone="warn"` 改的是外框，内容仍然由 Markdown 写成。
提示、警告、折叠说明这类在文章里反复出现的结构，适合做成这样的容器组件：样式集中在一个 CSS 文件里，正文只负责写内容。
## 一组结果可以由数据生成
前面演示的是单个表达式。需要一次列出多组结果时，不必把每一行都写出来——正文可以直接导出数据，再用表达式渲染：
export const speeds = [
{ speed: 200, words: 1800 },
{ speed: 300, words: 1800 },
{ speed: 600, words: 1800 },
]
{speeds.map(({ speed, words }) => (
- {words} 字 ÷ 每分钟 {speed} 字 = {Math.ceil(words / speed)} 分钟
))}
`export const speeds = [...]` 是普通的 JavaScript 模块语法，MDX 允许在正文里直接使用。下面的 `` 用 `speeds.map(...)` 生成列表项，`key` 是 React 用来区分列表项的属性。
把数据写在正文里的好处是它离解释它的那段文字很近：改一处数字，列表就跟着变，不需要同时维护正文和表格两份内容。
表达式和列表都在构建时求值，写进 HTML 之后就不再变化。要响应点击、保存新的参数，需要组件里的状态和事件处理。
## 状态留在组件里，文章负责解释
阅读时间估算器使用 React 的 [`useState`](https://react.dev/reference/react/useState) 保存当前字数和速度。读者修改速度时，事件处理函数更新状态，React 再根据新的状态更新结果。
核心代码如下，完整示例另外包含增加字数和恢复初始值的按钮：
```jsx
import { useState } from 'react';
export default function ReadingTime({ initialWords = 1800, initialSpeed = 300 }) {
const [words] = useState(initialWords);
const [speed, setSpeed] = useState(initialSpeed);
const minutes = Math.ceil(words / speed);
return (
);
}
```
这样拆开之后，文章继续解释公式和假设，组件只处理输入、计算和显示。以后另一篇文章需要相同的估算器，可以复用组件，再通过属性换一组初始值。
组件也可以在同一篇文章中使用多次。下面给它传入 600 字，每分钟仍然是 300 字，初始结果就是 2 分钟。两份组件的状态各自独立，修改这里不会改变上面的示例。
## 正文在构建时已经生成
给静态博客加交互，一个容易混淆的问题是：正文是不是必须等浏览器运行 JavaScript 后才出现？
本博客使用的 [Stark MDX 实现](https://github.com/jimyag/stark/blob/e7cd5b0190ce6555f0f6798a674460dd4850d07d/scripts/mdx.mjs) 在构建时先渲染文章。处理顺序如下：
```text
index.mdx + ReadingTime.jsx
│
├─ MDX 编译 + React 服务端渲染 → 文章 HTML
│
└─ 浏览器打包 → React 和文章的交互脚本
│
文章 HTML + Hugo 主题布局 ────────────┤
↓
public/ 静态文件
```
因此，页面初始 HTML 已经包含正文、表格和估算器的初始结果。浏览器加载交互脚本后，调用 React 的 [`hydrateRoot`](https://react.dev/reference/react-dom/client/hydrateRoot)，让这些已有内容具备交互能力。禁用 JavaScript 时仍能读文章，也能看到初始数字，但按钮不会更新状态。
这要求组件在服务端和浏览器第一次渲染时产生一致的内容。这个示例只依赖固定的初始属性，不在渲染时读取 `window`、当前时间或随机数。确实需要访问浏览器能力的逻辑，应放在合适的事件处理或 effect 中，而不是直接写在组件的首次渲染路径上。
## 需要浏览器能力时，用 effect
上一节说首次渲染必须和服务端一致。只能由浏览器提供的能力——本地存储、窗口尺寸、`navigator`——就不该出现在首次渲染的路径上。下面这个组件把读者写的笔记存在浏览器本地：
它的做法是：初始状态给一个固定的空值，等浏览器接管之后，再在 effect 里读取本地存储。
```jsx
import { useEffect, useId, useState } from 'react';
const STORAGE_KEY = 'stark-mdx-reader-note';
export default function ReaderNote() {
const id = useId();
const [note, setNote] = useState('');
const [loaded, setLoaded] = useState(false);
useEffect(() => {
const stored = window.localStorage.getItem(STORAGE_KEY);
if (stored) setNote(stored);
setLoaded(true);
}, []);
useEffect(() => {
if (loaded) window.localStorage.setItem(STORAGE_KEY, note);
}, [loaded, note]);
return (