@show-docs/docusaurus-theme-diff
v0.2.9
Published
Md 的 frontmatter 写 diff 就在正文上方渲染这份文件上一次改动的差异视图
Readme
@show-docs/docusaurus-theme-diff
在文档页正文上方渲染「上一次改动」的 Docusaurus 主题插件。frontmatter 写 diff: true 时,页面
顶部出现这份 markdown 上一个版本与此刻这一份之间的差异视图,正文保持原样。写成
diff: {old: 旧, new: 新} 时,比的是磁盘上那两份文件,与 git 历史无关。
安装
「整页换成差异页」这一格由 theme-component-page 判,本层的共享外壳也住在 theme-component-page 里,
「谁来编本包那几份未编译的 .tsx」由
@show-docs/docusaurus-plugin-compile-source 那一条 babel 规则负责,三个包一起安装:
pnpm add @show-docs/docusaurus-plugin-compile-source @show-docs/docusaurus-theme-component-page @show-docs/docusaurus-theme-diff使用
注册插件
// docusaurus.config.mjs
export default {
plugins: [
'@show-docs/docusaurus-plugin-compile-source',
'@show-docs/docusaurus-theme-diff',
'@show-docs/docusaurus-theme-component-page'
]
};本层在自己的 loadContent() 里交回一对条目(交回的 content 里带 componentPage:组件
@theme/DiffPage 登记成 diff,规则 { key: 'diff', match: 'any' }),由
theme-component-page 那份 DocItem 判表后整页换成它。所以 component-page 要注册,而且要写在
本层之后。那条顺序只管「这一页归谁判」,不管同一页写中多把键时谁先命中(那看站点
component-page 那一列 rules 的顺序)—— 两件事都记在
component-page 的 README的「层栈与代价」那一节,这里不抄第二份。
本层不依赖 theme-iframe。
写 frontmatter
---
title: 差异视图示例
diff: true
---
# 这份文档的改动差异视图渲染在整页内容上方;正文仍由官方 DocItem 正常渲染,标题、目录、翻页都不受影响。
层栈
本层不提供 theme/DocItem:它在 loadContent() 里交出一把 diff 条目(判法 any ——
true、一串路径或 { old, new } 都算命中,组件指回 @theme/DiffPage),由 theme-component-page
在最外那一格命中后把整页换掉。DiffPage 自己也不拼外壳 —— 它向官方要 DocItem
(@theme-init/DocItem;仓库里只有 component-page 这一层提供 DocItem,没有要串的链),把差异
视图摆在它前面,正文一格都不动;frontmatter 没写 diff、或写了却没取到差异时清单不命中,
这一页看不出这一层存在过。
配置
没有插件选项。diff 的值决定比的是什么:
| 写法 | 作用 |
| -------------------------- | ------------------------------------------------------------- |
| diff: true | 本文自己:上一个版本 → 现在磁盘上这一份(含未提交的改动) |
| diff: <路径> | 那份文件:上一个版本 → 现在这一份(路径相对这份 md 所在目录) |
| diff: {old: 旧, new: 新} | 对照磁盘上的那两份文件,不读 git 历史 |
| diff: false | 不开启 |
| 不写 | 不开启 |
单份那条路径写成 diff: intro.md 或 diff: ../other.md 都行,取的是磁盘上的文件,不要求它在
站点里有页面。右边那一格永远是磁盘上此刻这一份:工作区里还有未提交的改动时,改动就在右边,左边
是这份文件上一次被提交的那一版;工作区干净时,右边就是它最后一次被提交的结果,左边往前再取一次
属于这份文件的改动。
两份那条写成 diff: {old: a.md, new: b.md}:old 是「改动之前」那一份、落在视图左边,
new 是「之后」那一份、落在右边,两条谁写在前头都一样,角色由键名定。值也可以折行:diff:
后面空着、把 { } 落在下面几行,或者把 old: 与 new: 各写一行,都认 —— 读的就是 YAML 那一份,
YAML 认的形状这一族就认。地址同样相对这份 md 所在目录,两边都可以不在
git 仓库里,也可以只是站点里的静态资源;两份内容一模一样时不渲染视图(构建日志留一句告警)。
old 与 new 两个键凑不齐、或者那两份里有一份在磁盘上不存在,同样只是不渲染。
工作方式
- 构建时由 webpack loader 从磁盘上的源文件读 frontmatter,再调用本机的
git取差异:单份时先看 工作区里这一份与它上一次被提交时是否一致 —— 不一致就比「这一次提交 → 工作区」,一致才去找动过 这份文件的最后两个提交、比这两者之间的差异;问git时路径只圈这一份文件,别的提交没动过它 就不会进来。两份时直接让git比这两份文件本身。结果都追加到 md 模块的导出上,DiffPage拿到本层数据后把差异视图摆在DocItem前面。 - 差异视图按站点亮暗模式取色;展开与并排视图(GitHub 的分栏样式)在组件里写死。
- 差异数据在构建时就算好了,成品站点里的这一页不需要
git。 - 视图初始化失败时显示一条提示,正文继续渲染。
已知限制
- 只处理
.md文件,.mdx不触发。 diff: true与单份路径那种来源要求站点源码就在一个 git 仓库里,且这份文件至少提交过一次:一次 都没提交过就没有「上一个版本」,只提交过一次、之后又没再改动,那一次就是它自己,同样没得比。 这两种都等于没开这个功能(构建日志里会留一条 warning)。diff: {old: 旧, new: 新}不读 git 历史,不受这两条限制。- 同一条限制在浅克隆上也会命中:CI 默认的检出(depth 1)只有一条提交,比不出上一个版本,
这一页的差异视图整块不出现、只留那句 warning。要它在 CI 里也渲染就给构建一份完整检出
(
actions/checkout的fetch-depth: 0,本站的 e2e 作业就是这么写的)。 - 这份数据是 loader 的产物,走 webpack 的模块缓存:
diff: {old: 旧, new: 新}那两份与被指向的 那一份文件都登记成了依赖,改了会重算;但 git 那一路的左边来自仓库历史,没法当文件登记, 所以「又提交了一次、内容却没变」不会让这一页重算。 - 构建机器上要能找到
git;取不到差异时只跳过这一块视图,不影响整站构建。 - frontmatter 必须是文件开头的 YAML 块;写在正文里的
diff:不会生效。这一族的读法就是官方那一条 (@docusaurus/utils的DEFAULT_PARSE_FRONT_MATTER),跟站点渲染这一页时用的是同一份解析: YAML 读不成一把键的写法(比如diff:true少那一个空格)两边一起看不见。 一行流式映射里那两个地址带逗号要靠引号(写成块式各一行就没这条限制,那是 YAML 的规则, 不是这一族的)。
相关文档
- 维护者文档:组成、
git那几步、取不到差异时的几种落点。 - 差异视图示例(一份文件的上一个版本 → 此刻这一份)。
- 两份文件对照示例(
diff: {old: 旧, new: 新})。 - git-diff-view 文档。
