跳转到主要内容

符合CommonMark规范的Markdown格式化工具

项目描述

Documentation Status Build Status codecov.io PyPI version

mdformat

符合CommonMark规范的Markdown格式化工具

Mdformat是一个有观点的Markdown格式化工具,可以用来在Markdown文件中强制执行一致的风格。Mdformat是一个Unix风格的命令行工具,也是一个Python库。

文档中了解更多。

安装

使用CommonMark支持进行安装

pip install mdformat

使用GitHub Flavored Markdown (GFM)支持进行安装

pip install mdformat-gfm

请注意,GitHub的Markdown渲染器支持GFM规范之外的语法扩展。要完全支持GitHub,请

pip install mdformat-gfm mdformat-frontmatter mdformat-footnote

使用Markedly Structured Text (MyST)支持进行安装

pip install mdformat-myst

命令行使用

格式化文件

就地格式化文件 README.mdCHANGELOG.md

mdformat README.md CHANGELOG.md

递归地格式化当前工作目录中的所有 .md 文件

mdformat .

从标准输入读取Markdown,直到 EOF。将格式化的Markdown写入标准输出。

mdformat -

检查格式化

mdformat --check README.md CHANGELOG.md

这不会对文件应用任何更改。如果文件格式不正确,退出代码将不为零。

选项

foo@bar:~$ mdformat --help
usage: mdformat [-h] [--check] [--version] [--number] [--wrap {keep,no,INTEGER}] [--end-of-line {lf,crlf,keep}] [paths ...]

CommonMark compliant Markdown formatter

positional arguments:
  paths                 files to format

options:
  -h, --help            show this help message and exit
  --check               do not apply changes to files
  --version             show program's version number and exit
  --number              apply consecutive numbering to ordered lists
  --wrap {keep,no,INTEGER}
                        paragraph word wrap mode (default: keep)
  --end-of-line {lf,crlf,keep}
                        output file line ending mode (default: lf)

文档

此README仅提供命令行界面的快速入门指南。有关更多信息,请参阅文档。以下是一些入门提示

常见问题解答

为什么不使用 Prettier 呢?

Mdformat 是纯 Python 代码!Python 在 macOS 和几乎所有 Linux 发行版上都预装了,这意味着通常不需要额外安装就可以运行 mdformat。当与 pre-commit (也是 Python) 一起使用时,这个论点同样适用。另一方面,Prettier 需要 Node.js/npm。

Prettier 存在许多缺陷,其中许多会导致 Markdown AST 和渲染的 HTML 发生变化。许多这些问题是使用 remark-parse v8.x 作为 Markdown 解析器造成的,根据作者的自身说法,它不如 mdformat 使用的 markdown-it。宣传中的 remark-parse v9.x 是符合 CommonMark 的,可能修复许多问题,但尚未被 Prettier (v2.4.0) 使用。

Prettier (v2.4.0) 能够格式化许多除了 Markdown 之外的语言,是一个大型软件包,有 65 个直接依赖(mdformat 在 Python 3.11+ 上只有一个)。这在许多环境中可能是一个缺点,例如优化尺寸的 Docker 镜像。

Mdformat 的解析器扩展插件 API 不仅允许自定义使用的 Markdown 规范,还提供了诸如 自动生成目录 等高级功能。此外,还提供了一个代码格式化插件 API,可以实现任何编程语言的嵌入式代码格式化集成。

mdformat 的标志有什么问题?它渲染不正确,总体来说很糟糕。

不,标志实际上很好——你很糟糕。这个标志更像是艺术品而不是标志,描绘了格式糟糕的文本文档的恐怖。这是我制作的!

话虽如此,如果您有任何图形设计技能并想贡献一个修订版本,欢迎提交 PR 😄。

项目详情


下载文件

下载您平台对应的文件。如果您不确定选择哪个,请了解有关 安装包 的更多信息。

源代码分发

mdformat-0.7.17.tar.gz (36.3 kB 查看散列值)

上传时间 源代码

构建分发

mdformat-0.7.17-py3-none-any.whl (28.9 kB 查看散列值)

上传时间 Python 3

由以下支持

AWSAWS云计算和安全赞助商DatadogDatadog监控FastlyFastlyCDNGoogleGoogle下载分析MicrosoftMicrosoftPSF赞助商PingdomPingdom监控SentrySentry错误日志StatusPageStatusPage状态页面