开源文档工具 MkDocs 项目的崩塌与生态分裂始末

2026-04-02
  • https://www.mkdocs.org/
    • https://github.com/mkdocs/mkdocs
    • BSD-2-Clause license
    • 21.9K stars
    • Python
    • 当前版本:Version 1.6.1 (2024-08-30)
  • https://squidfunk.github.io/mkdocs-material/
    • https://github.com/squidfunk/mkdocs-material
    • MIT license
    • 26.4K stars
    • Python

MkDocs 是一个用 Python 编写的、快速、简洁且功能强大的静态网站生成器,专门用于创建项目文档。

它的核心设计理念是简单易用,其主要特点包括:

  1. 文档即源码:使用易于编写的 Markdown 格式来撰写内容,通过一个 YAML 配置文件 (mkdocs.yml) 来管理网站导航和设置。
  2. 即时预览:内置开发服务器,支持在编写文档时实时预览更改。
  3. 主题化:拥有丰富的主题系统(如广受欢迎的 Material for MkDocs 主题),可以轻松定制网站外观。
  4. 插件化架构:这是其早期获得成功的关键,允许通过插件扩展其功能(如支持代码文档生成、SEO优化等)。

核心工作流程非常简单:

  1. 在 docs 文件夹中编写 Markdown 文件。
  2. 配置 mkdocs.yml 文件,定义网站结构。
  3. 运行 mkdocs build 命令生成一个完整的静态网站(通常是 HTML、CSS、JS 文件)。
  4. 可以轻松地将生成的站点部署到 GitHub Pages、Netlify 等托管服务。

MkDocs 因其极低的学习成本和优雅的输出效果,长期以来是 Python 生态乃至更广技术社区中创建项目文档的首选工具之一。

项目的崩塌与生态分裂始末

The Slow Collapse of MkDocs

这篇文章复盘了 Python 静态站点生成器 MkDocs 从 2014 年诞生到 2026 年陷入“慢速崩塌”的全过程。
核心矛盾在于:创始人回归后推行破坏生态的激进重构(v2),与社区长期维护者及插件生态爆发激烈冲突,最终导致项目分裂。

核心冲突:技术路线与社区治理的撕裂

  • v2 激进重构:创始人 @lovelydinosaur 主导的 MkDocs 2.0 计划移除插件系统,改为私有开发模式,被社区视为“开倒车”和背离开源精神。
  • 生态断裂:Material for MkDocs(最受欢迎的主题)因 v2 不兼容宣布进入维护模式,并另起炉灶开发 Zensical。
  • 权力斗争:前核心维护者 @oprypin 因权限被削与创始人产生激烈冲突,甚至上演了短暂的 PyPI 仓库“夺权”闹剧。

时间线:从繁荣到分裂

时间 关键事件 影响
2014-2021 项目诞生,@waylan 长期单核维护 项目成熟但进展缓慢
2021-2024 @oprypin 接手,进入活跃维护期 功能迭代稳定,生态繁荣
2024 创始人回归,@oprypin 被削权出走 核心开发停滞,社区分裂
2025-2026 MkDocs v2 公布(无插件),Material 停更 生态彻底崩塌,替代品涌现

当前格局:三分天下

MkDocs 的生态位已被三个竞品瓜分:

  1. ProperDocs (@oprypin):MkDocs 1.x 的延续,强调向下兼容和插件生态。
    • https://properdocs.org/
    • https://github.com/ProperDocs/properdocs
    • BSD-2-Clause license
    • 80 stars
    • Python
  2. Zensical (@squidfunk):Material 团队重写,性能更强,旨在成为下一代标准。

    • https://zensical.org/
    • https://github.com/zensical/zensical
    • MIT license
    • 4.1K stars
    • Rust

    Zensical is a modern static site generator designed to simplify building and maintaining project documentation. It's built by the creators of Material for MkDocs and shares the same core design principles and philosophy – batteries included, easy to use, with powerful customization options.

  3. MaterialX (@jaywhj):Material for MkDocs 的社区延续版本。

    • https://jaywhj.github.io/mkdocs-materialx/
    • https://github.com/jaywhj/mkdocs-materialx
    • MIT license
    • 87 stars
    • Python

根本原因复盘

  • 治理失败:创始人长期缺席后突然回归“夺权”,无视社区贡献者的历史功绩和现有生态。
  • 技术独裁:在未达成共识的情况下,强行推行破坏性变更,且拒绝公开协作。
  • 生态反噬:当核心工具(Material)与上游(MkDocs)决裂,用户被迫用脚投票,导致项目事实性死亡。

Sublime Text

2025-09-29

Ubuntu 上 VSCode 打不开,应该是哪里报错了。
没空折腾,就直接安装一个 Subline Text 满足基本文档编辑需求。

-> % wget -qO - https://download.sublimetext.com/sublimehq-pub.gpg | sudo tee /etc/apt/keyrings/sublimehq-pub.asc > /dev/null

-> % echo -e 'Types: deb\nURIs: https://download.sublimetext.com/\nSuites: apt/stable/\nSigned-By: /etc/apt/keyrings/sublimehq-pub.asc' | sudo tee /etc/apt/sources.list.d/sublime-text.sources
Types: deb
URIs: https://download.sublimetext.com/
Suites: apt/stable/
Signed-By: /etc/apt/keyrings/sublimehq-pub.asc

-> % sudo apt update
-> % sudo apt search sublime
-> % sudo apt install sublime-text
  1. Ctrl + Shift + P,输入 Install Package Control
  2. Ctrl + Shift + P,输入 Package Control: Install Package,弹出来的搜索框中输入 ChineseLocalizations,选中点击安装。
  3. 几秒之后,等中文包安装好,UI 就换成中文显示了。

备注:快捷键

Shift + Alt + Up/Down: 多行编辑

网络工具:sunny

2025-05-24

几年前就用过 sunny,这次因为一些特殊场景又要用到网络穿透,又捡起来了。

  1. 先在他们官网上创建隧道(选择本地地址,还有远程端口)
  2. 下载 sunny 程序(他们定制的 ngrok 客户端)
  3. 执行他们隧道管理页面提供的命令 sunny --server=free.idcfengye.com:4443 --key=xxxx 就行了

如果临时使用一下的话,nuhup + & 就够:

nuhup sunny --server=free.idcfengye.com:4443 --key=xxx &

如果要求更高,那就用 systemd 保活:

sudo vim /etc/systemd/system/sunny-eqr.service
sudo chmod 644 /etc/systemd/system/sunny-eqr.service
sudo systemctl enable sunny-eqr.service
sudo systemctl start sunny-eqr.service
sudo systemctl status sunny-eqr.service

需要吧把注删除
[Service]
ExecStart=/home/catroll/Documents/Mine/sunny --server=free.idcfengye.com:4443 --key=xxx
Restart=always
RestartSec=3
# 每10秒检查一次 (程序不支持 watchdog 协议)
# WatchdogSec=10
# 启动前等待2秒
ExecStartPre=/bin/sleep 2
# 自定义停止命令
ExecStop=/usr/bin/pkill -f sunny
# 限制最大内存使用
MemoryMax=512M
# 限制CPU使用率
CPUQuota=80%

先配置 ssh 证书信任,然后就关闭密码登录,后续就通过证书认证。

# 将自己的公钥配置到服务器上(在本地执行)
ssh-copy-id -i /path/to/id_rsa -p 10022 admin@free.idcfengye.com

# 修改服务器 ssh 配置(在服务器执行)
# PermitRootLogin no
# PasswordAuthentication no
sudo vim /etc/ssh/sshd_config
sudo systemctl restart sshd

# 测试链接情况(在本地执行)
ssh -i /path/to/id_rsa -p 10022 admin@free.idcfengye.com

DBeaver on MacBook

2024-06-24

今天,办公电脑出了故障(电源坏了),我切换到 MacBook 工作。
用了很多年的 HeidiSQL 没有 Mac 版本,只能用跨平台的 DBeaver 社区版了。

brew install --cask dbeaver-community
  1. 安装目录:

    Windows: C:\Users\nosch\AppData\Local\DBeaver
    MacOS: /Applications/DBeaver.app/

  2. 配置文件目录:

    Windows: C:\Users\nosch\AppData\Roaming\DBeaverData
    Ubuntu: ~/snap/dbeaver-ce/current/.local/share/DBeaverData
    MacOS: ~/Library/Application Support/DBeaverData

    $ tree -a
    .
    ├── .workspaces
    ├── drivers // 驱动相关,忽略
    ├── secure
    │   └── secure_storage
    ├── settings
    │   └── global-settings.ini
    └── workspace6
        ├── .metadata // 忽略
        └── General
            ├── .dbeaver
            │   ├── credentials-config.json
            │   ├── data-sources.json
            │   └── project-settings.json
            ├── .project
            └── .settings
                └── org.eclipse.core.resources.prefs
    

    PS: 默认给我创建的工作区叫做:workspace6
    PS:用户配置在 workspace6/General/.dbeaver/ 目录,连接信息在 data-sources.json 中,但是密码是加密的,保存在 credentials-config.json 中。

  3. 创建第一个 MySQL 数据库连接时,需要下载 MySQL 驱动。
    DBeaver 支持几十种不同的库,包括 NoSQL,例如 MongoDB 和 Redis,不过 NoSQL 功能需要付费,每个月几十刀。

从 HeidiSQL 导出配置文件到 DBeaver

我之前有一个脚本导出 HeidiSQL 数据库配置到 JSON 文件中。
这次直接写一个脚本来从 JSON 同步到 DBeaver 配置文件。

配置文件同步

ln -sf ~/Documents/Mine/Sync/DBeaver ~/Library/DBeaverData/workspace6/General

赞美内网云

2023-03-31

之前用过 Sunny-Ngrok,注册一个账号,有免费的套餐,有很多种方式部署使用。
刚发现现在要搞实名认证,而且只有付费才能使用。

在网上搜索了一下,发现一个好用的内网穿透工具:内网云。免费,然后更方便。
不需要注册,用的 SSH 方案,只需要一行 ssh 命令,做一个远程端口转发,就能实现内网穿透。
给了我这样的开发者非常大的便利。希望能一直用下去~

ssh -R 80:127.0.0.1:8080 sh@sh3.neiwangyun.net
Welcome to network server by neiwangyun.net
current server node : sh3.neiwangyun.net
----------------------------------------------------------
Basic Tunnel Information
  username      : sh
  type          : anonymous
  subdomain     : sxxelgxzm6efshsh3.neiwangyun.net
  remote_ip     : 121.60.84.218
  bandwidth     : 2 Mbps
  expire_time   : 2 hours
  unid          : d8scvjne5lt2c3svr2rny...
----------------------------------------------------------
Local Server
  local server: 127.0.0.1:8000
----------------------------------------------------------
Access to the Tunnel
  cname         : not support
  http          : http://sxxelgxzm6efshsh3.neiwangyun.net
  https         : https://sxxelgxzm6efshsh3.neiwangyun.net
  ipport        : sxxelgxzm6efshsh3.neiwangyun.net:25207
----------------------------------------------------------
Ctrl+C Exit Process

常用工具汇总

2021-11-18

编辑器

  • VSCode
  • JetBrains 全家桶

SSH

数据库 GUI

Redis GUI

虚拟化与容器

  • VirtualBox
  • Vagrant
  • Docker

编程相关

  • gitg
  • Beyond Compare 可以一直试用
  • Meld Linux 下的简化版 Beyond Compare

其他

在线服务

Git 命令

2021-08-04

看到有篇文章说是 git “新增”了 switch 和 restore 两个命令,仔细一看,原来就是 2019 年就引入了的两个命令,不过我确实没有用过。

这里重新整理一下现在 git 的命令。

git version
git version 2.30.2

apt list --installed | grep ^git
git-doc/hirsute,hirsute,now 1:2.30.2-1ubuntu1 all [已安装]
git-extras/hirsute,hirsute,now 6.1.0-1 all [已安装]
git-flow/hirsute,hirsute,now 1.12.3-1 all [已安装]
git-man/hirsute,hirsute,now 1:2.30.2-1ubuntu1 all [已安装,自动]
git-svn/hirsute,hirsute,now 1:2.30.2-1ubuntu1 all [已安装]
git/hirsute,now 1:2.30.2-1ubuntu1 amd64 [已安装]
gitg/hirsute,now 3.32.1-1 amd64 [已安装]
gitk/hirsute,hirsute,now 1:2.30.2-1ubuntu1 all [已安装]

VPN 与 NAT

2021-05-09

我公司办公环境需要用到 OpenVPN,之前允许一个账号在两处登录,现在处于安全考虑只允许一处登录了。
然后,我就不方便了,因为我办公环境有两台电脑(台式机 Windows,笔记本 Ubuntu)都需要接入 VPN。

nmap 基本用法

2021-05-01

检查端口可连接性,并支持检测操作系统信息、占用端口的常见应用程序。

  • 开放(Open)
  • 关闭(Closed)
  • 过滤(Filtered)
  • 未过滤(Unfiltered)
  • 开放或过滤(Open|Filtered)
  • 关闭或过滤(Closed|Filtered)

  • 默认扫描常用端口

常用命令

nmap 192.168.31.0/24

# Ping扫描
nmap -sn 192.168.31.0/24
# 快速端口扫描
nmap -F  192.168.31.0/24

# 操作系统
sudo nmap -O -v 192.168.31.42
sudo nmap -A -v 192.168.31.42  # 输出更详细

# 常规检查:端口(-sV)和操作系统(-O)
sudo nmap -sV -O 192.168.31.42

# 检查指定端口
nmap -p 22 192.168.31.42
nmap -p 22,80,443,3306 192.168.31.42
# 所有端口
nmap -p 1-65525 192.168.31.42
nmap -p-        192.168.31.42
# 加上使用这个端口的服务版本信息
nmap -p 22 192.168.31.42 -sV

# 对端口进行探测
nmap -PS 192.168.31.42  # SYN
nmap -PA 192.168.31.42  # ASK
nmap -PU 192.168.31.42  # UDP

sudo nmap -sS 192.168.1.1-10   # SYN
sudo nmap -sA 192.168.31.0/24  # ACK
sudo nmap -sF 192.168.31.0/24  # FIN
sudo nmap -sN 192.168.31.0/24  # TCP Null
sudo nmap -sT 192.168.31.0/24  # TCP Connect
sudo nmap -sU 192.168.31.0/24  # UDP
sudo nmap -sO 192.168.31.0/24  # IP 协议扫描

nmap -O  192.168.0.1/16
nmap -sP 192.168.0.1/16

nmap -sSU 192.168.1.1/24
# Ping Scan
# Parallel DNS resolution
# SYN Stealth Scan
# UDP Scan

参考资料与拓展阅读

谷歌身份认证器

2021-03-08

基础概念

身份验证器

Authenticator

密码就算是身份验证器。
加密密钥,比如 SSH 的公钥私钥(密钥对)

动态密码

One-time Password, 缩写: OTP, 又叫做一次性密码

我们常用的的短信验证码就是一种非常方便快捷的动态密码形式。
早些年一些网络服务,比如谷歌、网易通行证等,可能会提供一个动态口令表,包含十几个密码,可以保存为图片,或者纯文本,上面的密码可以逐个使用,每个密码只能用一次。

  • RFC4226 HOTP: An HMAC-Based One-Time Password Algorithm
  • RFC6238 TOTP: Time-Based One-Time Password Algorithm

HOTP 基于 HMAC 算法

简单来说就是根据密钥和计数器来生成一个一次性密码。
除了记住密钥之外,你还要记住这是第几次使用。

  • HOTP value = HOTP(K, C) mod 10d
  • HOTP(K, C) = truncate(HMACH(K, C))
  • truncate(MAC) = extract31(MAC, MAC[(19 × 8) + 4:(19 × 8) + 7] × 8)
  • MAC[(19 × 8) + 4:(19 × 8) + 7] × 8
    取第十九字节的后四位(小端序), 转成一个有符号整型数(小端序),作为截取 MAC 的位置
  • extract31(MAC, i) = MAC[i × 8 + 1:i × 8 + (4 × 8) − 1]
  • MAC[i × 8 + 1:i × 8 + (4 × 8) − 1]
    从上一步得到的位置处,取四个字节,去掉符号位(小端序)

TOTP 基于时间

  1. 协商起始时间 T0 和时间间隔 TX
  2. 双方分别计算时间计数器 CT
  3. TOTP value(K) = HOTP value(K, CT)

多重要素验证

Multi-factor authentication, 缩写: MFA
Two-factor authentication, 缩写: 2FA

谷歌身份验证器

Google 身份验证器是一款 TOTP 与 HOTP 的两步验证软件令牌,此软件用于 Google 的认证服务。此项服务所使用的算法已列于 RFC 6238 和 RFC 4226 中。
Google 身份验证器给予用户一个六位到八位的一次性密码用于进行登录 Google 或其他站点时的附加验证。其同样可以给第三方应用生成口令,例如密码管理员或网络硬盘。先前版本的 Google 身份验证器开放源代码,但之后的版本以专有软件的形式公开。

谷歌验证器基于 TOTP,但是更进一步简化,以约定代替了协商过程。

  1. T0 为 Unix 时间
  2. TX 为 30 秒
  3. 哈希算法为 sha1

此外:

虽然不是很大的创新,而且这个软件验证器实现很简单,但是免费、开放(不需要做任何谷歌服务绑定),加上谷歌的强大影响力,这个软件验证器被很多系统采用。
最后,其他提供动态口令的应用都需要来兼容谷歌身份验证器。

PS: RedHat 开发并维护了开源的 FreeOTP 分支项目。

PS: 微软也有一个 Microsoft Authenticator,阿里云 APP 中有一个 虚拟MFA 功能,都是一个意思。
微软家的为自己提供 8 位密码,别人家的就 6 位,区别对待(虽然感觉好像也并没有什么影响)
阿里云 MFA 是需要手机 APP 登录进去之后才能使用的。

Just4Fun

import base64
import hashlib
import hmac
import time

DEFAULT_INTERVAL = 30  # Google Authenticator: 30 秒
DEFAULT_HASH = hashlib.sha1


def get_hotp_token(secret: str, counter: int, hash_algorithm=DEFAULT_HASH, length=6):
    padding_len = 8 - len(secret) % 8
    if padding_len != 8:
        assert 1 <= padding_len <= 7
        secret += '=' * padding_len
    key = base64.b32decode(secret, True)
    message = (counter & 0xffffffffffffffff).to_bytes(8, 'big')
    mac = hmac.new(key, message, hash_algorithm).digest()
    loc = mac[-1] & 0x0F
    token = (int.from_bytes(mac[loc:loc+4], 'big') & 0x7fffffff) % (10 ** length)
    return token


def get_totp_token(secret, interval=DEFAULT_INTERVAL):
    time_counter = int(time.time()) // interval
    return get_hotp_token(secret, time_counter)


if __name__ == '__main__':
    print('%06d' % get_totp_token(sys.argv[1]))

参考资料与拓展阅读

使用 jq 命令解析 JSON 数据

2021-03-04

JSON Logo

jq 是我在命令行中解析 JSON 的一个常用工具,用起来非常顺手。

  • https://github.com/stedolan/jq
  • https://stedolan.github.io/jq/

用法

curl https://24pullrequests.com/users.json | jq

# 取第一个元素
curl https://24pullrequests.com/users.json | jq '.[0]'
# 取第一个元素的指定字段
curl https://24pullrequests.com/users.json | jq '.[0].nickname'

# 切片
curl https://24pullrequests.com/users.json | jq '.[:2]'

# 遍历
curl https://24pullrequests.com/users.json | jq '.[] | .nickname'

# 取字段
curl https://24pullrequests.com/users/changeworld.json | jq .nickname

# 取多个字段
curl https://24pullrequests.com/users/changeworld.json | jq '.nickname,.contributions_count'

# 获取列表长度
curl https://24pullrequests.com/users.json | jq length

# 列出 Keys
curl https://24pullrequests.com/users/changeworld.json | jq keys
curl https://24pullrequests.com/users/changeworld.json | jq "keys[]"
curl https://24pullrequests.com/users.json | jq ".[0] | keys[]"

# 列出 Keys 和 值类型
cat a.json | jq ".[0] | keys,map(type)"
cat a.json | jq ".[0] | to_entries | map([.key, (.value | type)])"
cat a.json | jq '.[0] | to_entries | map("\(.key) : \(.value|type)")[]'

还有很多更强大的用法,可以参考文档,我就会上面几个,在命令行中简单搜索 JSON 也够用了。

刚在文档中学会一招,重新组合 JSON:

curl https://24pullrequests.com/users/changeworld.json | jq '[.nickname, .organisations[].login]'
curl https://24pullrequests.com/users/changeworld.json | jq '{name:.nickname, orgs:[.organisations[].login]}'

👍🏻 Nice!!!

修改 cmd 字体

2021-02-14

Windows CMD 太挫,中文字体选择少,XP, Win7 下只有点阵字体 (fixedsys) 和新宋体,Win10 字体又多了几个,但效果页不太好。
不过 Win10 的话,可能是半年前吧,微软新出来了一个 Windows Terminal 的虚拟终端,就现代化多了。现在我在 Windows 下(偶尔)一般都是用的新版 Terminal + PowerShell,听方便。
但如果由于 OS 版本等问题,离不开 cmd 的话,有两个方法,一个是使用第三方终端模拟器,比如 cmder;再一个就是想办法定制一下 cmd 的字体。
我在这里记录一下之前使用的一个方案失效地址(确认有效,不过好久都没有用了)。

GNU/Linux 上如何快速创建一个大文件?「from StackOverflow」

2019-12-25

在 StackOverflow 上看到好些种快速创建文件的命令,逐个测试,在 Ubuntu 下可用的方法有以下几种:

time dd if=/dev/zero of=test.img bs=10M iflag=fullblock,count_bytes count=10G
# 0.00s user 0.45s system 1% cpu 39.144 total

# 在 xfsprogs 包中:
# -n 表示不写入数据
time xfs_mkfile -n 10g test.img
# 0.01s user 0.01s system 2% cpu 0.669 total

# 在 VBox 挂载的虚拟磁盘上执行时遇到 “不支持的操作” 错误
# 在 EXT4 磁盘上没有遇到问题,速度很快
time fallocate -l 10G test.img

time truncate -s 10G test.img
# 0.00s user 0.00s system 46% cpu 0.005 total

time dd if=/dev/zero of=test.img bs=1 count=0 seek=10G
# 0.00s user 0.00s system 77% cpu 0.002 total

最后看到的 dd seek 方案深得征信深得朕心。

根据这个思路,Python 创建 10G 的文件应该这么写(也是我一直以来的写法):

GB = 1 << 30
with open('test.img', 'w') as _file:
    _file.seek(10 * GB - 1)
    _file.write(chr(0))

PowerShell 在 Ubuntu 下的安装和试用

2019-08-22

PowerShell 的最近的一次更新修复了其作为 SSH 的登录 Shell 的一些问题。
Win 10 对 NFS,SSH 的支持推进也是有目共睹。
随着 MS 对 Windows 的策略调整,估计以后 Windows 服务器也会变多。

# Download the Microsoft repository GPG keys
wget -q https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb

# Register the Microsoft repository GPG keys
sudo dpkg -i packages-microsoft-prod.deb

# Update the list of products
sudo apt-get update

# Enable the "universe" repositories
sudo add-apt-repository universe

# Install PowerShell
sudo apt-get install -y powershell

# Start PowerShell
pwsh

PS 常用命令

# 获取本地 IP
(invoke-webrequest -uri "http://ifconfig.me/ip").content

get-nettcpconnection | where-object {$_.State -eq "Listen"}
get-nettcpconnection -localport 49667
get-process -id (get-nettcpconnection -localport 49667).owningprocess
stop-process -id (get-nettcpconnection -localport 11).owningprocess

"# README" | out-file README.md
type README.md

Gitlab 从 12.1 版本开始将不再支持 MySQL

2019-07-03

看到新闻,Gitlab 从 12.1 版本开始将不再支持 MySQL,理由是:

Gitlab 支持的另一个数据库是 PostgreSQL,意思是 PostgreSQL 不存在上面的问题。
这也可以看作是二者的部分区别吧!

值得研究研究。