Last updated: Monday 07 September 2026 @ 20:44:27

mdbook-qr 操作手册

mdbook-qr 在构建时生成 PNG 二维码，并把 Markdown 中的二维码 marker 替换为 <img>。

原仓库：https://github.com/CompEng0001/mdbook-qr

本书当前二维码

当前主二维码编码的是：

https://pages.quaternijkon.online

注意：默认二维码编码的是 book.toml 中配置的 url，不是自动拼接当前章节 URL。

基础用法

默认 marker 为：

{{QR_CODE}}

在 Markdown 中放入它，构建后会替换成二维码图片。

当前配置：

[preprocessor.qr]
enable = true
url = "https://pages.quaternijkon.online"
qr-path = "src/qr.png"
margin = 2
background = "#FFFFFFFF"
module = "#000000FF"

[preprocessor.qr.fit]
width = 256
height = 256

[preprocessor.qr.shape]
circle = true

修改二维码内容

url 本质上是二维码要编码的字符串。

[preprocessor.qr]
url = "https://pages.quaternijkon.online"

也可以是普通文本：

[preprocessor.qr]
url = "Quaternijkon mdBook"

设置尺寸

[preprocessor.qr.fit]
width = 256
height = 256

如果只提供一个维度，插件会把同一个值用于另一个维度。

设置边距

[preprocessor.qr]
margin = 2

margin 是二维码周围的 quiet zone，单位为二维码 module。边距过小可能降低扫描可靠性。

设置颜色

[preprocessor.qr]
background = "#FFFFFFFF"
module = "#000000FF"

支持 #RRGGBB、#RRGGBBAA，也支持 RGB/RGBA 数组形式。前景和背景应保持高对比度。

设置模块形状

支持：

[preprocessor.qr.shape]
square = true
circle = true
rounded_square = true
vertical = true
horizontal = true
diamond = true

多个值同时为 true 时，优先级为：

circle → rounded_square → vertical → horizontal → diamond → square

如果均未指定，默认使用 square。

一个书中生成多个不同二维码

使用 custom.* 定义命名二维码。

样例：GitHub 二维码

[preprocessor.qr]
url = "https://pages.quaternijkon.online"

[preprocessor.qr.custom.github]
marker = "{{QR_GITHUB}}"
url = "https://github.com/Quaternijkon"
qr-path = "src/qr-github.png"
fit.width = 160
fit.height = 160
shape.diamond = true

然后在 Markdown 中使用：

{{QR_GITHUB}}

自定义配置会继承主配置，显式字段覆盖父配置。

本地预览模式

[preprocessor.qr]
localhost-qr = true

本地预览时会生成指向：

http://127.0.0.1:3000/

的开发二维码，并使用专门的本地图片路径。

常见问题

页面没有二维码

检查：

Markdown 中是否放了对应 marker；
custom 二维码是否定义了 marker；
enable 是否为 true。

扫出来不是当前文章

这是正常的。默认 QR 编码固定 url。如果不同页面需要不同目标地址，应定义不同的 custom marker / URL。

Keyboard shortcuts

Pages