magiclens 0.1.0

强大的网页解析引擎，可以从HTML中提取结构化数据

MagicLens

MagicLens 是一个强大而灵活的HTML到Markdown转换工具，它使用可扩展的规则系统，能够准确地将HTML文档转换为Markdown格式。

名称寓意

MagicLens（神奇透镜）的名称灵感来源于透镜能够聚焦、放大并清晰呈现物体本质的特性。就像一个魔法透镜可以将复杂的事物简化并呈现其本质一样，我们的工具可以将复杂的HTML结构"透视"并转换为简洁清晰的Markdown格式。这个过程就像是通过一个神奇的透镜，让文档内容保持原貌，只是以一种更加简洁、可读性更强的方式呈现。"神奇透镜"不仅能看透HTML的复杂结构，还能智能地解析和转换各种元素，确保转换后的Markdown保留原始内容的精髓和格式，使得内容创作者可以专注于内容本身，而不是被复杂的标记语言所困扰。

特性

• 高质量的HTML到Markdown转换
• 支持所有标准HTML元素
• 基于规则的转换系统，易于扩展和自定义
• 提供多种转换选项，适应不同格式需求
• 默认支持GitHub风格Markdown (GFM)
• 支持HTML片段和自定义转换规则
• 支持从文件、URL或字符串中转换HTML
• 简单易用的命令行工具
• Python API，方便集成到其他应用中

安装

使用pip安装（推荐）

pip install magiclens

从源码安装

git clone https://github.com/magiclens/magiclens.git
cd magiclens
pip install -e .

快速入门

命令行使用

MagicLens 提供了一个简单的命令行工具：

# 从HTML文件转换
magiclens -f input.html -o output.md

# 从URL转换
magiclens -u https://example.com -o example.md

# 从字符串转换
magiclens -s "<h1>标题</h1><p>段落</p>" -o output.md

# 显示帮助信息
magiclens --help

Python API使用

from magiclens.converters import Html2MarkdownConverter

# 创建转换器
converter = Html2MarkdownConverter()

# 从HTML字符串转换
html = "<h1>标题</h1><p>这是一个<strong>示例</strong>。</p>"
markdown = converter.convert_html(html)
print(markdown)

# 从URL转换
url_markdown = converter.convert_url("https://example.com")
print(url_markdown)

# 使用自定义选项
options = {
    "headingStyle": "atx",      # setext 或 atx
    "bulletListMarker": "-",    # *, -, 或 +
    "codeBlockStyle": "fenced", # fenced 或 indented
    "emDelimiter": "*",         # * 或 _
    "strongDelimiter": "**"     # ** 或 __
}
custom_converter = Html2MarkdownConverter(options=options)
custom_markdown = custom_converter.convert_html(html)
print(custom_markdown)

# 转换HTML片段
fragment = "<li>列表项1</li><li>列表项2</li>"
markdown = converter.convert_html_fragment(fragment)
print(markdown)

更多示例，请查看 examples 目录。

转换选项

MagicLens 支持多种转换选项，可以通过命令行参数或API选项进行设置：

选项名	可选值	默认值	描述
dialect	"github", "commonmark", "traditional", "custom"	"github"	Markdown方言类型
headingStyle	"atx", "setext"	"atx"	标题样式 (# 或 ====)
bulletListMarker	"*", "-", "+"	"-"	无序列表标记
codeBlockStyle	"fenced", "indented"	"fenced"	代码块样式 (``` 或缩进)
fence	"```", "~~~"	"```"	代码块围栏标记
emDelimiter	"*", "_"	"*"	斜体分隔符
strongDelimiter	"**", "__"	"**"	粗体分隔符
linkStyle	"inlined", "referenced"	"inlined"	链接样式（内联或引用）
linkReferenceStyle	"full", "collapsed", "shortcut"	"full"	引用链接样式
convertImages	Boolean	true	是否转换图片

Markdown方言支持

MagicLens默认使用GitHub风格Markdown（GFM），这是目前最广泛使用的Markdown方言。

GitHub风格Markdown (GFM)

GitHub风格Markdown是本工具的默认方言，支持表格、任务列表、删除线等扩展特性：

• 任务列表 (- [x] 和 - [ ])
• 表格支持
• 删除线 (~~文本~~)
• 自动链接
• ATX风格标题 (# 标题)
• 围栏式代码块 (```)

# 默认已使用GitHub风格
converter = Html2MarkdownConverter()

# 或明确指定
converter = Html2MarkdownConverter(options={"dialect": "github"})

MagicLens还支持其他方言如CommonMark和传统Markdown，但我们推荐使用GFM以获得最佳体验和最广泛的兼容性。

项目结构

magiclens/
├── src/
│   └── magiclens/
│       ├── converters/    # 转换器实现
│       │   ├── __init__.py
│       │   ├── base.py
│       │   └── html2md.py
│       ├── rules/         # 转换规则
│       │   ├── __init__.py
│       │   ├── base.py
│       │   └── html2md.py
│       ├── __init__.py
│       ├── __main__.py
│       └── cli.py         # 命令行接口
├── tests/                 # 测试代码
├── examples/              # 使用示例
├── setup.py               # 安装配置
└── README.md              # 项目文档

贡献指南

我们欢迎各种形式的贡献，包括但不限于：

• 报告问题和错误
• 提出新功能建议
• 改进文档
• 提交代码修复或新功能

贡献步骤

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加一些令人惊叹的功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建Pull Request

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

联系我们

• 项目维护者: MagicLens Team
• 电子邮件: [e-mail]
• GitHub Issues: 提交问题

---

Made with ❤️ by MagicLens Team