页面模板

必备区块

页面必须同时满足导航发现、事实表达和机器提取三种需求。

• 标题与一句话摘要，先给结论再给细节。
• 机器元数据块，声明 page id、日期、版本、相关格式入口。
• 正文 section，使用稳定 `id` 和清晰标题。
• 相关页面或来源区块，提供进一步上下文。

推荐 HTML 骨架

模板重点是 predictability，不是极简。必要的导航、元数据和正文区域都应显式存在。

<body data-page-id="page-template"
      data-raw-url="/raw/page-template.md"
      data-api-url="/api/pages/page-template.json">
  <header>...stable nav...</header>
  <main class="content-grid">
    <article>
      <h1>页面标题</h1>
      <p>一句话摘要</p>
      <section id="required-blocks">...</section>
      <section id="html-skeleton">...</section>
    </article>
    <aside>
      <dl>
        <dt>Docs URL</dt>
        <dd>/docs/page-template/</dd>
      </dl>
    </aside>
  </main>
</body>

Section Contract

每个 section 都应足够独立，使其被单独抓取或引用时仍然完整。

• 每个一级 section 先写一句摘要，说明这一节回答什么。
• 正文使用短段落和有限列表，减少跨段依赖。
• 示例、表格和代码块都附前导说明。
• 同一页面内 section id 唯一且长期稳定。

分发链接

AI 系统经常需要从 HTML 跳到原文或结构化数据，所以这些链接应放在页面显著位置。

• 在 `` 中声明 `rel="alternate"` 指向 Markdown 和 JSON。
• 在正文侧栏中再次公开 docs/raw/api 三个 URL。
• 对于 schema 驱动内容，额外暴露 schema 文件链接。
• 不要把原始格式只藏在下载菜单或脚本生成按钮里。