py2md

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

功能特性

• 多文件类型支持：Python、HTML、CSS、JavaScript、Vue、TypeScript、JSON、XML、YAML
• 递归扫描：自动遍历目标目录下所有匹配文件（支持自定义扩展名）
• 保留层级：输出 Markdown 中完整保留文件的目录结构路径
• 灵活配置：支持自定义编码、排除隐藏文件、多扩展名过滤等选项
• 友好 CLI：基于 Typer 的命令行接口，支持彩色输出和详细统计
• 类型安全：全面使用 Type Hints，提供 py.typed 标记文件
• 向后兼容：保留原有 py_to_markdown 和 html_to_markdown 接口

支持的文件类型

安装

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

命令行参数

输出示例

生成的 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