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

mdbook-gitinfo 操作手册

mdbook-gitinfo 会把章节对应的 Git 信息注入页面 header、footer 或两者。

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

当前书库只启用了 header，可以在页面顶部查看最后更新时间；底部不再显示构建时间和 commit 信息。

当前显示格式

[preprocessor.gitinfo]
enable = true
header = true
footer = false
align.header = "center"
margin.header.top = "2em"
margin.header.bottom = "2em"
font-size = "0.8em"
separator = " • "
date-format = "%A %d %B %Y"
time-format = "@ %H:%M:%S"
branch = "main"
hyperlink = true
timezone = "source"

[preprocessor.gitinfo.message]
header = "Last updated: <em>{{date}}</em>"

页面顶部会居中显示类似内容，日期部分使用斜体：

Last updated: Thursday 15 January 2026 @ 23:45:51

模板占位符

占位符	含义
`{{hash}}`	短 commit hash
`{{long}}`	完整 commit hash
`{{tag}}`	最近 tag
`{{date}}`	按配置格式化后的提交时间
`{{sep}}`	separator
`{{branch}}`	分支名

样例：日期 + 分支 + Commit

[preprocessor.gitinfo.message]
footer = "Updated {{date}}{{sep}}{{branch}}{{sep}}{{hash}}"

效果类似：

Updated 2026-09-04 • main • a1b2c3d

样例：完整 Commit

[preprocessor.gitinfo.message]
footer = "Commit {{long}}"

只显示顶部：

header = true
footer = false

只显示底部：

header = false
footer = true

上下都显示：

header = true
footer = true

[preprocessor.gitinfo.message]
header = "Last updated: {{date}}"
footer = "{{branch}}{{sep}}{{hash}}"

[preprocessor.gitinfo.message]
both = "{{date}}{{sep}}{{branch}}{{sep}}{{hash}}"

如果某个位置同时定义了专用模板和 both，专用模板优先。

对齐方式

支持：

left
center
right

分别设置：

[preprocessor.gitinfo.align]
header = "left"
footer = "right"

统一设置：

[preprocessor.gitinfo.align]
both = "center"

默认是居中。

Margin

Margin 使用 CSS 风格的 Top / Right / Bottom / Left 顺序。

单值：四边相同

[preprocessor.gitinfo]
margin.both = "1em"

四值数组

[preprocessor.gitinfo]
margin.header = ["0", "0", "1.25em", "0"]
margin.footer = ["2em", "0", "0", "0"]

顺序：

Top Right Bottom Left

单独指定某一边

[preprocessor.gitinfo]
margin.header.top = "1em"
margin.footer.bottom = "2em"

分隔符

当前：

separator = " • "

模板中通过 {{sep}} 使用。

也可以改成：

separator = " | "

日期与时间格式

date-format = "%Y-%m-%d"
time-format = "%H:%M:%S"

常用格式符：

格式	含义
`%Y`	四位年份
`%m`	月
`%d`	日
`%H`	24 小时制小时
`%M`	分钟
`%S`	秒
`%z`	时区 offset

时区

当前：

timezone = "source"

可选：

local
utc
source
fixed:+08:00
fixed:-05:00

例如固定东八区：

timezone = "fixed:+08:00"

若希望时间字符串显示 offset，需要在 time-format 中使用 %z、%:z 或 %Z。

Commit / Branch 超链接

hyperlink = true

插件会尝试从 CI 环境变量或 remote.origin.url 推导远程仓库，把 hash / branch 做成链接。

关闭：

hyperlink = false

Branch

branch = "main"

若指定 branch 找不到，插件会回退到 main 并给出 warning。

GitHub Actions

如果通过 GitHub Actions 构建，希望插件取得完整 Git 历史，应使用：

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

否则 shallow clone 可能使 tag、历史 commit 等信息不完整。

使用方式总结

Gitinfo 与 Mermaid、KaTeX 不同：它通常不需要在 Markdown 正文中写特殊语法。日常使用主要是调整 book.toml 模板、位置、对齐、时间格式和链接行为。

Pages