文档服务器 SEO 升级与重构

2026-05-30

本次更新分为两条主线：内容渲染层在各页面类型间完成统一，并在此基础上完成了完整的 SEO 改造。

渲染重构

  • 看板、列表、看板组、看板列表现共用同一张卡片渲染器：内边距、背景、阴影与圆角在各类型间完全一致；列表标题改用与看板一致的 h5 样式。
  • 每页一个 <h1>，位于面包屑最后一项 —— 自然贴合页面位置，无需额外视觉空间，并成为页面标题的唯一来源。
  • 全面 HTML 转义：所有用户可控字符串（名称、描述、面包屑文本、canonical URL、OG 图片 URL）现均经过 html_escape 后再交给模板。形如 Q&A: when to use "file" 这类名称不再破坏 HTML 属性。
  • 细节打磨：卡片行内图标与文字间距、列表与看板圆角统一、列表标题上下内边距与看板卡片对齐。

SEO 与多语言 URL

  • /zh/... 与 /ja/... 路径：每个页面现可通过对应语言的独立可爬取 URL 访问；原始裸 URL（例如 /policies/）继续提供默认语言（英文）。
  • 每页 <link rel="alternate" hreflang="...">：Google 可为不同语言访客提供对应版本。
  • canonical、Open Graph、Twitter Card、JSON-LD BreadcrumbList 标签覆盖每一页。社交平台的链接预览现可正确显示标题、描述与图片。
  • /sitemap.xml：由后台任务每小时自动生成与刷新，包含所有页面及其 hreflang 备用 URL。
  • /op/switch_lang/<code>：全新的语言切换端点，保持 URL 与 Cookie 同步。点击「中文」会跳转到 /zh/<当前页面>/。

缘由

渲染重构清理了长期以来按页面类型分别实现的重复代码；SEO 与多语言改造让文档可被搜索引擎收录、可被分享：主站访客保留语言偏好，同时搜索引擎将每种语言索引为独立、可爬取的页面。