Back to Details

doc-reader

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Read documentation effectively

高效阅读文档

This skill helps you efficiently consume documentation without overwhelming your context window or missing important information.
本技能可帮助你高效获取文档信息，避免上下文窗口过载或遗漏重要内容。

Quick reference: choose your approach

快速参考：选择合适的方法

SituationApproach
First visit to a doc siteCheck for llms.txt, then MCP
Know exactly what you're looking forMCP search or grep llms-full.txt
Need to read a specific pageTry 
.md
URL variant first, then HTML
Exploring/browsingView HTML page in browser
Need comprehensive understandingLoad llms-full.txt (check length first)
Multiple doc sites in one taskSet up MCPs for each
场景方法
首次访问文档站点先查找llms.txt，再尝试MCP
明确知道要查找的内容使用MCP搜索或grep查询llms-full.txt
需要阅读特定页面优先尝试
.md
格式的URL变体，再尝试HTML格式
探索/浏览文档在浏览器中查看HTML页面
需要全面理解内容加载llms-full.txt（先检查文件长度）
同一任务涉及多个文档站点为每个站点配置MCP

Step 1: Discover what's available

步骤1：了解可用资源

When you encounter a documentation site, check for AI-friendly resources.
当你遇到一个文档站点时，先查找对AI友好的资源。

Check for llms.txt

查找llms.txt

Every well-structured doc site should have an llms.txt file at the root. For example 
https://docs.example.com/llms.txt
or 
https://example.com/docs/llms.txt
.
This file contains:
  • A description of what the documentation covers
  • Links to each page in the docs
Sites may also have llms-full.txt files at the root which contain all the content on the documentation site as a single .md file.
结构完善的文档站点应在根目录下包含llms.txt文件，例如
https://docs.example.com/llms.txt
或
https://example.com/docs/llms.txt
。
该文件包含：
  • 文档覆盖范围的描述
  • 文档中各页面的链接
部分站点还会在根目录提供llms-full.txt文件，该文件将整个文档站点的内容整合为单个.md文件。

Try markdown URL variants

尝试Markdown格式的URL变体

Many doc sites serve clean markdown versions of pages at 
.md
URL variants. Prefer the 
.md
URL extensions for easier-to-parse content.
For any specific page you need to read, try the 
.md
variant first:
https://docs.example.com/page      →  try https://docs.example.com/page.md
If it returns valid markdown (not a 404 or HTML error page), use that instead of fetching the HTML.
许多文档站点会在
.md
格式的URL变体中提供简洁的Markdown版本页面。优先选择
.md
格式的URL，以便更易解析内容。
对于需要阅读的特定页面，先尝试
.md
变体：
https://docs.example.com/page      →  尝试 https://docs.example.com/page.md
如果返回有效的Markdown内容（而非404或HTML错误页面），则使用该版本，而非获取HTML页面。

Check for skill.md

查找skill.md

Some documentation sites provide a skill.md file that teaches you how to work with the product that is documented. Check for it at the root like 
https://docs.example.com/skill.md
or 
https://example.com/docs/skill.md
.
Read the skill to understand the product and features. Add the skill if it will be helpful with your current task:
bash
npx skills add docs.example.com/skill.md
部分文档站点会提供skill.md文件，指导你如何使用文档所介绍的产品。在根目录查找该文件，例如
https://docs.example.com/skill.md
或
https://example.com/docs/skill.md
。
阅读该技能文档以了解产品和功能。如果它对当前任务有帮助，可添加该技能：
bash
npx skills add docs.example.com/skill.md

Check for MCP server

查找MCP服务器

Some documentation sites provide MCP servers for semantic search. The MCP endpoint often follows this pattern:
https://docs.example.com/mcp
部分文档站点会提供用于语义搜索的MCP服务器。MCP端点通常遵循以下格式：
https://docs.example.com/mcp

Step 2: Set up MCP if available

步骤2：若可用则配置MCP

MCP (Model Context Protocol) servers let you search documentation semantically rather than relying on keyword matching or loading entire files.
MCP（Model Context Protocol，模型上下文协议）服务器允许你通过语义搜索文档，而非依赖关键词匹配或加载整个文件。

Connecting to the MCP

连接到MCP

The setup process varies by platform. For Claude Code:
json
{
  "mcpServers": {
    "example-docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp"
    }
  }
}
Once connected, you'll have access to the search tool for semantic search across the documentation. The tool follows the naming pattern 
Search{DocsTitle}
(for example, 
SearchMintlify
).
配置流程因平台而异。对于Claude Code：
json
{
  "mcpServers": {
    "example-docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp"
    }
  }
}
连接成功后，你将可使用搜索工具对文档进行语义搜索。工具命名遵循
Search{DocsTitle}
模式（例如
SearchMintlify
）。

Managing multiple MCPs

管理多个MCP

When working with multiple documentation sources:
  1. Give each MCP a descriptive name based on the product/library
  2. Use the appropriate MCP for each query rather than searching all of them
当处理多个文档源时：
  1. 根据产品/库为每个MCP指定一个描述性名称
  2. 针对每个查询使用对应的MCP，而非全部搜索

Step 3: Choose your consumption strategy

步骤3：选择内容获取策略

Strategy A: MCP search (preferred for targeted questions)

策略A：MCP搜索（针对特定问题的首选方式）

Use when:
  • You have a specific question or topic
  • You're looking for a particular API, function, or concept
  • You want semantically relevant results, not just keyword matches
Use the MCP search tool with a natural language query describing what you need.
适用场景：
  • 你有特定的问题或主题
  • 正在查找特定的API、函数或概念
  • 需要语义相关的结果，而非单纯的关键词匹配
使用MCP搜索工具，用自然语言描述你的需求。

Strategy B: Fetch markdown variant (for reading specific pages)

策略B：获取Markdown变体（用于阅读特定页面）

Use when:
  • You need to read a specific documentation page
  • MCP search returned a result but you need the full page content
  • HTML rendering is adding noise or causing truncation
Try the 
.md
variant of the page URL:
bash
curl -s "https://docs.example.com/page.md"
If it returns valid markdown, use it. If it 404s, fall back to HTML (Strategy E).
适用场景：
  • 需要阅读特定的文档页面
  • MCP搜索返回结果，但你需要完整的页面内容
  • HTML渲染带来干扰或导致内容截断
尝试页面URL的
.md
变体：
bash
curl -s "https://docs.example.com/page.md"
如果返回有效的Markdown内容，则使用该版本。如果返回404，则 fallback到策略E（HTML页面）。

Strategy C: Grep llms-full.txt (for keyword-specific searches)

策略C：Grep查询llms-full.txt（用于关键词特定搜索）

Use when:
  • You need to find exact matches (function names, error codes, specific terms)
  • MCP isn't available
  • You want to see all occurrences of a term
Grep for your terms:
bash
curl -s "https://docs.example.com/llms-full.txt" | grep -C 3 "your-search-term"
适用场景：
  • 需要查找精确匹配内容（函数名称、错误代码、特定术语）
  • 无MCP可用
  • 想查看某个术语的所有出现位置
使用grep查询你的术语：
bash
curl -s "https://docs.example.com/llms-full.txt" | grep -C 3 "your-search-term"

Strategy D: Load full content (for comprehensive understanding)

策略D：加载完整内容（用于全面理解）

Use when:
  • You need complete context about a library/API
  • The llms-full.txt is small enough (< 15k tokens recommended)
  • You're doing extensive work that will reference many parts of the docs
Always check length first. Before loading a full file:
bash
curl -sI "https://docs.example.com/llms-full.txt" | grep -i content-length
If the file is too large, consider:
  • Loading specific files identified from llms.txt instead
  • Using MCP search for specific topics
  • Loading in chunks as needed
适用场景：
  • 需要了解库/API的完整上下文
  • llms-full.txt文件足够小（建议小于15k tokens）
  • 正在进行需要频繁参考文档多个部分的大量工作
务必先检查文件长度。加载完整文件前：
bash
curl -sI "https://docs.example.com/llms-full.txt" | grep -i content-length
如果文件过大，可考虑：
  • 仅加载llms.txt中指定的特定文件
  • 针对特定主题使用MCP搜索
  • 根据需要分块加载

Strategy E: View HTML page (for exploration and navigation)

策略E：查看HTML页面（用于探索和导航）

Use when:
  • You need to understand the documentation structure
  • The user needs to navigate or click through the docs
  • You want to see diagrams, interactive examples, or formatted content
  • You're helping the user find something and they need to continue browsing
Fetch and render the HTML page, or direct the user to open it in their browser. HTML pages provide:
  • Navigation menus showing doc structure
  • Interactive code examples
  • Visual diagrams and illustrations
  • Links to related topics
Watch for truncation. Pages over ~150,000 characters may get cut off, which means you may miss critical information without knowing it. If a page seems incomplete, try the 
.md
URL variant (Strategy B) or look for section-specific files in llms.txt.
适用场景：
  • 需要了解文档结构
  • 用户需要导航或点击浏览文档
  • 想查看图表、交互式示例或格式化内容
  • 帮助用户查找内容，且用户需要继续浏览
获取并渲染HTML页面，或引导用户在浏览器中打开。HTML页面提供：
  • 显示文档结构的导航菜单
  • 交互式代码示例
  • 可视化图表和插图
  • 相关主题的链接
注意内容截断。超过约150,000字符的页面可能会被截断，这意味着你可能会在不知情的情况下遗漏关键信息。如果页面内容不完整，尝试使用
.md
URL变体（策略B）或在llms.txt中查找特定章节的文件。

Common patterns

常见模式

Pattern: Research before implementation

模式：实现前调研

  1. Fetch llms.txt to understand documentation scope
  2. Set up MCP if available
  3. Use MCP search for your specific implementation questions
  4. Load relevant sections as needed
  5. Keep MCP connected for follow-up questions during implementation
  1. 获取llms.txt以了解文档范围
  2. 若可用则配置MCP
  3. 使用MCP搜索特定的实现问题
  4. 根据需要加载相关章节
  5. 在实现过程中保持MCP连接，以便后续查询

Pattern: Debugging with docs

模式：借助文档调试

  1. Search for the exact error message or code using grep
  2. If no results, use MCP search with a description of the problem
  3. Load the relevant section for full context on the solution
  1. 使用grep搜索精确的错误消息或代码
  2. 如果无结果，使用MCP搜索问题描述
  3. 加载相关章节以了解解决方案的完整上下文

Pattern: Learning a new library

模式：学习新库

  1. View the HTML landing page to understand structure
  2. Load llms-full.txt if small enough, or use section-specific files
  3. Set up MCP for ongoing reference during development
  1. 查看HTML首页以了解结构
  2. 如果文件足够小则加载llms-full.txt，否则使用特定章节的文件
  3. 配置MCP以便开发过程中持续参考

Pattern: Quick reference lookup

模式：快速参考查询

  1. MCP search with the function/method name
  2. Or grep llms-full.txt for exact matches
  1. 使用MCP搜索函数/方法名称
  2. 或使用grep查询llms-full.txt以查找精确匹配

Tips for efficiency

效率小贴士

  1. Prefer MCP for Mintlify sites: Semantic search is more efficient than loading and parsing raw text.
  2. Cache strategically: If you'll reference the same docs repeatedly, loading llms-full.txt once may be more efficient than multiple MCP searches.
  3. Use section files: If llms.txt links to section-specific files (like 
    api/llms.txt
    ), load only what you need.
  4. Parallel MCP searches: When working with multiple doc sources, search them in parallel rather than sequentially.
  1. Mintlify站点优先使用MCP：语义搜索比加载和解析原始文本更高效。
  2. 合理缓存：如果需要反复参考同一文档，一次性加载llms-full.txt可能比多次MCP搜索更高效。
  3. 使用章节文件：如果llms.txt链接到特定章节的文件（如
    api/llms.txt
    ），仅加载你需要的内容。
  4. 并行MCP搜索：处理多个文档源时，并行搜索而非按顺序搜索。

Handling edge cases

边缘情况处理

No llms.txt available

无llms.txt可用

Fall back to:
  1. Check if there's an MCP endpoint anyway
  2. Try 
    .md
    URL variants of specific pages you need to read
  3. Use WebFetch to read specific documentation pages
  4. Search the web for the documentation
fallback方案：
  1. 无论如何先检查是否有MCP端点
  2. 尝试所需特定页面的
    .md
    URL变体
  3. 使用WebFetch读取特定文档页面
  4. 在网络上搜索该文档

Very large documentation sets

超大文档集

For docs over 15k tokens:
  1. Use MCP search instead of loading the full file
  2. Load section-specific files as needed
  3. Ask the user which areas are most relevant
对于超过15k tokens的文档：
  1. 使用MCP搜索而非加载完整文件
  2. 根据需要加载特定章节的文件
  3. 询问用户哪些区域最相关

Page not found (404)

页面未找到（404）

If a page 404s:
  1. Check the 404 page for links to relevant content
  2. Check llms.txt for the current URL — it reflects the live site structure
  3. Search the MCP with the page topic to find where the content moved
  4. Note to the user that the content may have moved and provide the updated URL
如果页面返回404：
  1. 查看404页面是否有相关内容的链接
  2. 检查llms.txt中的当前URL——它反映了站点的实时结构
  3. 使用MCP搜索页面主题以查找内容迁移位置
  4. 告知用户内容可能已迁移，并提供更新后的URL

Outdated or conflicting information

信息过时或冲突

If you find documentation that seems outdated:
  1. Check for version indicators in the docs
  2. Note the discrepancy to the user
  3. Suggest checking the changelog or release notes
如果发现文档信息似乎过时：
  1. 检查文档中的版本标识
  2. 向用户说明差异
  3. 建议查看变更日志或发布说明