为 Astro 博客添加 Markdown 脚注支持
详细介绍如何在 Astro 博客中配置和自定义 Markdown 脚注功能，让你的技术文档更加专业。
views
| comments
前言#
在写技术博客或学术文章时，脚注是一个非常有用的功能。它可以让我们在不打断正文流畅性的前提下，提供额外的信息、引用来源或补充说明。因为最近打算写一些 Talk 类型的内容，所以需要引用一些 Paper，所以需要添加脚注支持。
简单研究了一下如何操作，因此介绍下如何在 Astro 博客中添加 Markdown 脚注支持。
什么是 Markdown 脚注#
Markdown 脚注使用 [^标识符] 的语法来创建引用，然后在文档的任意位置（通常在末尾）定义脚注内容。例如：
这是正文内容[^1]，这里还有一个脚注[^note]。
[^1]: 这是第一个脚注的内容。
[^note]: 这是一个有名称的脚注。
安装必要的依赖#
首先，我们需要安装 remark-gfm 插件，它提供了 GitHub Flavored Markdown 的支持，包括脚注功能：
# 使用 npm
npm install remark-gfm
# 使用 yarn
yarn add remark-gfm
# 使用 pnpm
pnpm add remark-gfm
# 使用 bun
bun add remark-gfm
配置 Astro#
接下来，我们需要修改 astro.config.mjs 文件来启用脚注支持。
基础配置#
import { defineConfig } from 'astro/config'
import remarkGfm from 'remark-gfm'
export default defineConfig({
markdown: {
remarkPlugins: [remarkGfm],
},
})
自定义脚注样式#
为了让脚注更符合中文用户的习惯，我们可以自定义脚注的标签和返回链接：
import { defineConfig } from 'astro/config'
import remarkGfm from 'remark-gfm'
export default defineConfig({
markdown: {
remarkPlugins: [remarkGfm],
remarkRehype: {
footnoteLabel: '脚注',
footnoteBackLabel: '返回内容',
footnoteBackContent: '↑'
},
},
})
配置选项说明：
footnoteLabel: 脚注区域的标题（对屏幕阅读器友好）footnoteBackLabel: 返回链接的无障碍标签footnoteBackContent: 返回链接显示的符号
完整配置示例#
如果你的博客已经有其他 remark 和 rehype 插件，完整的配置可能看起来像这样：
import { rehypeHeadingIds } from '@astrojs/markdown-remark'
import { defineConfig } from 'astro/config'
import rehypeKatex from 'rehype-katex'
import remarkMath from 'remark-math'
import remarkGfm from 'remark-gfm'
export default defineConfig({
markdown: {
remarkPlugins: [remarkMath, remarkGfm],
rehypePlugins: [
[rehypeKatex, {}],
rehypeHeadingIds,
// 其他 rehype 插件...
],
remarkRehype: {
footnoteLabel: '脚注',
footnoteBackLabel: '返回内容',
footnoteBackContent: '↑'
},
},
})
脚注语法示例#
基本脚注#
这是一个包含脚注的句子[^1]。
[^1]: 这是脚注的内容。
具名脚注#
这里引用了一篇论文[^paper2024]。
[^paper2024]: 张三, 李四. "关于某某技术的研究". 技术期刊, 2024.
多行脚注#
这是一个复杂的脚注引用[^complex]。
[^complex]: 这个脚注包含多行内容。
它可以包含：
- 列表项
- 代码块
```javascript
console.log("脚注中的代码");
甚至多个段落。
### 内联脚注
GitHub Flavored Markdown 还支持内联脚注：
```markdown
这是一个内联脚注^[内联脚注的内容直接写在这里]。
注意事项#
开发服务器重启#
重要提示：当你修改 astro.config.mjs 文件后，需要重启开发服务器才能使配置生效。这是因为配置文件的更改涉及到 Astro 的构建流程，无法通过热重载来更新。
脚注标识符#
- 脚注标识符可以是数字、字母或组合
- 标识符区分大小写
- 建议使用有意义的标识符，特别是在长文档中
无障碍性#
脚注功能已经内置了无障碍性支持：
- 使用
aria-describedby属性链接脚注引用和脚注内容 - 提供了对屏幕阅读器友好的标签
- 支持键盘导航
高级自定义#
自定义返回符号#
你可以使用各种符号作为返回链接：
footnoteBackContent: '↑' // 简洁向上箭头
footnoteBackContent: '⤴' // 弯曲箭头
footnoteBackContent: '🔝' // 表情符号
footnoteBackContent: '返回' // 中文文字
实际应用示例#
在技术博客中，脚注特别适用于：
总结#
通过添加脚注支持，我们的 Astro 博客现在具备了更专业的文档撰写能力。脚注不仅让内容更加丰富，还保持了正文的简洁性。记住在修改配置后重启开发服务器，就可以开始在你的博客文章中使用这个强大的功能了。