企业官网建设流程全解析

• 网页爬虫
• 人工智能
• AI 应用

本篇技术指南围绕 Scrapegraph-ai 项目中的 Markdownify 功能展开：它是一套把任意 HTML 内容（无论是线上 URL 还是本地 HTML 片段）转换为干净、可读 Markdown 的图形化处理流程。读者读完本篇后，将掌握 Markdownify 的两种输入方式（website_url与html_content）的完整调用方法、响应结构、错误处理策略，并能通过源码理解其底层"抓取 + 转换"两节点流水线的实现原理，为后续将网页内容接入 LLM 预处理、RAG 文档清洗等场景打下基础。

功能特性一览

Markdownify Graph 的核心目标是把杂乱的 HTML 页面转化为结构清晰的 Markdown 文档，其特性包括：

• HTML 到 Markdown 转换：将 HTML 内容转换为干净、易读的 Markdown 格式；
• URL 与直接 HTML 双输入：既支持传入website_url抓取线上网页，也支持直接传入html_content字符串处理本地 HTML；
• 保持原有格式与结构：标题、段落、列表、链接、表格等结构信息在转换后得到保留；
• 处理复杂嵌套 HTML：对复杂 HTML 元素与嵌套结构具备容错能力，相关边界行为在仓库测试中有对应用例。

这些特性记录于官方示例文档 examples/markdownify/readme.md，同时可以在源码中找到完整实现支撑。

环境准备：确认依赖与日志系统

Markdownify 功能位于 Scrapegraph-ai 仓库内，底层转换依赖html2text库，云端调用则依赖scrapegraph-py客户端。在 pyproject.toml 中可以看到相关依赖声明：

• html2text>=2025.4.15：负责 HTML 到 Markdown 的实际转换；
• scrapegraph-py>=1.44.0：提供Client客户端封装（对应markdownify方法）。

在使用前，建议先通过仓库的 requirements.txt 或pip install -e .安装项目依赖。同时，Scrapegraph-ai 内置了统一的日志系统sgai_logger，通过如下代码即可开启 INFO 级别日志，便于观察转换过程中的执行细节：

from scrapegraphai.logger import sgai_logger sgai_logger.set_logging(level="INFO")

日志级别可根据调试需求调整为DEBUG、WARNING等。完整的示例脚本可参考 examples/markdownify/markdownify_scrapegraphai.py。

快速上手：Client 方式调用 markdownify

官方文档 examples/markdownify/readme.md 给出的标准用法是初始化Client后调用markdownify方法。以下为文档中的完整示例：

from scrapegraphai import Client from scrapegraphai.logger import sgai_logger # Set up logging sgai_logger.set_logging(level="INFO") # Initialize the client sgai_client = Client(api_key="your-api-key") # Example 1: Convert a website to Markdown response = sgai_client.markdownify( website_url="https://example.com" ) print(response.markdown) # Example 2: Convert HTML content directly html_content = """ <div> <h1>Hello World</h1> <p>This is a <strong>test</strong> paragraph.</p> </div> """ response = sgai_client.markdownify( html_content=html_content ) print(response.markdown)

值得注意的是，仓库中的实际可运行脚本 examples/markdownify/markdownify_scrapegraphai.py 提供了更贴近生产环境的写法：

• 使用from scrapegraph_py import Client导入客户端；
• 通过load_dotenv()加载环境变量，从SCRAPEGRAPH_API_KEY读取 API Key；
• 当环境中缺少 API Key 时主动抛出ValueError提示；
• 结果通过字典键访问：response["result"]获取 Markdown 内容，response.get("metadata", {})获取元数据。

import os from dotenv import load_dotenv from scrapegraph_py import Client from scrapegraph_py.logger import sgai_logger load_dotenv() sgai_logger.set_logging(level="INFO") api_key = os.getenv("SCRAPEGRAPH_API_KEY") if not api_key: raise ValueError("SCRAPEGRAPH_API_KEY environment variable not found") sgai_client = Client(api_key=api_key) response = sgai_client.markdownify( website_url="https://example.com" ) print(response["result"]) print(response.get("metadata", {}))

两种写法中，api_key都来源于你自己的服务密钥，请妥善保管。

参数说明

markdownify方法接受以下参数：

注意：website_url与html_content必须二选一提供，不可同时传入，也不可同时为空。从源码实现来看，这一约束与底层图结构的输入规范一致：MarkdownifyGraph 中FetchNode的输入表达式为"url \| html"，即它只从状态中读取url或html两个键之一，二者都存在或都不存在时都会导致输入键解析失败。

响应对象结构

markdownify返回的响应对象包含以下字段：

• markdown（str）：转换后的 Markdown 内容；
• metadata（dict）：关于转换过程的附加信息。

在字典风格的访问方式下，对应为response["result"]与response.get("metadata", {})。建议在业务代码中使用带默认值的get方法读取metadata，以兼容元数据缺失的场景。

源码级实现解析：两节点流水线

除了云端Client封装，本仓库还提供了可直接在本地使用的图实现MarkdownifyGraph（位于 scrapegraphai/graphs/markdownify_graph.py），其内部是一个标准的"抓取 → 转换"两节点流水线：

1. FetchNode（抓取节点）：输入规范为"url | html"，输出键为["html_content"]。当传入 URL 时，它负责抓取网页内容；当传入本地 HTML 字符串时，它直接透传内容。该节点在 scrapegraphai/nodes/fetch_node.py 中实现，支持多种抓取策略与配置。
2. MarkdownifyNode（转换节点）：输入规范为"html_content"，输出键为["markdown"]，执行时从状态中取出 HTML 内容，调用convert_to_md完成转换，并将结果写回状态的markdown键。其实现位于 scrapegraphai/nodes/markdownify_node.py。

图结构通过边(fetch_node, markdownify_node)串联，入口点为fetch_node，graph_name为"Markdownify"。直接使用本地图的方式如下（对应类 docstring 中的示例）：

graph = MarkdownifyGraph( llm_model=your_llm_model, embedder_model=your_embedder_model ) result, _ = graph.execute({"url": "https://example.com"}) print(result["markdown"])

从源码结构看，MarkdownifyGraph在部分场景中可能以 LLM 模型作为参数初始化，但 Markdownify 的核心转换逻辑本身不依赖 LLM 推理——真正完成 HTML→Markdown 转换的是html2text工具函数。

转换核心：convert_to_md 函数

MarkdownifyNode 的转换能力最终落在 scrapegraphai/utils/convert_to_md.py 中的convert_to_md函数。其实现要点如下：

def convert_to_md(html: str, url: str = None) -> str: h = html2text.HTML2Text() h.ignore_links = False h.body_width = 0 if url is not None: parsed_url = urlparse(url) domain = f"{parsed_url.scheme}://{parsed_url.netloc}" h.baseurl = domain return h.handle(html)

• ignore_links = False：保留链接，不会被丢弃；
• body_width = 0：关闭自动换行宽度限制，避免长段落被意外截断；
• 可选参数url：当传入来源 URL 时，函数会通过urlparse提取scheme://netloc作为baseurl，使 HTML 中的相对链接在转换后可以解析为完整地址；
• 该函数会忽略 HTML 中的样式（CSS）信息，仅保留内容结构。

该函数的正确性由 tests/utils/convert_to_md_test.py 中的测试用例验证，覆盖了：基础 HTML 转换、含链接与图片的 HTML、表格结构、空 HTML、复杂嵌套结构（标题、加粗、斜体、无序列表、链接）等场景，说明它在各类常见 HTML 结构下都能稳定产出非空 Markdown。

FetchNode 的关键配置项

当使用website_url输入时，抓取行为由 FetchNode 控制，scrapegraphai/nodes/fetch_node.py 中暴露了以下可配置项（通过node_config字典传入）：

这些配置让 Markdownify 在应对反爬、需要登录态、指定地区代理等复杂网页时依然可用。相关抓取器的实现可进一步参考 scrapegraphai/docloaders/chromium.py、scrapegraphai/docloaders/browser_base.py 与 scrapegraphai/docloaders/scrape_do.py。

错误处理与边界情况

Markdownify 流程会处理多种异常场景，官方文档列出的边界情况包括：

• 无效 URL：URL 格式错误或无法访问时，抓取阶段会失败并抛出相应异常；
• 格式错误的 HTML：HTML 解析异常时会被捕获并向上抛出；
• 网络错误：请求失败、DNS 解析失败等网络问题会被记录并抛出；
• 超时问题：超过timeout配置的时间限制时，会抛出超时异常。

从源码看，具体的错误行为包括：当抓取到的 HTML 内容为空或仅含空白时，FetchNode会抛出ValueError("No HTML body content found ...")；当状态中缺少必要的输入键（如html_content）时，MarkdownifyNode会抛出KeyError，其 docstring 明确说明了这一行为："If the input keys are not found in the state, indicating that the necessary HTML content is missing"。所有错误都会被日志系统记录，并以合适的错误消息向上层抛出，便于调用方捕获与处理。

最佳实践

结合官方文档建议与源码行为，在实际项目中使用 Markdownify 时可以参考以下实践：

1. 始终提供有效 URL 或格式良好的 HTML：这是转换成功的前提。对于html_content输入，建议先进行基本合法性校验，避免传入空字符串或残缺标签；
2. 善用日志级别调试：开发阶段使用INFO或DEBUG级别观察 FetchNode 与 MarkdownifyNode 的执行日志，生产环境可降低到WARNING减少日志噪音；
3. 正确处理响应：在应用层对markdown/result字段做空值判断，并使用get("metadata", {})的默认值方式读取元数据；
4. 大规摸转换时考虑限流：批量转换大量网页时，应对请求频率进行限流控制，避免触发目标站点或服务端的访问限制；
5. 优先使用website_url或html_content单一入口：严格遵循"二选一"的参数约束，并通过代码校验保证调用正确性；
6. 善用convert_to_md的url参数：在需要保留相对链接可解析性的场景（如抓取网页后转 Markdown 供 RAG 引用）时，传入来源 URL 以启用baseurl解析。

总结

Markdownify 是 Scrapegraph-ai 中一个轻量而实用的 HTML 清洗工具：通过Client.markdownify一行调用即可完成网页或 HTML 片段的 Markdown 化；在仓库内部，它由MarkdownifyGraph（FetchNode + MarkdownifyNode）与convert_to_md工具函数共同支撑，依赖成熟的html2text库，并有完整测试用例覆盖边界行为。无论是作为 LLM 前置的内容清洗步骤、RAG 文档预处理，还是日常的网页转笔记工具，Markdownify 都提供了简洁可靠的解决方案。更多相关实现可继续阅读 scrapegraphai/graphs/markdownify_graph.py、scrapegraphai/nodes/markdownify_node.py 与示例脚本 examples/markdownify/markdownify_scrapegraphai.py。

• 网页爬虫
• 人工智能
• AI 应用