企业官网建设流程全解析

• 云原生

本指南是 Apache Mesos 项目中所有“非代码文档”的统一书写规范，规定了docs/目录下 Markdown 用户指南在标题大小写、代码块、强调、表格、空行等方面应遵循的约定，并解释了这些 Markdown 文件如何经 Middleman + Doxygen 流水线渲染为线上文档。读完本文后，你将掌握编写符合 Mesos 文档规范的 Markdown 页面的全部规则，并能理解从仓库docs/目录到最终站点页面的完整生成机制，使你的文档改动一次通过评审。

风格指南的定位与适用范围

Mesos 的文档体系分为三类（见 Documentation Guide）：Markdown 用户指南、Doxygen API 文档、以及普通源码注释。本文所述的风格指南专门约束第一类——即存放在docs/文件夹中的用户指南与非代码技术文档。这些 Markdown 文件会被渲染为线上文档（mesos.apache.org/documentation/latest/）。指南本身在 docs/home.md 的开发者资源列表中与 Doxygen Style Guide、C++ Style Guide 并列，是贡献者必须遵循的写作规范之一。

注意：原文档声明该指南仍在完善中（work in progress），仓库中部分存量文档可能尚未完全符合本规范。编写新文档时应以本指南为准，修订旧文档时也应向此规范靠拢。

此外，Mesos 文档在措辞上遵循 RFC 2119 的语义约定：must、should、can等词汇具有严格的约束强度含义（见 Documentation Guide 的 Conventions 一节），撰写文档时应保持这一语义一致性。

What to Document：什么值得写文档

指南给出的两条核心原则是：

1. 任何新的实质性功能（substantial feature）都应在其独立的 Markdown 文件中获得文档，而不是塞进既有页面。
2. 保持代码与文档的关联可见：如果从源码跳转到文档的链接不明显，应在相关代码中插入一条简短注释，说明存在需要同步维护的非代码文档，并指明它的位置。

与之配套的是“文档与代码同步”要求：修改代码时必须评估是否需要更新文档，尤其是引入新命令行 flag 或修改现有 flag 时，必须在 docs/configuration.md 中有对应反映。configuration.md是入口索引，实际 flag 表格分散在 docs/configuration/master.md、docs/configuration/agent.md、docs/configuration/master-and-agent.md 等页面中，这些页面正是 HTML 表格规范（下文详述）最集中的落地场景。

Section Headings：章节标题使用 Title Case

章节标题（section headings）应使用 Title Case（标题式大小写），指南推荐 APA 风格变体，具体规则为：

• 标题（含标题、副标题、子标题）的第一个单词首字母必须大写；
• 标题中所有“主要”单词（名词、动词、形容词、副词、代词）首字母大写，连字符主要词的第二部分同样大写（例如Self-Report而不是Self-report）；
• 五个字母及以上的单词一律大写首字母。

换言之，只有四类“次要”单词可以小写：连词（如and、or、nor、but）、冠词（a、an、the）、介词（如as、at、by、for、from、in、of、on、per、to、with），且仅限四个字母及以下；它们不能作为标题的第一个单词出现。

从仓库现状看，现有配置文档的标题正是这一规则的体现，例如 docs/configuration.md 中的Master and Agent Options、Autotools Options、CMake Options——介词and小写，其余主要词与五个字母以上的词均大写。

Code Examples：代码块的围栏语法与 Doxygen 限制

C++ 代码示例应使用带cpp语言标注的围栏代码块：

~~~{.cpp} int main(int argc, char** argv) { .... } ~~~

原文档中该示例本身采用了四空格缩进，这正是下一条限制的直接体现：由于 Doxygen 的 Markdown 解析器存在缺陷，当前所有非 C++ 的代码块统一改用缩进（而非围栏）包裹。

这条限制有明确的工程背景：Mesos 的 API 文档由 Doxygen 从源码与main.dox统一生成，Doxyfile 的INPUT配置同时包含了../include/、../src/与../src/main.dox，而 src/main.dox 将 API 文档页与整体文档站点串联在一起。因此 Markdown 内容会被两套渲染器（Middleman 站点与 Doxygen）先后处理，风格规则实际上是为“两者都能正确解析”而设计的折中方案。

从仓库现状看，~~~{.cpp}围栏在较新的文档中已广泛使用，例如 docs/reconciliation.md、docs/health-checks.md 中的 C++ 示例，以及 docs/app-framework-development-guide.md 中的~~~{.proto}与~~~{.sh}块，均与本指南的写法一致。

Notes、Emphasis 与行内高亮

指南定义了三层行内强调约定：

1. 醒目提示（NOTE）——用于突出正文中重要的部分，格式为加粗的**NOTE:**前缀：

**NOTE:** Short note. Continued longer note.

2. 单个标识符高亮——用单反引号突出句中的特定标识符（类型名、类名等）：

Use the default `HierarchicalDRF` allocator....

3. 命令高亮——示例命令同样使用单反引号：

`mesos-master --help`

4. 文件与路径——文件、路径引用使用单反引号，支持file://形式与绝对路径形式：

Remember you can also use the `file:///path/to/file` or `/path/to/file`

docs/configuration.md 的开头就是这一约定在实战中的直接应用：mesos-master --help、--option_name=value、MESOS_OPTION_NAME、file://path/to/file全部以单反引号行内高亮。

Tables：表格必须写成 HTML

为了避免 Markdown 表格在渲染时出现格式问题，指南要求直接用 HTML 书写表格，并给出标准模板（table table-striped为站点 Bootstrap 样式的斑马纹表格）：

<table class="table table-striped"> <thead> <tr> <th width="30%"> Flag </th> <th> Explanation </th> </thead> <tr> <td> --ip=VALUE </td> <td> IP address to listen on </td> </tr> <tr> <td> --[no-]help </td> <td> Prints this help message (default: false) </td> </tr> </table>

这一规则在仓库中有大量落地证据：docs/configuration/master.md 中每个 flag 都遵循Flag（列宽 30%）/Explanation两列结构，且带锚点的<tr id="quorum">等写法便于按 flag 名定位；docs/configuration/master-and-agent.md、docs/isolators/cgroups-cpu.md、docs/isolators/network-port-mapping.md 等页面也统一使用<table class="table table-striped">。撰写 flag 文档时应严格沿用这一结构。

Indentation and Whitespace：缩进与空行

指南对空白字符的规定很严格：

• Markdown 文件内不使用额外缩进；
• 章节标题之后一个空行；
• 章节与章节之间两个空行。

原文给出的示范结构如下：

... end of previous section. ## New Section Beginning of new section ....

这一约定保证了 Doxygen 与 Middleman 两套解析器对段落边界识别一致，也是评审时格式检查的常见依据。

渲染流水线：从 docs/ 到线上文档

理解风格规则“为什么必须这样写”的关键，在于 Mesos 的文档生成流水线。以下机制均可在仓库源码中得到确认：

1. 站点构建使用 Middleman。site/config.rb 中配置了 Markdown 引擎与关键选项：

set :markdown_engine, :rdiscount set :markdown, :layout_engine => :erb, :tables => true, :autolink => true, :smartypants => true, :fenced_code_blocks => true

其中fenced_code_blocks: true解释了~~~{.cpp}围栏语法在站点侧可以被正确渲染，而page "/documentation/*", :layout => "documentation"则解释了为何每篇docs/文档的 YAML front matter 都携带layout: documentation——docs/markdown-style-guide.md 自身的文件头即为：

--- title: Apache Mesos - Markdown Style Guide layout: documentation ---

2. docs/ 目录被整体同步进站点源目录。site/Rakefile 的update_docs任务（约 L20-L71）完成了四件关键工作：

• 将docs/**（排除docs/images）拷贝到site/source/documentation/latest/；
• 由于 Middleman 对xxx.json.md这类文件名的限制，把**/*.json.md迁移为**/*.json/index.md；
• 用正则批量改写文档内相对链接：(xxx.md#anchor)重写为/documentation/latest/<目录>/xxx/#anchor，<a href="xxx.md">同样处理，images/...路径重写为/assets/img/documentation/...；
• 将home.md移动为latest.html.md，并把docs/images/拷贝到site/source/assets/img/documentation/。

这也解释了风格指南中“表格用 HTML、图片用相对路径”的原因：这些链接会在发布前被脚本机械地重写，写法不规范的链接会直接失效。

3. 本地开发与构建。按 site/README.md 的流程：先按构建说明编译 Mesos，运行support/generate-endpoint-help.py生成 HTTP 端点帮助页，然后执行./site/mesos-website-dev.sh启动 Docker 容器与 Middleman 开发服务器，在http://localhost:4567预览站点；该流程同时生成 Doxygen 与 Javadoc 输出，可分别在/api/latest/c++/index.html与/api/latest/java/index.html查看。Rakefile 的doxygen任务即调用doxygen ../Doxyfile并把 HTML 输出移入site/source/api/latest/c++，这正与风格指南中“非 C++ 代码块改用缩进”的 Doxygen 限制相互印证。正式发布由 ASF Jenkins 的 Mesos-Websitebot 任务完成（见 support/jenkins/websitebot.sh），开发者本人无需手工发布。

编写文档的实操清单

结合上述规范，向docs/提交新页面或修改现有页面时，可按以下清单自检：

1. 内容层面：新功能是否有独立 Markdown 文件？代码中是否留下了指向文档的同步注释？flag 变更是否同步到了docs/configuration/下的表格？
2. Front matter：是否包含title（Apache Mesos - <页面名>格式）与layout: documentation？
3. 标题：章节标题是否遵循 APA Title Case（首词大写、主要词大写、五个字母以上词大写，介词/连词/冠词小写且不作首词）？
4. 代码块：C++ 用~~~{.cpp}围栏；非 C++ 块遵循当前的缩进约定以兼容 Doxygen 解析器。
5. 强调：重要提示用**NOTE:**前缀；标识符、命令、路径用单反引号，如`mesos-master --help`。
6. 表格：一律使用<table class="table table-striped">HTML 结构，flag 列固定 30% 宽度。
7. 空白：不额外缩进；标题后一个空行，章节之间两个空行。
8. 链接与图片：文档内相对链接与images/相对路径按现有文档写法书写，发布流水线会自动重写为站点绝对路径。

遵循以上约定，你的文档既能通过代码评审的格式检查，也能在 Middleman 站点与 Doxygen API 文档两条渲染路径下都呈现正确。

• 云原生