## 文档服务器 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 与多语言改造让文档可被搜索引擎收录、可被分享：主站访客保留语言偏好，同时搜索引擎将每种语言索引为独立、可爬取的页面。