yuzhi home page

墨探 (Omni-Article-Markdown) 使用文档

欢迎使用墨探！本指南将帮助你从基础安装到深度定制，全面掌握网页 Markdown 转换技巧。

1. 快速上手

环境要求

  • Python 3.10+
  • uv (推荐) 或 pip

安装

pip install omni-article-markdown

运行第一个转换

# 在终端输出转换结果
mdcli https://juejin.cn/post/7405845617282449462

# 转换并保存为当前目录下的 markdown 文件
mdcli https://juejin.cn/post/7405845617282449462 -s

2. CLI 参数详解

参数缩写描述示例
url-目标网页的 URL (必填)mdcli http://...
--save-s保存到文件（默认文件名基于标题）mdcli ... -s ./notes/
--help-h显示帮助信息mdcli --help

3. 核心架构说明

墨探遵循 Reader -> Extractor -> Parser 的处理流：

  • Reader: 负责网络请求。支持 Requests (简单) 和 Playwright (动态渲染)。
  • Extractor: 核心逻辑。通过 BeautifulSoup 识别正文标签、移除噪声。
  • Parser: 引擎层。将清理后的 HTML 转换为符合 GFM 规范的 Markdown。

4. 开发者指南：适配新站点

如果你发现某个站点的解析效果不理想，可以轻松增加自定义 Extractor。

  1. 创建文件：在 src/omni_article_markdown/extractors/ 目录下创建 your_site.py。
  2. 实现类：继承自基础类并重写 extract 方法。
  3. 注册：在 ExtractorFactory 中关联域名。

详细步骤请参考：开发者手册

5. 常见问题 (FAQ)

Q: 为什么某些页面转换出来不正确？
A: 可能是该页面未做适配，请前往 GitHub Issues 提交 issue。

Q: 如何处理需要登录的文章？
A: 墨探目前主要针对公开文章。对于私有内容，原则上不会强制适配。

Q: 如何处理需要人机验证后才能阅读的文章？
A: 墨探内置了简单的反防爬策略，但是原则上不会强制适配。

🤝 贡献

发现 bug 或有功能建议？请前往 GitHub Issues 提交。