omni-article-markdown 0.1.0__tar.gz

omni_article_markdown-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.DS_STORE
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env

omni_article_markdown-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 caol64
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omni_article_markdown-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: omni-article-markdown
+Version: 0.1.0
+Summary: Easily convert web articles (blogs, news, documents, etc.) into Markdown format.
+Project-URL: Homepage, https://github.com/caol64/omni-article-markdown
+Author-email: Lei <caol64@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Requires-Dist: beautifulsoup4>=4.13.4
+Requires-Dist: click-default-group>=1.2.4
+Requires-Dist: click>=8.2.0
+Requires-Dist: html5lib>=1.1
+Requires-Dist: pip
+Requires-Dist: pluggy>=1.6.0
+Requires-Dist: requests>=2.32.3
+Description-Content-Type: text/markdown
+
+# 墨探 (omni-article-markdown)
+
+轻松将网页文章（博客、新闻、文档等）转换为 `Markdown` 格式。
+
+![](data/1.gif)
+
+---
+
+## Recent changes:
+
+- 添加插件机制，复杂的页面可以通过插件进行扩展
+- 添加对github gist的支持
+  - 示例：https://towardsdatascience.com/hands-on-multi-agent-llm-restaurant-simulation-with-python-and-openai
+- 添加对katex公式的支持
+  - 示例：https://quantum.country/qcvc
+
+---
+
+## 1. 功能介绍
+墨探的开发初衷，是为了解决一个问题：如何将来自互联网上各种不同网站的文章内容，精准且高效地转换成统一的Markdown格式。
+
+众所周知，万维网上的网站设计风格迥异，其HTML结构也呈现出千差万别的特点。这种多样性给自动化内容提取和格式转换带来了巨大的困难。要实现一个能够适应各种复杂HTML结构的通用解决方案，并非易事。
+
+我的想法是：从特定的网站开始适配，以点到面，逐步抽取出通用的解决方案，最后尽可能多的覆盖更多网站。以下是一些我经常访问的的网站，支持的都不错：
+
+- 掘金
+- CSDN
+- Medium
+- Freedium
+- 公众号
+- 简书
+- 知乎专栏
+- 今日头条
+- towardsdatascience
+- quantamagazine
+
+只需要一条命令：
+
+```sh
+mdcli https://example.com
+```
+
+你还可以将网页手动保存为 HTML 文件，再使用本工具解析，也是支持的。
+
+```sh
+mdcli your/path/example.html
+```
+
+---
+
+## 2. 安装与运行
+
+首先，安装必要依赖项：
+```sh
+uv pip install .
+```
+
+然后，可以使用以下两种形式运行：
+```sh
+uv run mdcli
+```
+
+或者：
+
+```sh
+python -m omni_article_markdown.cli
+```
+
+---
+
+## 3. 参数说明
+
+运行命令及参数如下：
+
+```sh
+mdcli <URL_OR_PATH> [-s [SAVE_PATH]]
+```
+
+| 参数               | 说明 |
+|--------------------|------|
+| `URL_OR_PATH`     | **必填**，目标网页 URL 或本地 HTML 文件路径。 |
+| `-s, --save`      | **可选**，启用保存：<br> - 仅 `-s`：默认保存至 `./`。<br> - `-s <SAVE_PATH>`：保存至指定路径。 |
+
+---
+
+## 4. 使用示例
+
+### 4.1 仅转换
+```sh
+mdcli https://example.com
+```
+
+内容会输出值`stdout`。
+
+### 4.2 转换并保存到当前目录
+
+```sh
+mdcli https://example.com -s
+```
+
+会在当前目录生成一个`<title>.md`的文件。
+
+### 4.3 转换并保存到指定路径
+
+```sh
+mdcli https://example.com -s /home/user/
+```
+
+会在`/home/user/`目录生成一个`<title>.md`的文件。
+
+```sh
+mdcli https://example.com -s /home/user/data.md
+```
+
+会生成一个`/home/user/data.md`的文件。
+
+---
+
+## 5. 安装和使用插件
+
+墨探支持通过插件机制来扩展自身的能力。这使得社区可以贡献针对不同网站的定制化解析器，而无需修改核心代码。
+
+### 5.1 什么是插件？
+
+插件是独立的 Python 包，它们实现了墨探定义的特定接口（钩子），从而能够被主程序发现和调用。例如，一个插件可以提供一个专门用于解析知乎专栏文章的 `Reader`。插件往往需要安装额外的依赖，因此不包含在主程序中，有需要的用户可自行安装。
+
+### 5.2 如何安装插件？
+
+你可以使用 `mdcli` 提供的 `install` 命令来安装插件。插件通常会发布到 PyPI（Python Package Index）。
+
+**安装命令格式：**
+
+```sh
+mdcli install <PLUGIN_NAME_OR_PACKAGE_NAME> [-U] [-e]
+```
+
+| 参数                             | 说明                                                                 |
+|----------------------------------|----------------------------------------------------------------------|
+| `<PLUGIN_NAME_OR_PACKAGE_NAME>` | **必填**，插件的名称或其在 PyPI 上的完整包名。 |
+| `-U, --upgrade`                  | **可选**，如果插件已安装，则尝试升级到最新版本。                          |
+| `-e, --editable`                  | **可选**，基于提供的本地文件路径安装可编辑的包。                          |
+
+**示例：安装知乎解析插件**
+
+```sh
+mdcli install zhihu
+```
+
+或者，你可以使用 `-e` 参数安装本地可编辑的包。
+
+```sh
+mdcli install -e "./plugins/omnimd-zhihu-reader"
+```
+
+安装成功后，当下一次运行 `mdcli` 解析知乎链接时，如果该插件正确实现了接口，它将被自动用于处理该链接。
+
+### 5.3 如何卸载插件？
+
+如果你想移除一个已安装的插件，可以使用 `mdcli` 提供的 `uninstall` 命令。
+
+**卸载命令格式：**
+
+```sh
+mdcli uninstall <PLUGIN_NAME_OR_PACKAGE_NAME> [-y]
+```
+
+| 参数                             | 说明                                                     |
+|----------------------------------|----------------------------------------------------------|
+| `<PLUGIN_NAME_OR_PACKAGE_NAME>` | **必填**，要卸载的插件的名称或其在 PyPI 上的完整包名。 |
+| `-y, --yes`                      | **可选**，在卸载前不进行确认提示。                         |
+
+**示例：卸载知乎解析插件**
+
+```sh
+mdcli uninstall zhihu
+```
+
+或者，使用插件的全称删除
+
+```sh
+mdcli uninstall omnimd-zhihu-reader
+```
+
+卸载后，该插件的功能将不再可用。对于之前由该插件处理的 URL，`mdcli` 将会回退到其默认的解析逻辑。
+
+### 5.4 已支持的插件
+
+目前已发布3个插件，你可以按需安装：
+
+| 命令                             | 说明                                                     |
+|----------------------------------|----------------------------------------------------------|
+| `mdcli install zhihu`              | 知乎专栏 |
+| `mdcli install toutiao`            | 今日头条                         |
+| `mdcli install freedium`           | Freedium                         |
+
+### 5.5 开发自己的插件
+
+---
+
+## 6. 贡献与反馈
+- 发现解析问题？欢迎提交 [Issue](https://github.com/caol64/omni-article-markdown/issues)
+- 改进解析？欢迎贡献 [Pull Request](https://github.com/caol64/omni-article-markdown/pulls)
+- 开发插件？文档正在筹备中
+
+---
+
+## 7. 赞助
+
+如果您觉得不错，可以给我家猫咪买点罐头吃。[喂猫❤️](https://yuzhi.tech/sponsor)
+
+---
+
+## 8. License
+
+MIT License

omni_article_markdown-0.1.0/README.md

@@ -0,0 +1,215 @@
+# 墨探 (omni-article-markdown)
+
+轻松将网页文章（博客、新闻、文档等）转换为 `Markdown` 格式。
+
+![](data/1.gif)
+
+---
+
+## Recent changes:
+
+- 添加插件机制，复杂的页面可以通过插件进行扩展
+- 添加对github gist的支持
+  - 示例：https://towardsdatascience.com/hands-on-multi-agent-llm-restaurant-simulation-with-python-and-openai
+- 添加对katex公式的支持
+  - 示例：https://quantum.country/qcvc
+
+---
+
+## 1. 功能介绍
+墨探的开发初衷，是为了解决一个问题：如何将来自互联网上各种不同网站的文章内容，精准且高效地转换成统一的Markdown格式。
+
+众所周知，万维网上的网站设计风格迥异，其HTML结构也呈现出千差万别的特点。这种多样性给自动化内容提取和格式转换带来了巨大的困难。要实现一个能够适应各种复杂HTML结构的通用解决方案，并非易事。
+
+我的想法是：从特定的网站开始适配，以点到面，逐步抽取出通用的解决方案，最后尽可能多的覆盖更多网站。以下是一些我经常访问的的网站，支持的都不错：
+
+- 掘金
+- CSDN
+- Medium
+- Freedium
+- 公众号
+- 简书
+- 知乎专栏
+- 今日头条
+- towardsdatascience
+- quantamagazine
+
+只需要一条命令：
+
+```sh
+mdcli https://example.com
+```
+
+你还可以将网页手动保存为 HTML 文件，再使用本工具解析，也是支持的。
+
+```sh
+mdcli your/path/example.html
+```
+
+---
+
+## 2. 安装与运行
+
+首先，安装必要依赖项：
+```sh
+uv pip install .
+```
+
+然后，可以使用以下两种形式运行：
+```sh
+uv run mdcli
+```
+
+或者：
+
+```sh
+python -m omni_article_markdown.cli
+```
+
+---
+
+## 3. 参数说明
+
+运行命令及参数如下：
+
+```sh
+mdcli <URL_OR_PATH> [-s [SAVE_PATH]]
+```
+
+| 参数               | 说明 |
+|--------------------|------|
+| `URL_OR_PATH`     | **必填**，目标网页 URL 或本地 HTML 文件路径。 |
+| `-s, --save`      | **可选**，启用保存：<br> - 仅 `-s`：默认保存至 `./`。<br> - `-s <SAVE_PATH>`：保存至指定路径。 |
+
+---
+
+## 4. 使用示例
+
+### 4.1 仅转换
+```sh
+mdcli https://example.com
+```
+
+内容会输出值`stdout`。
+
+### 4.2 转换并保存到当前目录
+
+```sh
+mdcli https://example.com -s
+```
+
+会在当前目录生成一个`<title>.md`的文件。
+
+### 4.3 转换并保存到指定路径
+
+```sh
+mdcli https://example.com -s /home/user/
+```
+
+会在`/home/user/`目录生成一个`<title>.md`的文件。
+
+```sh
+mdcli https://example.com -s /home/user/data.md
+```
+
+会生成一个`/home/user/data.md`的文件。
+
+---
+
+## 5. 安装和使用插件
+
+墨探支持通过插件机制来扩展自身的能力。这使得社区可以贡献针对不同网站的定制化解析器，而无需修改核心代码。
+
+### 5.1 什么是插件？
+
+插件是独立的 Python 包，它们实现了墨探定义的特定接口（钩子），从而能够被主程序发现和调用。例如，一个插件可以提供一个专门用于解析知乎专栏文章的 `Reader`。插件往往需要安装额外的依赖，因此不包含在主程序中，有需要的用户可自行安装。
+
+### 5.2 如何安装插件？
+
+你可以使用 `mdcli` 提供的 `install` 命令来安装插件。插件通常会发布到 PyPI（Python Package Index）。
+
+**安装命令格式：**
+
+```sh
+mdcli install <PLUGIN_NAME_OR_PACKAGE_NAME> [-U] [-e]
+```
+
+| 参数                             | 说明                                                                 |
+|----------------------------------|----------------------------------------------------------------------|
+| `<PLUGIN_NAME_OR_PACKAGE_NAME>` | **必填**，插件的名称或其在 PyPI 上的完整包名。 |
+| `-U, --upgrade`                  | **可选**，如果插件已安装，则尝试升级到最新版本。                          |
+| `-e, --editable`                  | **可选**，基于提供的本地文件路径安装可编辑的包。                          |
+
+**示例：安装知乎解析插件**
+
+```sh
+mdcli install zhihu
+```
+
+或者，你可以使用 `-e` 参数安装本地可编辑的包。
+
+```sh
+mdcli install -e "./plugins/omnimd-zhihu-reader"
+```
+
+安装成功后，当下一次运行 `mdcli` 解析知乎链接时，如果该插件正确实现了接口，它将被自动用于处理该链接。
+
+### 5.3 如何卸载插件？
+
+如果你想移除一个已安装的插件，可以使用 `mdcli` 提供的 `uninstall` 命令。
+
+**卸载命令格式：**
+
+```sh
+mdcli uninstall <PLUGIN_NAME_OR_PACKAGE_NAME> [-y]
+```
+
+| 参数                             | 说明                                                     |
+|----------------------------------|----------------------------------------------------------|
+| `<PLUGIN_NAME_OR_PACKAGE_NAME>` | **必填**，要卸载的插件的名称或其在 PyPI 上的完整包名。 |
+| `-y, --yes`                      | **可选**，在卸载前不进行确认提示。                         |
+
+**示例：卸载知乎解析插件**
+
+```sh
+mdcli uninstall zhihu
+```
+
+或者，使用插件的全称删除
+
+```sh
+mdcli uninstall omnimd-zhihu-reader
+```
+
+卸载后，该插件的功能将不再可用。对于之前由该插件处理的 URL，`mdcli` 将会回退到其默认的解析逻辑。
+
+### 5.4 已支持的插件
+
+目前已发布3个插件，你可以按需安装：
+
+| 命令                             | 说明                                                     |
+|----------------------------------|----------------------------------------------------------|
+| `mdcli install zhihu`              | 知乎专栏 |
+| `mdcli install toutiao`            | 今日头条                         |
+| `mdcli install freedium`           | Freedium                         |
+
+### 5.5 开发自己的插件
+
+---
+
+## 6. 贡献与反馈
+- 发现解析问题？欢迎提交 [Issue](https://github.com/caol64/omni-article-markdown/issues)
+- 改进解析？欢迎贡献 [Pull Request](https://github.com/caol64/omni-article-markdown/pulls)
+- 开发插件？文档正在筹备中
+
+---
+
+## 7. 赞助
+
+如果您觉得不错，可以给我家猫咪买点罐头吃。[喂猫❤️](https://yuzhi.tech/sponsor)
+
+---
+
+## 8. License
+
+MIT License

omni_article_markdown-0.1.0/omni_article_markdown/__init__.py

@@ -0,0 +1,9 @@
+from .omni_article_md import OmniArticleMarkdown
+
+__all__ = ['OmniArticleMarkdown']
+
+DEFAULT_PLUGINS = {
+    "zhihu": "omnimd-zhihu-reader",
+    "freedium": "omnimd-freedium-reader",
+    "toutiao": "omnimd-toutiao-reader",
+}

omni_article_markdown-0.1.0/omni_article_markdown/cli.py

@@ -0,0 +1,105 @@
+import click
+import sys
+from runpy import run_module
+from click_default_group import DefaultGroup
+
+from .omni_article_md import OmniArticleMarkdown
+from . import DEFAULT_PLUGINS
+
+@click.group(cls=DefaultGroup, default='parse', default_if_no_args=True)
+def cli():
+    """
+    A CLI tool to parse articles and save them as Markdown.
+    It also supports installing plugins.
+    """
+    pass
+
+@cli.command(name="parse")
+@click.argument("url_or_path")
+@click.option(
+    "-s", "--save",
+    default=None,
+    help="Save result (default: ./). Provide a path to save elsewhere.",
+    is_flag=False,
+    flag_value="./"
+)
+def parse_article(url_or_path, save):
+    """
+    Parses an article from a URL or local path and outputs/saves it as Markdown.
+    """
+    handler = OmniArticleMarkdown(url_or_path)
+    article = handler.parse()
+
+    if save is None:
+        click.echo(article)
+    else:
+        handler.save(save)
+        click.echo(f"Article saved to: {handler.save_path}")
+
+@cli.command()
+@click.argument("plugin_name")
+@click.option(
+    "-U", "--upgrade", is_flag=True, help="Upgrade the plugin if already installed."
+)
+@click.option(
+    "-e", "--editable", is_flag=True, help="Install the editable package based on the provided local file path"
+)
+def install(plugin_name, upgrade, editable):
+    """
+    Installs a plugin for this application.
+    For example, to install the 'zhihu' plugin: mdcli install zhihu
+    """
+    actual_package_name = plugin_name if editable or plugin_name not in DEFAULT_PLUGINS else DEFAULT_PLUGINS[plugin_name]
+
+    click.echo(f"Attempting to install plugin: {actual_package_name}...")
+    args = ["pip", "install"]
+    if upgrade:
+        args.append("--upgrade")
+    args.append(actual_package_name)
+
+    original_argv = sys.argv
+    try:
+        sys.argv = args
+        run_module("pip", run_name="__main__")
+        click.echo(f"Plugin '{actual_package_name}' processed by pip.")
+        click.echo("If the plugin provides new functionality, it should now be available.")
+        click.echo("You might need to restart the application for changes to take full effect if it involves runtime loading during startup.")
+    except Exception as e:
+        click.echo(f"Failed to process plugin '{actual_package_name}' with pip: {e}", err=True)
+        click.echo("Please ensure pip is installed and the package name is correct.", err=True)
+    finally:
+        sys.argv = original_argv
+
+@cli.command()
+@click.argument("plugin_name")
+@click.option(
+    "-y", "--yes", is_flag=True, help="Don't ask for confirmation before uninstalling."
+)
+def uninstall(plugin_name, yes):
+    """
+    Uninstalls a plugin for this application.
+    For example, to uninstall the 'zhihu' plugin: mdcli uninstall zhihu
+    """
+    actual_package_name = plugin_name if plugin_name not in DEFAULT_PLUGINS else DEFAULT_PLUGINS[plugin_name]
+
+    click.echo(f"Attempting to uninstall plugin: {actual_package_name}...")
+    args = ["pip", "uninstall"]
+    if yes:
+        args.append("-y")
+    args.append(actual_package_name)
+
+    original_argv = sys.argv
+    try:
+        sys.argv = args
+        run_module("pip", run_name="__main__")
+        click.echo(f"Plugin '{actual_package_name}' uninstallation processed by pip.")
+        click.echo("The plugin's functionality should no longer be available after the next application start (or if dynamically unloaded).")
+    except Exception as e:
+        click.echo(f"Failed to process uninstallation of plugin '{actual_package_name}' with pip: {e}", err=True)
+        click.echo("Please ensure pip is installed and the package name is correct.", err=True)
+    finally:
+        sys.argv = original_argv
+
+
+if __name__ == "__main__":
+    cli()

omni_article_markdown-0.1.0/omni_article_markdown/hookspecs.py

@@ -0,0 +1,22 @@
+from pluggy import HookimplMarker, HookspecMarker
+from typing import Optional, Protocol
+
+
+hookspec = HookspecMarker("mdcli")
+hookimpl = HookimplMarker("mdcli")
+
+class ReaderPlugin(Protocol):
+    def can_handle(self, url: str) -> bool:
+        ...
+
+    def read(self, url: str) -> str:
+        ...
+
+
+@hookspec(firstresult=True)
+def get_custom_reader(url: str) -> Optional[ReaderPlugin]:
+    """
+    Allows plugins to provide a custom reader for a given URL.
+    The first plugin that returns a ReaderPlugin instance will be used.
+    """
+    ...