企业官网建设流程全解析

• 文档
• 开发工具
• 静态站点

Slate 是一个把 API 文档生成做到极致的静态站点生成器：左侧是接口描述、右侧是代码示例、顶部是多语言 Tab 切换，整份文档就是一个滚动、可锚点跳转的单页。本文以 README.md 为核心骨架，结合仓库内 config.rb、slate.sh、deploy.sh、Dockerfile、Vagrantfile 以及lib/下的源码实现，讲清楚从零搭建、编写文档、理解内部机制到一键部署 GitHub Pages 的完整链路，读完你可以直接照搬到自己的 API 项目。

核心特性：为什么用 Slate 写 API 文档

Slate 的设计目标很明确——让 API 文档"写起来是 Markdown，看起来是专业文档站"。它的核心特性可以归纳为以下几点：

• 干净、直观的双栏设计：文档左侧是 API 的描述文字，右侧是代码示例，这一布局灵感来自 Stripe 和 PayPal 的 API 文档。同时整站是响应式的，在平板、手机甚至打印场景下都能正常呈现。
• 所有内容集中在一个单页：用户不必在几十个页面之间来回翻找。Slate 没有牺牲链接能力——滚动时浏览器地址栏的 hash 会自动更新到最近的标题锚点，因此可以自然、方便地链接到文档中的任意位置（该机制由 lib/unique_head.rb 实现，详见下文）。
• 就是纯粹的 Markdown：写 Slate 文档就是写 Markdown，连代码示例本身也只是 Markdown 代码块，编辑和学习成本极低。
• 多语言代码示例一键切换：如果 API 提供了多种语言绑定，可以像 GitHub Flavored Markdown 一样在代码块顶部指定语言名，Slate 会自动生成切换 Tab。
• 开箱即用的语法高亮：基于 Rouge 支持 100 多种语言的语法高亮，无需任何额外配置；仓库内置了定制的 Monokai Sublime 主题（见 lib/monokai_sublime_slate.rb）。
• 自动滚动定位的目录：页面最左侧的目录会随滚动高亮当前所处章节。该实现基于 Nokogiri 解析渲染后的 HTML 生成嵌套目录（见 lib/toc_data.rb），官方在 TripIt 的实际文档中目录超过 180 个条目时性能依然优秀。
• 协作友好、托管简单：默认情况下生成的文档可以托管在公开的 GitHub 仓库，借助 GitHub Pages 免费托管，社区开发者可以直接提 Pull Request 修正拼写或内容错误；当然也完全可以把产物部署到任何其他静态托管平台。
• RTL 布局支持：内置完整从右到左的布局，适用于阿拉伯语、波斯语（Farsi）、希伯来语等从右往左阅读的语言（对应样式实现见 source/stylesheets/_rtl.scss）。

快速开始：三种运行方式

Slate 可以在三种环境下运行：本机原生运行（Ruby）、Vagrant 虚拟机、Docker 容器。仓库根目录的 README.md 把这三种方式并列列出，下面分别给出对应配置文件与实操命令。

方式一：本机原生运行

依赖声明在 Gemfile：核心是 Middleman~> 4.4静态站点框架、Redcarpet~> 3.6.0Markdown 渲染器、Rouge~> 3.21语法高亮器、Nokogiri（用于目录解析）等，要求 Ruby>= 2.6。

bundle install # 安装依赖 bundle exec middleman server # 启动本地开发服务器

也可以直接使用仓库自带的统一入口脚本 slate.sh：

./slate.sh serve # 启动 Middleman 开发服务器 ./slate.sh build # 构建静态文件

开发服务器默认监听4567端口（见 config.rb 中的set :port, 4567），访问http://localhost:4567即可预览文档，修改source/下的 Markdown 文件后页面会热更新。

方式二：使用 Vagrant

仓库提供了 Vagrantfile，基于ubuntu/focal64镜像，自动安装 Ruby、Node.js、Git 以及 Nokogiri 所需的系统库，并把宿主机4567端口转发到虚拟机内的 4567：

vagrant up

启动后 Vagrant 会自动执行bundle exec middleman server --watcher-force-polling --watcher-latency=1，日志写入虚拟机内的~/middleman.log，然后访问http://localhost:4567即可。

方式三：使用 Docker

仓库提供了 Dockerfile：基于ruby:2.6-slim镜像，工作目录为/srv/slate，暴露4567端口，容器的ENTRYPOINT是 slate.sh，默认CMD为build。因此构建镜像后直接运行即可获得构建产物：

docker build -t slate . docker run --rm -p 4567:4567 slate # 默认执行 build docker run --rm -p 4567:4567 slate serve # 以开发服务器模式运行

如果需要把构建产物输出到宿主机，可以挂载build目录：

docker run --rm -v "$PWD/build:/srv/slate/build" slate build

编写文档：一切从 source 目录开始

所有文档源码都放在source/目录下。仓库自带的示例文档是 source/index.html.md，它同时充当了 Slate 编写规范的活教材。该文件开头有一段 YAML frontmatter，控制着文档站的各种开关：

--- title: API Reference language_tabs: # 必须是 Rouge 支持的语言之一 - shell - ruby - python - javascript toc_footers: - <a href='#'>Sign Up for a Developer Key</a> includes: - errors search: true code_clipboard: true meta: - name: description content: Documentation for the Kittn API ---

各配置项的作用如下（与 source/layouts/layout.erb 中的读取逻辑一一对应）：

用includes拆分文档

当文档很长时，Slate 允许把内容拆成多个文件：只要把子文件保存到source/includes/目录（文件以下划线开头，如_errors.md），再在 frontmatter 的includes列表里按顺序引用即可。仓库自带的 source/includes/_errors.md 就是一个范例——它用一张 Markdown 表格罗列了 API 的各个错误码及其含义（400、401、403、404、405、406、410、418、429、500、503 等）。文件中还演示了<aside class="notice">提示框的用法：

<aside class="notice"> This error section is stored in a separate file in <code>includes/_errors.md</code>. </aside>

多语言代码示例：语言 Tab 从何而来

在 Markdown 正文中，只要连续编写多个不同语言标记的围栏代码块，Slate 就会在右侧把它们组织成可切换的 Tab。例如 source/index.html.md 中的认证示例同时给出了 Ruby、Python、Shell、JavaScript 四种写法，与 frontmatter 里language_tabs的声明顺序一致。

其底层实现在 lib/multilang.rb：Multilang#block_code先按--拆分代码块语言名（支持ruby--自定义名这种带别名写法，高亮仍用--前的真实语言），再在渲染出的<div class="highlight ...">上追加tab-语言名的类名，前端脚本 source/javascripts/app/_lang.js 据此完成 Tab 切换与高亮联动。注意语言名必须来自 Rouge 支持的语言列表，否则高亮会退化。

源码级机制解析：单页、锚点与目录是如何实现的

Slate 的"单页 + hash 锚点 + 滚动目录"体验背后是几个小而精巧的 Ruby 模块，都在lib/目录下，可以通过 config.rb 的配置追踪它们的接入点。

唯一标题生成（unique_head）

config.rb 为 Redcarpet 指定了自定义渲染器UniqueHeadCounter（定义在 lib/unique_head.rb）。它会在渲染每个标题时：

1. 去掉标题中的 HTML 标签并parameterize成 URL 友好的 slug；
2. 用计数器记录 slug 出现次数，重复标题自动追加-2、-3后缀，保证每个锚点唯一；
3. 遇到中文、俄文等parameterize会清空的字符时，回退为标题文本 SHA1 哈希的前 10 位作为 id——这正是 README 所说"滚动时浏览器 hash 自动更新到最近标题"的基石。

仓库还提供了另一个实现 lib/nesting_unique_head.rb（NestingUniqueHeadCounter），它会为子标题生成带父级前缀的嵌套 id（如intro-usage），适合需要更强层级语义的文档站，可按需在 config.rb 中切换renderer。

目录树生成（toc_data）

lib/toc_data.rb 定义了一个在 config.rb 的helpers块中引入的toc_data(page_content)函数：它用 Nokogiri 把渲染后的 HTML 解析成文档片段，抽取h1、h2、h3标题及其id，然后自底向上把低层级标题嵌套进最近的高层级标题，最终生成一棵多级目录树，交给前端 source/javascripts/app/_toc.js 渲染成左侧可滚动、可高亮当前位置的目录。

语法高亮主题（monokai_sublime_slate）

config.rb 中activate :syntax启用代码高亮，仓库自带主题定义在 lib/monokai_sublime_slate.rb：它基于 Rouge 官方 Monokai Sublime 主题改造——去掉了背景色，并把 JSON 键的配色改为柔黄色（soft_yellow），让右侧代码区域的观感更贴合 Slate 的整体设计。

构建与部署

本地构建

./slate.sh build

其内部等价于bundle exec middleman build --clean --watcher-disable（见 slate.sh 的run_build）。构建产物输出到build/目录。构建阶段 config.rb 还会做以下优化：

• activate :minify_css与activate :minify_javascript：压缩 CSS 与 JS；
• activate :asset_hash：为静态资源生成内容哈希文件名（专门排除了.woff/.woff2，规避字体资源哈希错配的已知问题）；
• activate :relative_assets与set :relative_links, true：所有资源与链接改为相对路径，这是发布到 GitHub Pages 子路径所必需的；
• activate :autoprefixer：自动为 CSS 补充浏览器前缀（目标为最近两个大版本与 Firefox ESR）。

一键部署到 gh-pages

Slate 的部署哲学是"把构建产物推到gh-pages分支"，配合 GitHub Pages 即可免费托管。仓库为此提供了两套脚本：

• slate.sh：统一入口，./slate.sh deploy会先构建再部署；支持--no-build（只部署不构建）、-m/--message（自定义提交信息）、-n/--no-hash（不在提交信息中追加源 commit 哈希）、-e/--allow-empty（允许部署空目录）等参数。
• deploy.sh：独立部署脚本，额外提供--source-only（只构建不推送）与--push-only（只推送不构建）。

两者共享同一套部署逻辑，要点包括：

• 默认部署分支为gh-pages、部署目录为build/，均可在脚本内或通过环境变量调整；
• 若远端已存在gh-pages分支会先git fetch --force同步，再执行增量部署，避免覆盖远端他人提交；无该分支则用checkout --orphan创建孤儿分支做首次部署；
• 默认提交信息为publish: <最近一次提交标题>，并追加generated from commit <hash>便于溯源；
• 推送时使用--quiet且对命令输出做了过滤，避免在日志中泄露含 token 的仓库 URL。

整个流程（原生运行、Vagrant、Docker、部署）都集中在仓库根目录的几个配置与脚本文件中，配合 config.rb 即可完整掌控从 Markdown 到线上文档站的每个环节。

小结

Slate 的价值在于把"API 文档工程"压缩成了几个固定套路：frontmatter 声明language_tabs与includes，正文写 Markdown 围栏代码块，然后slate.sh serve预览、slate.sh build构建、slate.sh deploy发布。配合仓库内lib/下唯一标题生成、目录树解析、多语言 Tab、Monokai 主题等源码，你可以深入理解每一处体验背后的实现，并针对自己的项目做二次定制。如果想快速上手，直接以本仓库为模板，改写 source/index.html.md 的 frontmatter 与正文即可。

• 文档
• 开发工具
• 静态站点