py2md
将源代码文件递归转换为结构化 Markdown 文档的命令行工具。
功能特性
- 多文件类型支持:Python、HTML、CSS、JavaScript、Vue、TypeScript、JSON、XML、YAML
- 递归扫描:自动遍历目标目录下所有匹配文件(支持自定义扩展名)
- 保留层级:输出 Markdown 中完整保留文件的目录结构路径
- 灵活配置:支持自定义编码、排除隐藏文件、多扩展名过滤等选项
- 友好 CLI:基于 Typer 的命令行接口,支持彩色输出和详细统计
- 类型安全:全面使用 Type Hints,提供
py.typed标记文件 - 向后兼容:保留原有
py_to_markdown和html_to_markdown接口
支持的文件类型
| 类型 | 标志 | 扩展名 | 代码块标注 |
|---|---|---|---|
| Python | --py / -py |
.py |
python |
| HTML | --html / -html |
.html, .htm |
html |
| CSS | --css / -css |
.css |
css |
| JavaScript | --js / -js |
.js, .mjs, .cjs |
javascript |
| Vue | --vue / -vue |
.vue |
vue |
| TypeScript | --ts / -ts |
.ts, .tsx |
typescript |
| JSON | --json / -json |
.json |
json |
| XML | --xml / -xml |
.xml |
xml |
| YAML | --yaml / -yaml |
.yaml, .yml |
yaml |
安装
pip install py2md-cli
快速开始
# 整合 Python 文件(默认)
py2md ./src
py2md ./src -py
# 整合 HTML 文件
py2md ./html_files -html
# 整合 CSS 文件
py2md ./styles -css
# 整合 JavaScript 文件
py2md ./scripts -js
# 整合 Vue 文件
py2md ./components -vue
# 整合 TypeScript 文件
py2md ./ts_src -ts
# 整合 JSON 文件
py2md ./config -json
# 整合 XML 文件
py2md ./data -xml
# 整合 YAML 文件
py2md ./config -yaml
# 指定输出文件路径
py2md ./src -py --output docs/code.md
# 使用 GBK 编码读取,并包含隐藏文件
py2md ./src -py --encoding gbk --include-hidden
# 自定义扩展名
py2md ./src -py --ext .py --ext .pyx
命令行参数
| 参数 | 缩写 | 说明 | 默认值 |
|---|---|---|---|
INPUT_DIR |
— | 待扫描的目标文件夹路径(必填) | — |
--py |
-py |
整合 Python 文件(.py) | 默认行为 |
--html |
-html |
整合 HTML 文件(.html, .htm) | — |
--css |
-css |
整合 CSS 文件(.css) | — |
--js |
-js |
整合 JavaScript 文件(.js, .mjs, .cjs) | — |
--vue |
-vue |
整合 Vue 文件(.vue) | — |
--ts |
-ts |
整合 TypeScript 文件(.ts, .tsx) | — |
--json |
-json |
整合 JSON 文件(.json) | — |
--xml |
-xml |
整合 XML 文件(.xml) | — |
--yaml |
-yaml |
整合 YAML 文件(.yaml, .yml) | — |
--output |
-o |
输出 Markdown 文件路径 | {目录名}_{类型}.md |
--encoding |
-e |
读取源文件时使用的字符编码 | utf-8 |
--exclude-hidden / --include-hidden |
— | 是否排除隐藏文件和目录 | 排除 |
--ext |
-x |
自定义文件扩展名(可多次指定,覆盖默认) | 按类型决定 |
输出示例
生成的 Markdown 文件结构如下:
# my_project — Python 文件汇总
> **生成时间**:2026-07-29 10:30:00 UTC
> **根目录**:`/path/to/my_project`
## 路径:`main.py`
```python
# main.py 的源代码内容
路径:utils/helpers.py
# helpers.py 的源代码内容
## 作为 Python 库使用
### 通用接口(推荐)
```python
from py2md import files_to_markdown
# 转换 Python 文件
result = files_to_markdown(
input_dir="./src",
output_path="output.md",
file_type="py",
encoding="utf-8",
exclude_hidden=True,
)
print(f"扫描文件数:{result.files_found}")
print(f"成功:{result.files_success}")
print(f"失败:{result.files_failed}")
# 转换 HTML 文件
result = files_to_markdown("./html_files", "html_output.md", "html")
# 转换 Vue 文件
result = files_to_markdown("./components", "vue_output.md", "vue")
向后兼容接口
from py2md import py_to_markdown, html_to_markdown
# Python 文件转换(原有接口)
result = py_to_markdown(
input_dir="./my_project",
output_path="output.md",
encoding="utf-8",
exclude_hidden=True,
)
print(f"成功率:{result.success_rate}%")
# HTML 文件转换(原有接口)
result = html_to_markdown("./html_files", "html_output.md")
文件类型配置
from py2md import FILE_TYPE_CONFIG
# 查看所有支持的文件类型
for file_type, config in FILE_TYPE_CONFIG.items():
print(f"{file_type}: {config['extensions']} -> ```{config['code_block']}")
从源码安装(开发模式)
git clone https://github.com/py2md/py2md.git
cd py2md
pip install -e ".[dev]"
构建与发布
# 构建分发包
python -m build
# 上传到 PyPI
twine upload dist/*
# 上传到 TestPyPI(测试)
twine upload --repository testpypi dist/*
版本历史
v0.3.0
- 新增多文件类型支持:HTML、CSS、JavaScript、Vue、TypeScript、JSON、XML、YAML
- 新增通用转换函数
files_to_markdown和FILE_TYPE_CONFIG配置 - 新增
FileConversionResult统一转换结果对象 - CLI 新增文件类型切换选项(
--py、--html、--css等) - 默认输出文件名改为
{目录名}_{类型}.md格式 - 保留
py_to_markdown和html_to_markdown向后兼容接口
v0.1.x
- 初始版本,支持 Python 文件递归转换为 Markdown
许可证
Metadata
Release files for py2md-cli 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| py2md_cli-0.2.0.tar.gz | 15.8 kB | Without provenance | Details for py2md_cli-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| py2md_cli-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for py2md_cli-0.2.0-py3-none-any.whl |
Total release size: 31.0 kB
Release files / py2md_cli-0.2.0.tar.gz
| Download URL | py2md_cli-0.2.0.tar.gz |
|---|---|
| Size | 15.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d9975347ffca9b130fcb793d756f20ddb58dece08ac95561e54c92c9075a7c43
|
|
BLAKE2b-256 checksum How to use checksums |
105e6c862126a55dc85d9cc7786d54dd835ab143e7a1d3ffef3054b56b5bd1ca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.13
|
Release files / py2md_cli-0.2.0-py3-none-any.whl
| Download URL | py2md_cli-0.2.0-py3-none-any.whl |
|---|---|
| Size | 15.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0c8d27eea3041fcf86e611c0a688f08897c00695ba24f86dfdef87133bb0e77e
|
|
BLAKE2b-256 checksum How to use checksums |
0fc8c00474fcaf114a52c4bc25d63abdc496c6d463427d14f03846af770660d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.13
|
Security for py2md-cli 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.