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 编写的、快速、简洁且功能强大的静态网站生成器,专门用于创建项目文档。
它的核心设计理念是简单易用,其主要特点包括:
- 文档即源码:使用易于编写的 Markdown 格式来撰写内容,通过一个 YAML 配置文件 (
mkdocs.yml) 来管理网站导航和设置。
- 即时预览:内置开发服务器,支持在编写文档时实时预览更改。
- 主题化:拥有丰富的主题系统(如广受欢迎的 Material for MkDocs 主题),可以轻松定制网站外观。
- 插件化架构:这是其早期获得成功的关键,允许通过插件扩展其功能(如支持代码文档生成、SEO优化等)。
核心工作流程非常简单:
- 在
docs 文件夹中编写 Markdown 文件。
- 配置
mkdocs.yml 文件,定义网站结构。
- 运行
mkdocs build 命令生成一个完整的静态网站(通常是 HTML、CSS、JS 文件)。
- 可以轻松地将生成的站点部署到 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 的生态位已被三个竞品瓜分:
- ProperDocs (@oprypin):MkDocs 1.x 的延续,强调向下兼容和插件生态。
- https://properdocs.org/
- https://github.com/ProperDocs/properdocs
- BSD-2-Clause license
- 80 stars
- Python
-
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.
-
MaterialX (@jaywhj):Material for MkDocs 的社区延续版本。
- https://jaywhj.github.io/mkdocs-materialx/
- https://github.com/jaywhj/mkdocs-materialx
- MIT license
- 87 stars
- Python
根本原因复盘
- 治理失败:创始人长期缺席后突然回归“夺权”,无视社区贡献者的历史功绩和现有生态。
- 技术独裁:在未达成共识的情况下,强行推行破坏性变更,且拒绝公开协作。
- 生态反噬:当核心工具(Material)与上游(MkDocs)决裂,用户被迫用脚投票,导致项目事实性死亡。
开发工具
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
- Ctrl + Shift + P,输入 Install Package Control
- Ctrl + Shift + P,输入 Package Control: Install Package,弹出来的搜索框中输入 ChineseLocalizations,选中点击安装。
- 几秒之后,等中文包安装好,UI 就换成中文显示了。
备注:快捷键
Shift + Alt + Up/Down: 多行编辑
开发工具
2025-05-24
几年前就用过 sunny,这次因为一些特殊场景又要用到网络穿透,又捡起来了。
- 先在他们官网上创建隧道(选择本地地址,还有远程端口)
- 下载 sunny 程序(他们定制的 ngrok 客户端)
- 执行他们隧道管理页面提供的命令 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
DB 开发工具 macOS
2024-06-24
今天,办公电脑出了故障(电源坏了),我切换到 MacBook 工作。
用了很多年的 HeidiSQL 没有 Mac 版本,只能用跨平台的 DBeaver 社区版了。
brew install --cask dbeaver-community
-
安装目录:
Windows: C:\Users\nosch\AppData\Local\DBeaver
MacOS: /Applications/DBeaver.app/
-
配置文件目录:
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 中。
-
创建第一个 MySQL 数据库连接时,需要下载 MySQL 驱动。
DBeaver 支持几十种不同的库,包括 NoSQL,例如 MongoDB 和 Redis,不过 NoSQL 功能需要付费,每个月几十刀。
从 HeidiSQL 导出配置文件到 DBeaver
我之前有一个脚本导出 HeidiSQL 数据库配置到 JSON 文件中。
这次直接写一个脚本来从 JSON 同步到 DBeaver 配置文件。
配置文件同步
ln -sf ~/Documents/Mine/Sync/DBeaver ~/Library/DBeaverData/workspace6/General
开发工具 计算机网络 VPN NAT iptables
2023-04-23
2021/05/09,VPN 与 NAT 讲了我使用 Windows route 命令和 Linux iptables 命令做 NAT,实现 Windows 机器的 VPN 流量走 Linux 的指定网络设备。
现在情况可能会发生一些新的变化,所以这里记录一下我的几点思路。
开发工具
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
Git 开发工具
2022-01-17
读到微信公众号文章 本地如何配置多个 GitHub/Gitee 账号?,想起了几年前,面对这样的需求,我自己也是这么操作的。
Linux Curl dig 开发工具 DNS
2021-12-17
:) 本文正在编辑中,暂时不提供浏览...
开发者 开发工具 在线服务
2021-11-18
编辑器
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 [已安装]
开发工具 内网穿透
2021-05-17

开发工具 计算机网络 VPN NAT iptables
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
参考资料与拓展阅读
开发工具 密码学 OTP Auth 信息安全
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 基于时间
- 协商起始时间 T0 和时间间隔 TX
- 双方分别计算时间计数器 CT
- 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,但是更进一步简化,以约定代替了协商过程。
- T0 为 Unix 时间
- TX 为 30 秒
- 哈希算法为 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]))
参考资料与拓展阅读
Linux 开发工具 jq JSON
2021-03-04

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!!!
开发工具 Windows
2021-02-14
Windows CMD 太挫,中文字体选择少,XP, Win7 下只有点阵字体 (fixedsys) 和新宋体,Win10 字体又多了几个,但效果页不太好。
不过 Win10 的话,可能是半年前吧,微软新出来了一个 Windows Terminal 的虚拟终端,就现代化多了。现在我在 Windows 下(偶尔)一般都是用的新版 Terminal + PowerShell,听方便。
但如果由于 OS 版本等问题,离不开 cmd 的话,有两个方法,一个是使用第三方终端模拟器,比如 cmder;再一个就是想办法定制一下 cmd 的字体。
我在这里记录一下之前使用的一个方案失效地址(确认有效,不过好久都没有用了)。
Linux 开发工具
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))
Linux PowerShell 开发工具
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
开发工具 Git
2019-08-01
git log --diff-filter=A --follow --format="%h %ad %ce" -1 -- requirements.txt | cat
# 6a0eebf 2019-05-22 19-47-09 bobo@example.com
参考:https://stackoverflow.com/questions/2390199/finding-the-date-time-a-file-was-first-added-to-a-git-repository
开发工具 GitLab MySQL PostgreSQL
2019-07-03
看到新闻,Gitlab 从 12.1 版本开始将不再支持 MySQL,理由是:
Gitlab 支持的另一个数据库是 PostgreSQL,意思是 PostgreSQL 不存在上面的问题。
这也可以看作是二者的部分区别吧!
值得研究研究。