{
  "$schema": "https://pingfanfan.github.io/OpenWebsite/schema/knowledge-page.schema.json",
  "format": "knowledge-page",
  "id": "url-conventions",
  "url": "https://pingfanfan.github.io/OpenWebsite/docs/url-conventions/",
  "rawUrl": "https://pingfanfan.github.io/OpenWebsite/raw/url-conventions.md",
  "apiUrl": "https://pingfanfan.github.io/OpenWebsite/api/pages/url-conventions.json",
  "schemaUrl": "https://pingfanfan.github.io/OpenWebsite/schema/knowledge-page.schema.json",
  "title": "URL 规范",
  "summary": "定义 slug、锚点、资源路径和生命周期策略。",
  "lastUpdated": "2026-03-12",
  "version": "v1.0.0",
  "audience": ["ai-agent", "crawler", "developer", "human"],
  "sourceOfTruth": "路径命名与引用稳定性",
  "tags": ["url", "slug", "anchors", "lifecycle"],
  "sections": [
    {
      "id": "route-patterns",
      "title": "路径模式",
      "summary": "同一主题在 HTML、Markdown 和 JSON 三种格式下共享同一 slug。",
      "content": [
        "HTML 路径模式为 /docs/<slug>/。",
        "Markdown 路径模式为 /raw/<slug>.md，JSON 路径模式为 /api/pages/<slug>.json。",
        "三种表示应保持一一对应，避免多组命名并存。"
      ]
    },
    {
      "id": "slug-rules",
      "title": "Slug 规则",
      "summary": "slug 应该是可读但不依赖自然语言细节的稳定标识。",
      "content": [
        "使用小写英文和连字符，不使用空格、下划线和日期前缀。",
        "slug 表达主题而不是营销标题，例如 url-conventions。",
        "页面标题可以变化，但 slug 尽量不变化。"
      ]
    },
    {
      "id": "anchor-rules",
      "title": "锚点规则",
      "summary": "稳定 anchor 能显著提升检索系统回引具体结论的能力。",
      "content": [
        "使用语义化 id，例如 #anchor-rules 和 #lifecycle。",
        "不要使用自动生成的随机 hash。",
        "调整 section 顺序时不应修改原有 id。"
      ]
    },
    {
      "id": "lifecycle",
      "title": "生命周期策略",
      "summary": "删除或频繁更改 URL 会直接破坏已有引用和缓存。",
      "content": [
        "非破坏更新使用同一路径并提升版本号。",
        "主题边界变化时保留旧 URL 并在正文中指向新页面。",
        "仅在需要隔离不兼容事实时，才创建新版本路径。"
      ]
    }
  ],
  "relatedPages": [
    {
      "id": "information-architecture",
      "title": "信息架构",
      "url": "https://pingfanfan.github.io/OpenWebsite/docs/information-architecture/"
    },
    {
      "id": "retrieval-contract",
      "title": "检索与抓取契约",
      "url": "https://pingfanfan.github.io/OpenWebsite/docs/retrieval-contract/"
    }
  ]
}