MarkGrab

MarkGrab

韩语文档 · llms.txt

通用网页内容提取工具——将任意 URL 转换为适用于大模型的 Markdown。

from markgrab import extract

result = await extract("https://example.com/article")
print(result.markdown)    # clean markdown
print(result.title)       # "Article Title"
print(result.word_count)  # 1234
print(result.language)    # "en"

功能

• HTML — 使用 BeautifulSoup 和内容密度过滤（移除导航栏、侧边栏和广告）
• YouTube — 提取带时间戳的转录文本
• PDF — 提取文本并保留页面结构
• DOCX — 提取段落和标题
• 自动回退 — 首先尝试轻量级 httpx，遇到 JavaScript 密集型页面时则回退到 Playwright
• 异步优先 — 基于 httpx 和 Playwright 的异步 API 构建

安装

pip install markgrab

特定内容类型的可选扩展：

pip install "markgrab[browser]"    # Playwright for JS-rendered pages
pip install "markgrab[youtube]"    # YouTube transcript extraction
pip install "markgrab[pdf]"       # PDF text extraction
pip install "markgrab[docx]"      # DOCX text extraction
pip install "markgrab[all]"       # everything

使用方法

Python API

import asyncio
from markgrab import extract

async def main():
    # HTML (auto-detects content type)
    result = await extract("https://example.com/article")

    # YouTube transcript
    result = await extract("https://youtube.com/watch?v=dQw4w9WgXcQ")

    # PDF
    result = await extract("https://arxiv.org/pdf/1706.03762")

    # Options
    result = await extract(
        "https://example.com",
        max_chars=30_000,       # limit output length (default: 50K)
        use_browser=True,       # force Playwright rendering
        stealth=True,           # anti-bot stealth scripts (opt-in)
        timeout=60.0,           # request timeout in seconds
        proxy="http://proxy:8080",
    )

asyncio.run(main())

CLI

markgrab https://example.com                     # markdown output
markgrab https://example.com -f text             # plain text
markgrab https://example.com -f json             # structured JSON
markgrab https://example.com --browser           # force browser rendering
markgrab https://example.com --max-chars 10000   # limit output

ExtractResult

result.title        # page title
result.text         # plain text
result.markdown     # LLM-ready markdown
result.word_count   # word count
result.language     # detected language ("en", "ko", ...)
result.content_type # "article", "video", "pdf", "docx"
result.source_url   # final URL (after redirects)
result.metadata     # extra metadata (video_id, page_count, etc.)

工作原理

flowchart TD
    A["🔗 URL Input"] --> B{"Content\nType?"}
    B -->|"HTML"| C["HTTP fetch\n(httpx)"]
    C --> D{"JS\nrequired?"}
    D -->|"no"| E["HTML Parser\n→ clean markdown"]
    D -->|"yes"| F["Playwright\nfallback"]
    F --> E
    B -->|"YouTube"| G["Transcript API\n→ timestamped markdown"]
    B -->|"PDF"| H["PDF Parser\n→ structured markdown"]
    B -->|"DOCX"| I["DOCX Parser\n→ markdown"]
    E --> J["✅ LLM-ready\nMarkdown"]
    G --> J
    H --> J
    I --> J

对于 HTML 页面，如果初次使用 httpx 获取的内容少于 50 个单词，MarkGrab 会自动使用 Playwright 重试，以处理由 JavaScript 渲染的内容。

免责声明

本软件仅供合法用途使用。 使用 MarkGrab 即表示您同意以下条款：

• robots.txt：MarkGrab 不会检查或强制执行 robots.txt。用户须自行负责检查并遵守 robots.txt 指令以及所访问网站的服务条款。

• 速率限制：MarkGrab 不包含内置的速率限制或请求节流功能。用户必须自行实施速率限制，以避免目标服务过载。滥用请求可能违反适用法律和网站服务条款。

• YouTube 转录文本：YouTube 转录文本提取依赖第三方 youtube-transcript-api 库，该库使用 YouTube 的内部（非官方）字幕 API。这可能不符合 YouTube 服务条款。使用此功能的后果和风险由您自行承担。

• 隐身模式：可选的 stealth=True 功能会修改浏览器指纹信号，以降低被检测为机器人的概率。此功能适用于测试、研究以及访问普通浏览器用户可公开访问的内容等正当用途。用户须自行负责确保其使用行为符合适用法律和目标网站的服务条款。

• 法律合规：用户须自行负责确保其对 MarkGrab 的使用符合所有适用法律，包括但不限于《计算机欺诈和滥用法案》（CFAA）、《数字千年版权法》（DMCA）、GDPR 以及所在司法辖区的同等法律。

本软件按“原样”提供，不提供任何形式的保证。完整的 MIT 许可证文本请参阅 LICENSE 文件。

致谢

MarkGrab 建立在优秀的开源项目和成熟技术之上：

• puppeteer-extra-plugin-stealth — 隐蔽规避模式（移除 webdriver、模拟插件、伪造 WebGL）启发了可选的 anti_bot/stealth.py 模块
• Mozilla Readability — 内容区域检测优先级（article > main > body）和链接密度过滤理念，用于密度过滤器
• Boilerpipe（Kohlschutter 等人，2010 年）— 用于移除模板内容的链接密度比算法的学术起源
• Jina Reader — 验证了市场对 URL 转 Markdown 提取的需求；MarkGrab 致力于成为轻量级、可自托管的替代方案

基于 httpx、BeautifulSoup、markdownify、Playwright、youtube-transcript-api、pdfplumber 和 python-docx 构建。

使用方

• newswatch — RSS 新闻监控流水线（feedkit → markgrab → embgrep → diffgrab）
• watchdeck — 带有视觉差异对比和安全防护的网页监控

许可证

MIT

---

_{属于 QuartzUnit 生态系统 — 用于数据收集、提取、搜索和 AI Agent 安全防护的可组合 Python 库。}