先定阅读路径，再画页面

上一版从“首页要放什么”开始，结果首页塞了自我介绍、最新文章、项目卡片、友链、订阅框和一张很大的头像。每个模块都有一点用，但没有一个能让人停下來。

这次先写了一个只有五行的草稿：

我是谁 → 我做过什么 → 我最近在想什么 → 怎么联系我。

对应的就是首页的顺序：一句主张、三个事实、项目、笔记、关于、联系。导航只保留这四件事，其他链接放进页脚。页面少了，反而更容易把每一屏做清楚。

主题不是换一套颜色

最容易做的事是改 --bs-primary，然后宣布“自定义主题完成”。真正麻烦的是那些模板没管的地方：标题的中英文混排、代码块的横向滚动、深色模式下的边框对比度、目录在窄屏上的位置。

我把样式分成两层：

1. 变量层：颜色、字体、圆角、阴影、容器宽度，全部放在 tokens.css；
2. 规则层：导航、首页、内页、页脚各自一个文件，只使用变量，不写死颜色。

这样深色模式不需要复制一套规则。只要在根元素上切换 data-theme，再让 Quarto 自己的 quarto-dark 类跟上：

html[data-theme="dark"] {
  --cz-bg: #14110e;
  --cz-ink: #f4ead9;
  --cz-accent: #e98a5c;
}

颜色不是越多越好。浅色模式用暖纸色做底，正文是偏暖的墨色；强调色只留给链接、按钮和少量标记。深色模式不是简单反色，而是把纸换成深棕，把橙色提亮，避免纯黑背景上的细字发虚。

Quarto 帮了大忙，也有自己的脾气

Quarto 的网站项目很适合这种站点：Markdown 写内容，YAML 管导航，Bootstrap 处理栅格，发布到 GitHub Pages 只需要一个 action。但它不是“零配置”。

我踩到的第一个坑是缩进。首页最初用原始 HTML 写，<div class="cz-hero"> 内部的空行和四空格缩进被 Pandoc 当成了代码块，整段 HTML 原样显示在页面上。后来改成 fenced div：

::: {.cz-hero}
...
:::

这里还有一条规则：::: 的上一行必须是空行，下一行也要空一行。否则 Pandoc 会把围栏当成普通段落的一部分。这不是 Quarto 的 bug，是 Pandoc 的 Markdown 解析规则；知道以后就不再浪费时间怀疑人生。

第二个坑是页面宽度。Quarto 的 page-layout: custom 不会自动把内容容器居中，默认贴着左侧。自定义页面需要自己处理：

#quarto-content.page-layout-custom {
  margin-inline: auto;
}

第三个坑是链接。Quarto 不会阻止你写一个不存在的 href，但构建时会给出警告。把警告当错误看，顺手就能发现导航里指向 .qmd 而不是渲染后路径的链接。

发布应该是一条命令

网站最终放在 GitHub Pages 上。构建和发布都在 GitHub Actions 里完成，本地只负责写和预览：

quarto preview
quarto render

发布工作流做三件事：安装 Quarto、渲染站点、把 _site 推到 gh-pages。第一次发布后，还要去仓库的 Settings → Pages 把来源改成 gh-pages。用户站点默认会指向 main，这一步很容易漏，漏了就会看到 404。

最后留下的检查清单

• 每个页面都有独立的 title 和 description；
• 导航链接在本地渲染后仍然有效；
• 深色模式不是反色，而是重新检查过对比度；
• 键盘可以到达所有交互元素，焦点环清晰可见；
• 关闭动画后，内容仍然完整；
• 发布后打开线上地址，而不是只看本地预览。

网站不是一次做完的。它现在仍然有一些我想改的地方，比如项目页的筛选、文章的上一篇/下一篇。但至少这次，我知道每一层为什么存在，也知道下一次该从哪里开始。

例子要能独立存在

最开始的例子常写成这样：

// 省略头文件和 main
std::vector<int> values{3, 1, 4};
std::sort(values.begin(), values.end());

读者需要自己补 #include、命名空间和 main，还要猜 values 最后是什么。这些“显然”的部分，恰恰是初学者最容易卡住的地方。

现在我会把例子写成完整文件：

#include <algorithm>
#include <iostream>
#include <vector>

int main() {
  std::vector<int> values{3, 1, 4};
  std::sort(values.begin(), values.end());

  for (int value : values) {
    std::cout << value << ' ';
  }
  std::cout << '\n';
}

再附上实际输出：

1 3 4

多出来的几行不是噪音，而是把“你可以直接运行”这件事变成真的。

给每个例子一个位置

如果文章里只有一个例子，贴代码块就够了。但当一章有十几个例子时，散在正文里的代码很快会失去上下文。我的做法是给每篇笔记一个独立目录：

notes/
└── 03-references/
    ├── index.qmd
    ├── 01-basic.cpp
    ├── 02-const-ref.cpp
    └── expected.txt

正文通过代码块引用文件，构建前用一个脚本把源码和输出同步进去。这样例子可以被单独编译，笔记也不会因为复制粘贴而和源码走散。

脚本本身不需要复杂：

for file in notes/*/*.cpp; do
  g++ -std=c++20 -Wall -Wextra -pedantic "$file" -o /tmp/example
  /tmp/example > "${file%.cpp}.out"
done

真正重要的是把它放进发布流程。只要有一次提交没有通过编译，构建就会失败，而不是等到读者发现。

解释“为什么”，而不是复述语法

能运行的例子解决了“对不对”，但没有解决“为什么”。我尽量避免这种句子：

const 表示常量。

它没有错，但读者看完仍然不知道什么时候该用。更有用的写法是先给出一个会出问题的场景，再说明约束：

如果函数参数写成 std::vector<int> values，每次调用都会复制整个数组。数据量大时，这个复制会出现在性能分析里，而不是语法错误里。改成 const std::vector<int>& 可以避免复制，同时承诺函数不会修改它。

前者是定义，后者是判断。笔记的价值通常在后半部分。

一个可以照着做的检查清单

写完一篇 C++ 笔记，我会过一遍：

• 每个代码块都有完整的 #include 和 main，或者明确说明它只是片段；
• 代码用 -Wall -Wextra -pedantic 编译过；
• 输出是实际运行结果，不是手写的“应该输出”；
• 至少有一个地方解释“不这样写会怎样”；
• 文中的文件名、命令和目录结构，与示例仓库一致；
• 读者不需要先读上一篇，也能运行当前例子。

这几条不保证文章写得好，但能保证它不会在读者第一次尝试时就失败。对学习笔记来说，这已经是一个不错的起点。

第一次发布后，还要改一个设置

这是用户站点最容易漏的一步。仓库叫 chengzhao-dev.github.io 时，GitHub Pages 默认把 main 当作发布源。工作流把构建结果推到了 gh-pages，但 Pages 仍然在看 main，于是线上一直是旧页面，或者直接 404。

发布成功后，去 Settings → Pages，把 Build and deployment → Source 改成 Deploy from a branch，分支选 gh-pages，目录选 / (root)。只需要做一次。

项目站点（比如 cpp-notes）也是同样的逻辑，只是仓库设置的位置一样，页面地址多一个子路径。

本地预览和线上构建要一致

Actions 里的 Quarto 版本可能比你本地新。某次我在本地能渲染，线上却因为一个已经废弃的 YAML 字段失败。后来我在工作流里固定版本：

- uses: quarto-dev/quarto-actions/setup@v2
  with:
    version: "1.10.19"

固定版本不是拒绝升级，而是让“本地通过、线上失败”这种问题有一个明确的排查起点。升级时改一个数字，重新跑一遍，比在日志里猜版本要快。

把检查放进流水线

发布工作流不应该只负责“把文件推上去”。在 publish 之前加一步渲染检查，可以让坏链接、缺失的标题和无效的 YAML 在部署前暴露：

- name: Render and check
  run: |
    quarto render
    test -f _site/index.html
    test -f _site/sitemap.xml

更严格的检查可以交给单独的脚本，比如遍历 _site 里的内部链接、确认每个页面都有 <title>、检查 _site 没有混入草稿。这些检查在本地也能跑，但只有放进 CI，才不会因为“这次赶时间”被跳过。

三个常见故障

1. 发布成功，页面没变。 先看 Pages 的 Source 是不是 gh-pages，再看工作流有没有真的推送成功。gh-pages 分支存在，不代表 Pages 在用它。

2. 样式在本地正常，线上 404。 检查 CSS 和字体路径是不是以 / 开头。站点部署在用户根域名下没问题；如果以后放到子路径，根路径就会指错地方。

3. 工作流突然失败，日志只有一行权限错误。 检查仓库的 Settings → Actions → General → Workflow permissions 是否允许读写，以及 YAML 里有没有声明 contents: write。

发布应该无聊

我现在对发布流程的期待是“无聊”：push，等两分钟，打开线上地址，页面是新的。没有手动上传，没有忘记渲染，也没有“这次先这样”。

自动化不是为了显得专业。它只是把一件必须重复的事，变成一件不需要重复决定的事。省下来的注意力，可以拿去写下一篇文章。