Back to Details

docs-search

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Searching AEM Documentation

搜索AEM文档

Overview

概述

This skill helps you efficiently search the complete aem.live documentation (docs and blog posts) without wasting context on irrelevant pages. Use the provided search script to find relevant documentation pages, then fetch and read the full content of the most relevant results.
该技能可帮助你高效搜索完整的aem.live文档（文档和博客文章），避免在无关页面上浪费时间。使用提供的搜索脚本查找相关文档页面，然后获取并阅读最相关结果的完整内容。

When to Use This Skill

何时使用该技能

Use this skill when:
  • You need information about an aem.live feature or concept
  • You've already looked at the project codebase for context
  • You've tried a basic web search but didn't find relevant aem.live documentation
  • You need technical guidance on implementing aem.live features
  • You're looking for best practices or examples from the official docs
Do NOT use this skill when:
  • You need reusable code snippets or block examples (use 
    block-collection-and-party
    instead)
  • You already know the specific documentation URL
  • You're looking for general web development information (not aem.live specific)
在以下场景使用该技能：
  • 你需要了解aem.live的某个功能或概念
  • 你已经查看过项目代码库以获取相关背景
  • 你尝试过基础网络搜索，但未找到相关的aem.live文档
  • 你需要关于实现aem.live功能的技术指导
  • 你正在从官方文档中寻找最佳实践或示例
请勿在以下场景使用该技能：
  • 你需要可复用的代码片段或区块示例（请改用
    block-collection-and-party
    ）
  • 你已经知道具体的文档URL
  • 你正在寻找通用的Web开发信息（非aem.live特定内容）

How to Use This Skill

如何使用该技能

Step 1: Identify Keywords

步骤1：确定关键词

Determine 1-3 specific keywords related to what you're searching for. Be specific rather than general.
Good keywords:
  • "block decoration"
  • "metadata"
  • "universal editor"
  • "sidekick plugin"
Poor keywords:
  • "aem" (too generic, filtered as stop word)
  • "how to build website" (too broad)
  • "the" (stop word)
确定1-3个与你搜索内容相关的具体关键词。尽量具体，避免宽泛。
优质关键词：
  • "block decoration"
  • "metadata"
  • "universal editor"
  • "sidekick plugin"
劣质关键词：
  • "aem"（过于通用，会被作为停用词过滤）
  • "how to build website"（过于宽泛）
  • "the"（停用词）

Step 2: Run the Search Script

步骤2：运行搜索脚本

Execute the search script from the project root:
bash
node .claude/skills/docs-search/scripts/search.js [--all] <keyword1> [keyword2] [...]
Options:
  • --all
    : Return all matching results (default: limit to 10 most relevant)
  • Without 
    --all
    : Returns top 10 results
Examples:
bash
undefined
从项目根目录执行搜索脚本：
bash
node .claude/skills/docs-search/scripts/search.js [--all] <keyword1> [keyword2] [...]
选项说明：
  • --all
    ：返回所有匹配结果（默认：限制为最相关的10条结果）
  • 不使用
    --all
    ：返回前10条结果
示例：
bash
undefined

Search for block decoration info

搜索区块装饰相关信息

node .claude/skills/docs-search/scripts/search.js block decoration
node .claude/skills/docs-search/scripts/search.js block decoration

Search for metadata with all results

搜索元数据并返回所有结果

node .claude/skills/docs-search/scripts/search.js --all metadata
node .claude/skills/docs-search/scripts/search.js --all metadata

Multi-word search

多词搜索

node .claude/skills/docs-search/scripts/search.js universal editor blocks
undefined
node .claude/skills/docs-search/scripts/search.js universal editor blocks
undefined

Step 3: Review Search Results

步骤3：查看搜索结果

The script returns JSON with the following structure:
json
[
  {
    "path": "/developer/markup-sections-blocks",
    "title": "Markup, Sections, Blocks, and Auto Blocking",
    "description": "To design websites and create functionality, developers use the markup and DOM...",
    "snippet": "Markup, Sections, Blocks, and Auto Blocking\n\nTo design websites...",
    "type": "doc",
    "deprecation": null,
    "relevanceScore": 141
  }
]
Field Explanations:
  • path
    : URL path to the documentation page
  • title
    : Page title
  • description
    : Brief summary (usually ~150 chars) - use this for quick context
  • snippet
    : Relevant excerpt from the page content showing keyword context
  • type
    : "doc" or "blog"
  • deprecation
    : Warning message if feature is deprecated (or null)
  • relevanceScore
    : Relevance score (higher = more relevant)
Important Notes:
  • Results are sorted by relevance (highest first)
  • Deprecated pages have reduced relevance scores but still appear in results
  • The 
    description
    field provides the best quick summary of the page
  • The 
    snippet
    shows keyword context but may not be comprehensive
脚本返回的JSON结构如下：
json
[
  {
    "path": "/developer/markup-sections-blocks",
    "title": "Markup, Sections, Blocks, and Auto Blocking",
    "description": "To design websites and create functionality, developers use the markup and DOM...",
    "snippet": "Markup, Sections, Blocks, and Auto Blocking\n\nTo design websites...",
    "type": "doc",
    "deprecation": null,
    "relevanceScore": 141
  }
]
字段说明：
  • path
    ：文档页面的URL路径
  • title
    ：页面标题
  • description
    ：简要摘要（通常约150字符）- 可用于快速了解页面内容
  • snippet
    ：页面内容中包含关键词的相关摘录
  • type
    ：类型为"doc"（文档）或"blog"（博客）
  • deprecation
    ：若功能已废弃则显示警告信息（否则为null）
  • relevanceScore
    ：相关性得分（得分越高越相关）
重要提示：
  • 结果按相关性排序（得分高的在前）
  • 已废弃页面的相关性得分会降低，但仍会出现在结果中
  • description
    字段是快速了解页面内容的最佳途径
  • snippet
    仅用于提供关键词上下文，内容并不全面

Step 4: Fetch and Read Full Documentation

步骤4：获取并阅读完整文档

The search results give you an overview. To get detailed information, you must fetch and read the complete page content.
Target URL format:
https://www.aem.live{path}
How to retrieve: Use whatever method you have available to fetch the full HTML/text content:
  • Dedicated web fetching tools
  • Terminal commands (curl, wget, etc.)
  • Web browsing/scraping capabilities
Best Practice: Start with the top 2-3 most relevant results, read them fully, then decide if you need more. You may also follow links referenced in the documentation or conduct additional searches based on what you learn.
搜索结果仅为你提供概述。若需详细信息，你必须获取并阅读页面的完整内容。
目标URL格式：
https://www.aem.live{path}
获取方式： 使用你可用的任意方法获取完整的HTML/文本内容：
  • 专用的网页获取工具
  • 终端命令（curl、wget等）
  • 网页浏览/抓取功能
最佳实践： 先从最相关的2-3条结果开始，完整阅读后再决定是否需要更多内容。你也可以参考文档中引用的链接，或根据所学内容进行额外搜索。

Step 5: Alert User to Deprecations

步骤5：提醒用户注意废弃功能

If any results have a 
deprecation
field with content, inform the user that the feature is deprecated and include the deprecation message. Suggest they look at higher-ranked (non-deprecated) alternatives.
若任何结果的
deprecation
字段包含内容，请告知用户该功能已废弃，并附上废弃提示信息。建议用户查看排名更高的（未废弃）替代方案。

What Gets Searched

搜索范围

The search script searches documentation first (150+ pages). Blog posts are only searched if fewer than 5 doc results are found. If you need comprehensive coverage including blogs, use the 
--all
flag.
搜索脚本优先搜索文档（150+页面）。若找到的文档结果少于5条，才会搜索博客文章。若需要包括博客在内的全面覆盖，请使用
--all
参数。

Examples

示例

Example 1: Finding Block Documentation

示例1：查找区块相关文档

User Request: "How do I decorate blocks in aem.live?"
Good Approach:
  1. Search: 
    node .claude/skills/docs-search/scripts/search.js block decoration
  2. Review top 3 results
  3. Fetch the most relevant: 
    https://www.aem.live/developer/markup-sections-blocks
  4. Read full content and provide answer
Poor Approach:
  • Using general web search instead (wastes time on irrelevant results)
  • Not using the search script (might miss the best documentation page)
用户请求： "如何在aem.live中装饰区块？"
正确做法：
  1. 执行搜索：
    node .claude/skills/docs-search/scripts/search.js block decoration
  2. 查看前3条结果
  3. 获取最相关的页面：
    https://www.aem.live/developer/markup-sections-blocks
  4. 阅读完整内容并提供答案
错误做法：
  • 使用通用网络搜索（浪费时间在无关结果上）
  • 不使用搜索脚本（可能错过最佳文档页面）

Example 2: Learning About Metadata

示例2：了解元数据相关内容

User Request: "I need to add metadata to my pages"
Good Approach:
  1. Search: 
    node .claude/skills/docs-search/scripts/search.js metadata
  2. Notice top result is "/docs/bulk-metadata" (score: 63)
  3. Also see "/docs/metadata" (score: 30)
  4. Fetch and read both to understand page-level vs bulk metadata
  5. Provide comprehensive answer with both approaches
Poor Approach:
  • Only reading the first result and missing bulk metadata option
  • Not using 
    --all
    when you need comprehensive coverage
用户请求： "我需要为页面添加元数据"
正确做法：
  1. 执行搜索：
    node .claude/skills/docs-search/scripts/search.js metadata
  2. 注意排名第一的结果是"/docs/bulk-metadata"（得分：63）
  3. 同时看到"/docs/metadata"（得分：30）
  4. 获取并阅读这两个页面，了解页面级元数据与批量元数据的区别
  5. 结合两种方法提供全面的答案
错误做法：
  • 仅阅读第一条结果，错过批量元数据选项
  • 需要全面覆盖时未使用
    --all
    参数

Example 3: Deprecated Feature Warning

示例3：废弃功能提醒

User Request: "How do I use folder mapping?"
Search Results:
json
[
  {
    "path": "/developer/authoring-path-mapping",
    "title": "Path mapping for AEM authoring",
    "relevanceScore": 51,
    "deprecation": null
  },
  {
    "path": "/developer/folder-mapping",
    "title": "Folder Mapping",
    "relevanceScore": 34.5,
    "deprecation": "Please contact us if you have a use case for folder mapping..."
  }
]
Good Response: "I found information about folder mapping, but this feature is deprecated. The deprecation notice says: 'Please contact us if you have a use case for folder mapping...'. The current recommended approach is Path mapping for AEM authoring (the top result). Let me read that documentation for you instead."
Poor Response:
  • Ignoring the deprecation warning and implementing the deprecated feature
  • Not mentioning the better alternative
用户请求： "如何使用文件夹映射？"
搜索结果：
json
[
  {
    "path": "/developer/authoring-path-mapping",
    "title": "Path mapping for AEM authoring",
    "relevanceScore": 51,
    "deprecation": null
  },
  {
    "path": "/developer/folder-mapping",
    "title": "Folder Mapping",
    "relevanceScore": 34.5,
    "deprecation": "Please contact us if you have a use case for folder mapping..."
  }
]
正确回应： "我找到了关于文件夹映射的信息，但该功能已废弃。废弃提示信息为：'Please contact us if you have a use case for folder mapping...'。当前推荐的方案是AEM创作路径映射（排名第一的结果）。我将为你阅读该文档内容。"
错误回应：
  • 忽略废弃警告并指导用户实现已废弃功能
  • 未提及更优的替代方案

Related Skills

相关技能

  • block-collection-and-party: Use when you need reusable code examples or block implementations
  • building-blocks: Use when creating new blocks from scratch
  • content-modeling: Use when designing content models for blocks
  • block-collection-and-party：当你需要可复用的代码示例或区块实现时使用
  • building-blocks：当你需要从头创建新区块时使用
  • content-modeling：当你需要为区块设计内容模型时使用

Important Reminders

重要提醒

  1. Always check for deprecation warnings and alert the user
  2. Fetch and read full pages - search results are just for finding the right pages
  3. Start with top 2-3 results before expanding search
  4. The description field is your friend - it's usually well-written and concise
  5. Don't rely solely on snippets - they're for context, not comprehensive information
  1. 务必检查废弃警告并告知用户
  2. 获取并阅读完整页面 - 搜索结果仅用于定位正确页面
  3. 先从最相关的2-3条结果开始，再扩大搜索范围
  4. 善用description字段 - 该字段内容通常撰写精良且简洁
  5. 不要仅依赖snippet - 它仅用于提供上下文，无法涵盖全面信息