用途:优化 Elastic 文档页面开头部分(frontmatter 之后约前 10 行,包括 H1、开篇段落和前置要求),以提升可发现性与读者价值。输入为文件路径或目录;若为目录则处理其中所有 .md 文件,若为空则询问用户要优化什么。
主要能力:先判定文档类型(教程、操作指南、参考、说明、概览),不同类型对应不同 H1 风格、开篇语气与是否添加要求;概览页通过 toc.yml 中带 children 的条目识别。随后优化 H1,要求可发现、具体、唯一,超过约 50 字符时添加 navigation_title。再撰写 2-4 句开篇段落,且不得重复 frontmatter description,并按类型给出写法(教程定义功能并说明覆盖范围;操作指南定义功能与价值;参考定义主题与用途;说明交代背景与涵盖概念;概览说明功能、价值与关键能力)。满足条件时添加「Before you begin」小节:前 50 行无该节、非概览页、至少一项非显而易见要求。最后强制使用 Jinja2 替换硬编码产品名,UI 元素用粗体、技术元素用等宽,并在编辑后立即运行 vale <file> 修复错误。
使用方式:对目标文件逐项执行分类、改 H1、写开篇、必要时加要求小节、替换、lint。
限制与注意:不得修改、移动或重写前约 20 行内的重要/警告提示;概览页不加「Before you begin」;移除 9.0 之前版本引用;H1 不加自定义锚点由 docs-builder 自动生成;要求小节排除显而易见的前置条件与通用系统要求。具体收费、平台与效果信息暂未提供。