深入理解 Rails Guides 2024 视觉改版：SCSS 构建链、rake 生成流程与暗色模式、LTR/RTL 的实现原理

Rails 官方指南（Guides）在 2024 年第一季度完成了一次视觉改版，使其风格与 rubyonrails.org 主站保持一致。本文以 guides/README.md 为骨架，结合仓库中的 Rake 任务、生成器源码与 SCSS 文件，完整还原“从 Markdown 源文件到带缓存戳静态 HTML”的构建链路，并解释改版中几个关键设计决策（弃用 CSS 变量、LTR/RTL 双向布局、暗色模式独立成文件）背后的技术原因。读完本文，你将掌握在本地构建、清理、校验 Rails Guides 的完整方法，以及每个构建环节对应的源码位置。

一、项目背景：2024 年第一季度视觉改版

根据 guides/README.md 的说明，Rails Guides Visual Refresh 发生于 2024 年第一季度（Q1 2024），目标是让指南页面的视觉风格与 rubyonrails.org 站点统一。从 guides/assets/stylesrc/style.scss 的文件头注释可以看到，这套样式体系创建于 2024 年 2 月 29 日、修改于 3 月 19 日，与 README 中的时间线相互印证。

改版后的指南站点是完全由静态文件生成的：源 Markdown/ERB 文件位于 guides/source/，最终产物输出到 guides/output/，资产（图片、脚本、样式）从 guides/assets/ 复制并追加内容摘要（digest）。理解这套构建流程，是后续所有开发工作的基础。

二、样式编辑依赖：stylesrc 目录与 SCSS 技术选型

README 的 “Editing Dependencies” 一节指出：指南重建的编辑文件位于 stylesrc 目录，使用 SCSS 以提升开发者体验，并依赖两个基础库：

• include-media：支持在 SCSS 中内联书写媒体查询断点，替代手写 @media；
• normalize.css：消除各浏览器默认样式差异，统一跨浏览器表现。

这两者都以 vendor 形式内置在仓库中，可以从 guides/assets/stylesrc/vendor/_include-media.scss 看到 include-media 的完整实现（基于 sass:map、sass:list 等 Dart Sass 模块构建）。

stylesrc 目录结构

guides/assets/stylesrc/ 下的文件组织如下：

文件	作用
style.scss	主样式入口：引入 vendor 依赖、定义断点与全局变量、导入各组件后汇入主样式
highlight.scss	Pygments 语法高亮配色，覆盖 .c、.k、.s 等各 token 类名
print.scss	打印样式
_main.scss	主布局样式（partial）
_dark.scss	暗色模式覆盖样式（partial，见第五节 FAQ）
components/_code-container.scss	代码块容器组件

style.scss 的前置部分是整个样式体系的“配置中心”，它先引入三个 vendor 依赖：

@import 'vendor/normalize';
@import 'vendor/boilerplate';
@import 'vendor/include-media';

// 覆盖 include-media 的默认断点
$breakpoints: (
  'phone': 320px,
  'phone-wide': 480px,
  'tablet': 768px,
  'desktop': 1024px,
  'desktop-wide': 1280px,
  'desktop-ultra-wide': 1440px,
  'desktop-hd': 1920px,
  'desktop-full': 2560px
);

值得注意的是，这套断点覆盖了 include-media 的默认值（源码注释明确标注 “This overrides the defaults in include-media”），并一直覆盖到 2560px 的桌面超宽屏。随后文件定义了品牌色阶（$rf-brand: #C81418 及一组 lighten/darken 变体）、灰阶（$gray-100 到 $gray-1000）、以及三类“插值提示框”配色——$note（黄）、$tip（青）、$stop（品牌红），每类都带有 -dark 变体供暗色模式使用。style.scss 中还专门处理了 APCA 对比度算法在深色背景（暗于 #333333）下规则不同的问题，定义了 $text-on-dark-bg、$text-on-darker-bg、$large-text-on-darker-bg 三个文字色变量，分别对应常规文本与大号文本（> 24px）的对比度要求。

字体方面，样式与主站共用同一套字体资源：InterVariable（可变字体，100–900 字重）、IBM Plex Mono（等宽字体）与 Calibre（标题字体），通过 @font-face 从 rubyonrails.org 的字体路径加载（style.scss）。

三、本地构建指南：rake guides:generate 与清理规则

README 的核心操作指令只有一句：在 guides 目录下执行 rake guides:generate 即可生成新的静态指南文件；如果修改了 HTML 或 ERB，需要先删除 output 目录再运行该命令；主 SCSS 文件（style.scss、highlight.scss）会作为该过程的一部分被编译。下面结合源码解释每条指令的含义。

3.1 Rake 任务全景

guides/Rakefile 定义了完整的任务树：

guides:generate              # 生成 HTML 指南（等价于 guides:generate:html）
guides:generate:html         # 仅生成 HTML
guides:generate:epub         # 生成 EPUB（设置 EPUB=1 后调用 html 流程）
guides:generate:kindle       # 已废弃，打印弃用警告后转发到 epub 任务
guides:lint                  # 组合任务：check_links + mdl
guides:lint:check_links      # 以 GUIDES_LINT=1 运行生成流程，检查生成的 HTML 中的断链
guides:lint:mdl              # 用 mdl 检查 source/*.md 的 Markdown 风格（忽略 release notes）
guides:validate              # 通过 w3c_validator.rb 校验 HTML
guides:vendor_javascript     # 将 @hotwired/turbo 的 UMD 版本下载并 vendor 到 assets/javascripts
guides:help                  # 打印任务帮助（也是 default 任务）

所有任务最终汇聚到 Rakefile 中的 generate_guides 方法（guides/Rakefile），它读取环境变量并构造生成器：

def generate_guides
  require_relative "rails_guides"
  env_value = ->(name) { ENV[name].presence }
  env_flag  = ->(name) { "1" == env_value[name] }

  version = env_value["RAILS_VERSION"]
  edge    = `git rev-parse HEAD`.strip unless version

  RailsGuides::Generator.new(
    edge:      edge,
    version:   version,
    all:       env_flag["ALL"],
    only:      env_value["ONLY"],
    epub:      env_flag["EPUB"],
    language:  env_value["GUIDES_LANGUAGE"],
    direction: env_value["DIRECTION"],
    lint:      env_flag["GUIDES_LINT"]
  ).generate
end

guides:help 任务内置了完整的环境变量文档，整理如下：

环境变量	取值	作用
RAILS_VERSION	Git tag，如 v5.1.0	为特定 Rails 版本生成指南；不设置则使用当前 HEAD 的 SHA1 生成 edge 版指南
ALL	1	强制重新生成全部指南（默认只重建源文件比产物新的指南）
ONLY	名称，逗号分隔	只生成指定指南，如 ONLY=migrations 或 ONLY=assoc,migrations
GUIDES_LANGUAGE	语言代码，如 es	从 source/<语言代码>/ 目录生成翻译版指南
DIRECTION	ltr / rtl	控制页面文字方向（默认 ltr，见第五节）
GUIDES_LINT	1	进入 lint 模式：只检查断链并输出警告，不写文件；有警告时以非零码退出
EPUB	1	由 guides:generate:epub 任务内部设置，触发 EPUB 打包

3.2 为什么改了 HTML/ERB 必须删除 output 目录

这是 README 中一条容易被忽视的“坑”。从 guides/rails_guides/generator.rb 的增量判断逻辑可以看到原因：

def generate?(source_file, output_file)
  fin  = File.join(@source_dir, source_file)
  fout = output_path_for(output_file)
  @all || !File.exist?(fout) || File.mtime(fout) < File.mtime(fin)
end

增量构建只比较每篇指南自身源文件（.md/.erb）与其产物的修改时间。而 layout.html.erb 这类布局文件被所有指南共享，修改它并不会让任何一篇指南的源文件“变新”，因此已生成的旧 HTML 不会自动重算——这就是必须手动清除 output 目录的原因（也可以用 ALL=1 强制全量重建）。

另一方面，生成流程本身对资产目录做过精确清理。generator.rb 中的 cleanup_assets 只删除上次的 HTML 与 stylesheets/javascripts 两个目录：

def cleanup_assets
  FileUtils.rm_f(Dir.glob("#{@output_dir}/*.html"))
  FileUtils.rm_rf(Dir.glob("#{@output_dir}/{stylesheets,javascripts}"))
end

注意它并不清理 EPUB 子目录或手工放入 output 的其他文件。guides/test/generator_test.rb 中的测试固化了这一行为：预置的 stale_test_guide.html、old_stale_test.css、old_stale_test.js 必须在生成后被清除，而 keep_me_test_file.txt 必须保留（guides/test/generator_test.rb）。

3.3 SCSS 编译：process_scss

README 说“主 SCSS 文件会作为生成过程的一部分被编译”，实际调用链在 generator.rb：

def process_scss
  system "bundle exec dartsass \
    #{@guides_dir}/assets/stylesrc/style.scss:#{@output_dir}/stylesheets/style.css \
    #{@guides_dir}/assets/stylesrc/highlight.scss:#{@output_dir}/stylesheets/highlight.css \
    #{@guides_dir}/assets/stylesrc/print.scss:#{@output_dir}/stylesheets/print.css"
end

这里有两点值得注意：

1. 编译工具是 Dart Sass（bundle exec dartsass），一次命令行同时编译三个入口：README 中提到的 style.scss、highlight.scss，以及测试文件 guides/test/generator_test.rb 中同样确认的 print.scss（三者都会产出对应的 style.css/highlight.css/print.css 并被断言存在）；
2. 输出直接落到 output/stylesheets/，随后 add_digests 会为每个 CSS/JS 资产计算 MD5 摘要并重命名（如 style-<md5>.css），实现浏览器级缓存失效（generator.rb）。

copy_assets 随后把 assets/ 下除 stylesrc 以外的全部内容（即已编译产物之外的图片、JS 等）复制进 output——SCSS 源文件永远不会直接出现在发布产物中，只有编译后的 CSS。

四、生成流程总览：generate 的完整调用链

将上述环节串起来，generator.rb 的 generate 方法执行顺序为：

cleanup_assets   # 删除旧 HTML 与 stylesheets/javascripts 目录
process_scss     # dartsass 编译 3 个 SCSS 入口
copy_assets      # 复制 assets/*（排除 stylesrc）
add_digests      # 为 CSS/JS 资产追加 MD5 摘要重命名
generate_guides  # 逐篇渲染 Markdown/ERB → HTML，并检查断链
generate_epub    # 仅当 EPUB=1 时打包 epub

其中 generate_guides 逐篇处理 source/ 下匹配 /\.(?:erb|md)\z/ 的文件：.md 经 RailsGuides::Markdown 渲染为 HTML，.erb 则直接走 ActionView 渲染（如首页等特殊页面，源码中跳过了 _license、_welcome、layout 三个模板）。渲染时传给视图的局部变量包含了第五节要讲的 direction（generator.rb）：

view = ActionView::Base.with_empty_template_cache.with_view_paths(
  [@source_dir],
  edge:          @edge,
  version:       @version,
  path:          output_file,
  epub:          "epub/#{epub_filename}",
  language:      @language,
  direction:     @direction,
  uuid:          SecureRandom.uuid,
  digest_paths:  @digest_paths
)

另外，lint 模式（GUIDES_LINT=1）下生成器进入 dry_run? 状态：不复制资产、不写任何文件，只解析生成的 HTML 检查页内锚点（<h\d id="...">）与 <a href="#..."> 的对应关系，发现断链时打印 “BROKEN LINK” 并利用 DidYouMean 给出修正建议（generator.rb）。

五、FAQ：三个设计决策的源码级解释

README 的 FAQ 部分回答了三个“为什么”，每一条都能在仓库中找到对应的代码证据。

5.1 为什么不用 CSS 变量（Custom Properties）

README 的官方解释：截至 2024 年 2 月，CSS 自定义属性不能在媒体查询或容器查询中使用（MDN 文档佐证），SCSS 变量在构建期插值，功能上可以达到类似目的，且能兼容更老的浏览器；未来 CSS 变量支持全面后应当切换到该方案。

从源码结构看，这一决策贯穿了整套样式：style.scss 中所有颜色、尺寸都是 $ 前缀的 SCSS 变量（构建期插值），而 include-media 的断点系统（$breakpoints）本质上就是“在构建期把断点值拼进 @media 查询字符串”——这正是 CSS 变量做不到的场景，因为媒体查询的条件值在 CSS 规范中不允许使用 var()。

5.2 为什么同时支持 LTR 与 RTL

README 解释：LTR/RTL（左到右/右到左）是依据展示语言的布局方向切换，阿拉伯语、波斯语是典型的 RTL 语言；当站点被自动翻译时，布局会水平镜像以贴合文字方向。

仓库中的落地方式非常直接——把方向作为构建参数而非运行时检测。generator.rb 中 @direction = direction || "ltr"（默认左到右），该值经视图局部变量注入布局模板，guides/source/layout.html.erb 的第 2 行和第 38 行分别写入了：

<html dir="<%= @direction %>" lang="en">
...
<body dir="<%= @direction %>" class="guide no-js">

配合 Rakefile 的 DIRECTION 环境变量，即可一键生成 RTL 版本的整套静态站点；而样式层的 dir 属性则让 CSS 可以通过 :dir(rtl) 等选择器或逻辑属性做镜像适配。

5.3 为什么暗色模式放在单独文件

README 的答案一句话：include-media 当时不处理 prefers-color-scheme，所以暗色模式被单独抽离出来。

对应代码即 guides/assets/stylesrc/_dark.scss：整个文件被包裹在一个裸写的媒体查询中，完全绕开 include-media：

// @include-media does not handle prefers-color-scheme
// so we are declaring this as an independent file with the overrides for dark mode.
@media (prefers-color-scheme: dark) {
  body.guide {
    background-color: $gray-1000;
    color: $text-on-darker-bg;
    ...

文件内的覆盖逻辑与 light 版一一对应：正文背景取最深灰阶 $gray-1000，文字用第五节 5.1 提到的 APCA 深色背景文字变量；链接改用更亮的 $rf-brand-lightest；表格斑马纹、代码块、滚动条、移动导航栏、插值提示框（note/tip/warning/question）全部换成 *-dark 变体。文件末尾由 style.scss 的 @import 'main'; @import 'dark'; 统一汇入主构建。这是一个值得借鉴的取舍：当第三方 SCSS 库不覆盖某个新特性（prefers-color-scheme 之于 include-media）时，与其等待上游，不如把例外隔离进单一文件，保持主样式与 vendor 库的干净边界。

5.4 语法高亮的明暗反转

与暗色模式相关的还有一个细节：highlight.scss 的注释明确说明配色策略做了反转——“浅色页面上用深色代码块，深色页面上用浅色代码块”。Pygments 输出的 token 类名（.k 关键字、.s 字符串、.gd/.gi diff 增删等）在这一套 SCSS 中逐一定义了色值，与 style.scss 的灰阶变量体系配套，保证代码块在明暗两种主题下都可读。

六、如何验证构建行为：测试用例

对构建链路的改动可以直接参考 guides/test/generator_test.rb 的写法：它在临时目录中搭一个最小 guides 骨架（一份 getting_started.md、一个 layout.html.erb、三个空的 SCSS 文件），预置若干“陈旧文件”与一个“必须保留的文件”，然后断言：

• 陈旧 HTML/CSS/JS 被清理、stylesheets 目录被重建；
• 非 HTML 文件（keep_me_test_file.txt）不受影响；
• 生成的 getting_started.html 非空；
• style、highlight、print 三个 SCSS 各自都有对应编译产物。

这为“修改 SCSS 后应如何验证编译链路”提供了可直接对照的验收清单。

七、小结：一次指南构建涉及的仓库文件地图

环节	关键文件
构建文档与操作说明	guides/README.md、guides/Rakefile
生成器核心	guides/rails_guides/generator.rb
SCSS 源（编辑入口）	guides/assets/stylesrc/style.scss、highlight.scss、print.scss、_dark.scss、components/_code-container.scss
vendor 依赖	vendor/_include-media.scss
布局模板（LTR/RTL 注入点）	guides/source/layout.html.erb
构建行为测试	guides/test/generator_test.rb

整套体系可以概括为：SCSS 负责构建期的一切计算（断点、变量、暗色覆盖），静态生成器负责增量渲染与缓存戳，方向与语言则是纯构建参数。任何一条 FAQ 中的“为什么”，最终都指向“构建期解决”这一统一原则——这也是 2024 改版样式体系最值得复用的经验。