指南

搜索与分享

facet 负责页面的样子，搜索引擎看的是页面里的内容和 <head>。这一页列出每个使用 facet 的网站该做的事，以及哪些 facet 已经替你做好了。

facet 已经做好的

内容就在 HTML 里。故事页、全页面板和演示文稿没有 JavaScript 也能读，所以搜索引擎读到的和访客看到的一样。
每种版式都用语义标签：main、nav、article、section，以及有层级的标题。
字体自托管并使用 font-display: swap，文字不会因为等字体而空白；中文标题字体按需分片，一页只下载用到的字。
对比度至少 4.5:1，照顾减少动效的设置，键盘可以操作每个控件。可访问性和搜索看重的是同一套东西。
猫是装饰：它们带 aria-hidden，不会混进页面文字。

每一页的 head

标题和描述每页都不一样：标题先写这一页，再写网站名，60 个字符以内；描述 50 到 160 个字符，写给搜索结果里的读者。规范链接、分享图片和 og:url 用绝对地址。

<html lang="en" data-accent="moss">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Chasing the red dot · Duna's notes</title>
  <meta name="description" content="Twelve rooms, one red dot, and what Duna learned about light." />
  <link rel="canonical" href="https://example.com/notes/red-dot/" />

  <meta property="og:type" content="article" />
  <meta property="og:title" content="Chasing the red dot" />
  <meta property="og:description" content="Twelve rooms, one red dot, and what Duna learned about light." />
  <meta property="og:url" content="https://example.com/notes/red-dot/" />
  <meta property="og:image" content="https://example.com/notes/red-dot/card.png" />
  <meta name="twitter:card" content="summary_large_image" />

  <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
  <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#13161c" />
  <meta name="theme-color" media="(prefers-color-scheme: light)" content="#f5f7f9" />

  <link rel="preload" href="/facet/dist/fonts/geist.woff2" as="font" type="font/woff2" crossorigin />
  <link rel="stylesheet" href="/facet/dist/facet.css" />
</head>

分享图片 1200×630，PNG 或 JPEG，尽量小于 300 KB；文字放大，手机上的预览很小。
两个 theme-color 用的是 facet 的 --f-bg（深色和浅色），浏览器的地址栏就和页面同色。
只预加载首屏用到的一两个字体，通常是 Geist（正文）和 Source Serif 4（标题）。预加载太多反而拖慢首屏。
跨域加载字体（比如从 jsDelivr）时，preload 一定要带 crossorigin，否则字体会下载两次。

每种版式的结构化数据

在 <head> 里放一段 JSON-LD，告诉搜索引擎这一页是什么。每种版式通常对应一种 schema.org 类型：

版式	类型	要点
阅读、旁注	`BlogPosting`	`headline`、`datePublished`、`image`，作者指向网站的 `Person`。
文档	`TechArticle`	再加一个 `BreadcrumbList`，给出它在文档里的位置。
简历	`ProfilePage` + `Person`	`sameAs` 列出你在其他网站上的主页，把它们和这个网站连起来。
列表	`CollectionPage`	可以用 `ItemList` 列出每一项的链接。
分屏	`SoftwareSourceCode`	项目页：`codeRepository`、`license`、`version`。
封面、故事、全页面板	`VideoObject`	页面上有视频时：`name`、`thumbnailUrl`、`uploadDate`、`contentUrl`。
演示文稿	`PresentationDigitalDocument`	可选；大多数演示文稿用 `WebPage` 就够了。
应用	`WebApplication`	`applicationCategory`，比如 `GameApplication`。
空状态	不需要	用作 404 页时，服务器要真的返回 404。
聚焦	`ContactPage`	用作联系页时；链接汇总页用 `WebPage`。
首页	`ProfilePage`	个人首页；`Person` 是它的 `mainEntity`。

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Chasing the red dot",
  "datePublished": "2026-10-11T09:00:00-07:00",
  "image": "https://example.com/notes/red-dot/card.png",
  "author": { "@id": "https://example.com/#person" }
}
</script>

用 @id 引用同一个 Person，而不是每页重写一遍：首页定义它，其他页面只写 @id。

版式注意事项

封面：标题和导语写在 HTML 里，叠在图片上，不要做进图片。首屏大图不要 loading="lazy"，可以加 fetchpriority="high"。
演示文稿：data-f-slide 里只放位置和颜色，文字一律写在幻灯片的标记里。搜索引擎不读属性里的 JSON。
演示文稿、全页面板和应用的画面里没有显眼的大标题时，也给页面一个 h1，可以用 f-visually-hidden 藏起来。
文档和旁注：标题带稳定的 id，搜索结果可以直接链接到某一节；旁注本来就在 DOM 里。
图片：内容图写有意义的 alt，装饰图写 alt=""；写上 width 和 height，避免加载时页面跳动；首屏以下的图片用 loading="lazy"。
应用：内容很少的工具页，在 HTML 里写一段简短说明；登录后的状态或私人页面用 noindex。

双语网站

搜索引擎只收录一个地址返回的 HTML，在浏览器里替换文字的语言切换，另一种语言永远不会被收录。所以每种语言要有自己的地址，用 lang 标明语言，再用 hreflang 把它们连起来：

<html lang="zh-Hans">
<link rel="canonical" href="https://example.com/zh/notes/red-dot/" />
<link rel="alternate" hreflang="en" href="https://example.com/notes/red-dot/" />
<link rel="alternate" hreflang="zh-Hans" href="https://example.com/zh/notes/red-dot/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/notes/red-dot/" />

两种语言的页面都列出全部 hreflang，包括自己；每页的规范链接指向它自己，不要指向另一种语言。
facet 的中文规则跟着 lang 走：<html lang="zh-Hans"> 让整页用中文行高和断行，页面里的一段 lang="en" 再回到英文的行高。

站点地图和 robots.txt

sitemap.xml 列出每个规范地址，只列规范地址：不要列跳转页、分页的第一页或 noindex 的页面。
搜索引擎只在域名根目录读 robots.txt。GitHub Pages 的项目网站（比如 example.com/project/）没法有自己的 robots.txt，要在根网站的 robots.txt 里加一行 Sitemap: 指向它，或者在 Search Console 里提交。
草稿、设计稿和测试页面加 <meta name="robots" content="noindex">，并且不放进站点地图。

这个网站是怎么做的

每个参考页面只写自己的 <title> 和 <meta name="description">，各带一个中文的 data-zh。just site 组装网站时，scripts/site_meta.py 把每一页在 zh/ 下再写一份，中文直接写在 HTML 里，工具栏的 EN / 中文就在两个地址之间切换（本地 just serve 时仍是原地替换）；然后根据标题和描述补上规范链接、hreflang、图标、theme-color、Open Graph、JSON-LD（首页是 WebSite 和 SoftwareSourceCode，其他页面是带面包屑的 WebPage），写出 sitemap.xml，并给设计稿加上 noindex。分享图片由 scripts/card.py 根据 facet 的令牌和字体画出。