npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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 的规则, 不是这一族的)。

相关文档