Skip to main content

py2md

将源代码文件递归转换为结构化 Markdown 文档的命令行工具。

PyPI version Python Versions License: MIT

功能特性

  • 多文件类型支持: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

许可证

MIT License

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)

Source distribution for py2md-cli 0.2.0
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)

Table of built distributions (wheels) for py2md-cli 0.2.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page