Doc Server SEO upgrade & refactor

2026-05-30

A two-front update landed today: the content renderer was normalized across page types, and a full SEO pass shipped on top.

Rendering refactor

  • Boards, lists, board groups, and board lists now share one card renderer. Padding, background, shadow, and corner radius are identical across types. List titles use the same h5 typography as boards.
  • One <h1> per page, sitting in the last breadcrumb slot — natural placement, no extra visual real estate, single source of truth for the page heading.
  • HTML-escaped everywhere. Every user-controlled string (names, descriptions, breadcrumb labels, canonical URL, OG image URL) now goes through html_escape before reaching the template. Names like Q&A: when to use "file" no longer corrupt attributes.
  • Small polish: icon-to-text gap in card rows, list corner-radius matched to board, list title vertical padding aligned with the board card.

SEO & multi-language URLs

  • /zh/... and /ja/... URLs. Every page is reachable in each supported language at its own crawlable URL. The bare URL (e.g. /policies/) continues to serve the default language (English).
  • <link rel="alternate" hreflang="..."> in every page header — Google can surface the right language version to each visitor.
  • canonical, Open Graph, Twitter Card, and JSON-LD BreadcrumbList tags on every page. Link previews on social platforms show titles, descriptions, and images correctly.
  • /sitemap.xml generated and refreshed in the background every hour, listing every page with its hreflang alternates.
  • /op/switch_lang/<code> — a new language switcher that keeps URL and cookie in sync. Click “中文” anywhere and you’ll land on /zh/<the page you were on>/.

Why

The render refactor pays down years of per-type duplication. The SEO/language work makes the docs discoverable and shareable: humans on the main site get a sticky language preference, and search engines index each language as a distinct, crawlable page.