TL;DR
pymarkdownlnt (opens new window) 提供了一种简便的方法来检查你正在编辑的Markdown (opens new window) 是否符合一些明智的指南。如果你熟悉Python虚拟环境，你可能不需要阅读这篇文章的其余部分。
为什么？
最近，我花了很多时间在key Atsign repos (opens new window)中添加OpenSSF Scorecards (opens new window)。
逐步建立更好的安全习惯
在处理文档存储库时，我需要一种测试它们并检查Markdown是否符合一组规则的方法。
Yak shave 1 – 较新的Python
我日常使用的WSL2环境是Ubuntu 20.04。我应该很久以前就将其升级到22.04，但考虑到24.04即将发布... Ubuntu 20.04使用Python 3.8作为系统Python。对于pymarkdownlint来说并不太旧，但也不是最理想的版本。我通常喜欢使用最新的稳定版本，现在是3.12版本。幸运的是，通过使用deadsnakes存储库，很容易安装新版本的Python，而不影响系统自带的Python。
sudo add-apt-repository ppa:deadsnakes/ppasudo apt updatesudo apt install python3.12
系统环境与Python虚拟环境 #
我本可以直接运行pip3 install pymarkdownlint，但现在越来越多的人意识到使用系统软件包管理器安装Python包并不是一个好主意。像Debian 12和Raspberry Pi OS 'Bookworm'这样的新发行版阻止使用pip。很多人觉得这很烦人，但通过安装无法工作的依赖项的新版本来破坏系统软件包也同样令人烦恼。多年来我一直避免使用虚拟环境（venv），但似乎现在是时候跟上潮流了。
我为linter创建了一个虚拟环境：
python3 -m venv 安装pymarkdownlnt到虚拟环境
首先需要激活虚拟环境：
. ~/python/venvs/pymarkdownlnt/bin/activate
然后可以安装linter。
pip install pymarkdownlnt
使用uv进行虚拟环境和pip
[uv](https://astral.sh/blog/uv)是Astral公司发布的一个全新工具（昨天发布）。我一直在使用他们的[ruff](https://astral.sh/ruff) Python代码检查工具，速度令人印象深刻。
安装uv后，我可以重复上面的过程，多输入一些按键，等待时间也少一些：
uv venv ~/python/venvs/pymarkdownlnt -p python3.12. ~/python/venvs/pymarkdownlnt/bin/activateuv pip install pymarkdownlnt
现在我可以检查一些Markdown了
每当我想要检查一些Markdown时，我只需要激活我的pymarkdownlnt虚拟环境并运行linter来检查我的文件：
pymarkdownlnt scan somefile.md
使用GitHub Actions自动化检查
能够检查一些内容是非常好的。 在提交之前先检查Markdown的格式是否良好。但我真正想要的是阻止不良格式的Markdown首先进入存储库。这可以通过GitHub Actions工作流程[pymarkdownlnt.yml](https://github.com/atsign-foundation/at_protocol/blob/trunk/.github/workflows/pymarkdownlnt.yml)来实现。
关键部分如下：
- name: 安装并运行代码检查
run: |-
python3 -m pip install --require-hashes \
-r tools/requirements.txt
pymarkdownlnt -d MD013,MD024 scan */*.md
这将从一个requirements.txt文件中安装pymarkdownlnt，其中我已经固定了包的哈希（以确保评分卡的满意），然后运行代码检查来检查存储库中的所有Markdown文件。
在这种情况下，由于我们有一些不可避免地有非常长的行的表格，并且设置`siblings_only`功能似乎没有按照预期工作，因此已经抑制了一些规则。
### 更新
我已经在各种文件中的有长行的地方上面添加了特殊标记，因此不需要将其删除。 这是个好办法，因为现在将会捕捉到不需要长行的新文件。我还提出了一个[问题](https://github.com/jackdewinter/pymarkdown/issues/1000)关于设置MD024的siblings_only的问题。与此同时，我已经修改了工作流程：
- name: 安装并运行linter
run: |-
python3 -m pip install --require-hashes
-r tools/requirements.txt
pymarkdownlnt -c tools/pymarkdownlnt.conf
scan /.md
使用一个配置文件tools/pymarkdownlnt.conf：
{"plugins": {"md024": {"siblings_only": True}}}