• 文档
• 教程

Learn X in Y Minutes（learnxinyminutes-docs）是一个以"可运行的带注释代码"形式讲解编程语言与工具的开源文档仓库，本指南面向想要向该仓库提交内容的贡献者，完整覆盖贡献流程、写作风格规范、Frontmatter 头部元数据配置、语法高亮与编码要求，以及如何在本地构建站点预览自己的文章。读完本文，你将能按照仓库的既定规范撰写或翻译一篇教程、正确填写元数据、通过仓库自带的 lint 校验并构建出可浏览的本地站点。

贡献的基本原则与流程

CONTRIBUTING.md 明确欢迎一切形式的贡献，从最小的拼写修正到一篇全新的文章都在接受范围内；多语言翻译同样欢迎，甚至不限于翻译——任何语言的原创文章都可以。提交方式不限时间，随时可以通过 Pull Request（PR）或 Issue 提出。

为了帮助维护者快速定位与自己相关的提交，仓库要求在 Issue 和 PR 的标题前加上[language/lang-code]标签，例如英文 Python 教程写作[python/en]，中文 Python 教程写作[python/zh-cn]等。这个约定在 README.md 的 Contributing 一节中同样被强调，属于提交时的硬性规范。

此外，如果一次提交涉及多个重大变更（例如同时翻译两种不同语言的文章），强烈建议为每个变更单独发起一个 PR，这样审查者可以更有效地逐个审阅，也便于单独合并。

写作风格规范（Style Guidelines）

仓库对文章写作风格提出了四条明确要求，这些要求共同保证了所有教程在排版和表达上的统一性：

行宽不超过 80 字符

代码块内的行长度应控制在 80 字符以内，否则文本会在渲染时溢出，影响阅读体验。这一约束（以及下文其他格式一致性问题）由 markdownlint 这类工具识别。

示例优先于说明

尽量用最少的文字表达，所有场景下都优先使用代码示例而非大段叙述。这正是本仓库的核心形态：每篇教程本身就是"一份带注释的、可运行的代码"。

避免赘述（Eschew surplusage）

仓库欢迎新手，但目标读者是"有一定经验的程序员"。因此应避免解释与语言本身无关的基础概念，只解释该语言特有的知识点。文章要保持简洁、可快速扫读——正如文档所说，"我们都知道怎么用 Google"。

统一使用 UTF-8 编码

所有 Markdown 文件必须使用 UTF-8 编码，这一要求由仓库自带的 lint 脚本强制执行（详见下文"编码与格式校验"一节）。

Frontmatter 头部元数据配置

站点会从这些 Markdown 文件生成 HTML 页面，而 Markdown 正文之前可以包含一段额外的元数据，称为frontmatter。它采用 YAML 格式，夹在两条---分隔线之间，位于文件最顶部。

英文编程语言文章必填字段

• name：编程语言的人类可读名称（如Ruby、Python）；
• contributors：贡献者名单，是一个由[*作者*, *URL*]组成的列表，其中 URL 可选。

可选字段

• category：文章分类，目前可选值为language（语言）、tool（工具）或Algorithms & Data Structures（算法与数据结构），省略时默认为language。实际仓库中，amd.md、awk.md、docker.md 等使用category: tool，dynamic-programming.md 使用category: Algorithms & Data Structures；
• filename：文章代码对应的文件名，站点会抓取该文件、拼接合并并提供下载。

翻译文章附加字段

• translators：译者名单，同样是[*译者*, *URL*]列表，URL 可选。

非英文文章会继承对应英文文章（如果存在）的 frontmatter 值，但可以覆盖。这一特性在仓库中有大量实例：例如 zh-cn/python.md 只声明了contributors和translators，正文则是完整的中文翻译；而 bf.md 额外使用了where_x_eq_name: brainfuck这一字段（frontmatter 校验脚本允许的键之一，用于把文件名中的通配符映射到具体语言名）。

官方示例：Ruby 的头部配置

CONTRIBUTING.md 给出的标准示例：

--- name: Ruby filename: learnruby.rb contributors: - ["Doktor Esperanto", "http://example.com/"] - ["Someone else", "http://someoneelseswebsite.com/"] ---

对照仓库中真实的 ruby.md 文件，其 frontmatter 结构完全一致：name: Ruby、filename: learnruby.rb，并带有一长串contributors列表，每个成员都是一个["姓名", "URL"]二元组。这就是一篇标准教程头部的实际形态。

Frontmatter 的源码级校验规则

为了让贡献者提前发现 frontmatter 错误，仓库在 lint/frontmatter.py 中实现了一套自动校验器，其核心规则与写作规范一一对应：

• 允许的键白名单：仅允许name、where_x_eq_name、category、filename、contributors、translators这六个键，出现其他键会报Invalid keys found错误（lint/frontmatter.py）；
• 键的类型约束：name、where_x_eq_name、category、filename必须是字符串；contributors和translators必须是列表（lint/frontmatter.py）；
• 列表成员结构约束：contributors/translators中的每一项本身必须是列表，长度为 1 或 2，第一项必须是字符串（作者/译者名），第二项（如果存在）也必须是字符串（URL）（lint/frontmatter.py）；
• YAML 语法检查：frontmatter 内容会先经 yamllint 做语法级 lint（并关闭了缩进、行宽等与元数据无关的规则），再进行上述结构校验（lint/frontmatter.py）。

该脚本既可以针对单个文件运行，也可以递归处理整个目录下的所有.md文件（lint/frontmatter.py），任何文件出错时进程以非零码退出，便于接入 CI。运行它所需的依赖记录在 lint/requirements.txt 中，仅有yamllint与pyyaml两个包。

语法高亮与编码要求

语法高亮使用 Pygments

站点使用 Pygments 进行代码语法高亮，因此文章代码块的语言标识需要能被 Pygments 识别。这意味着在 Markdown 代码围栏中应使用 Pygments 支持的 lexer 名称（如ruby、python、bf等），以保证渲染后的高亮效果正确。

编码与 BOM 校验脚本

仓库的 lint/encoding.sh 提供了另一层质量保障，它并行检查所有.md文件：

• 使用file -b --mime-encoding读取文件编码，仅允许utf-8与us-ascii两种（lint/encoding.sh）；
• 若文件为 UTF-8，则进一步检查文件开头是否带有 UTF-8 BOM（EF BB BF），一旦发现 BOM 即报错（lint/encoding.sh）。

这与风格规范中"统一使用 UTF-8"的要求互为印证：规范文字负责说明"为什么"，lint 脚本负责给出"怎么查"。脚本默认以当前目录为参数，也支持传入指定目录（lint/encoding.sh）。

是否把自己加入贡献者名单？

如果你希望把自己加入contributors字段，请记住：贡献者列表是"平权"的（equal billing），而第一位贡献者通常是整篇文章的作者。因此请自行判断你的贡献是否构成实质性的内容增补，再决定是否署名，避免将细微改动也列入名单。

本地构建站点并预览

CONTRIBUTING.md 提供了完整的本地构建流程，用于在提交前预览文章的实际渲染效果：

1. 安装 Python：macOS 可用 Homebrew 安装：

brew install python

2. 克隆两个仓库：站点工程与文档仓库（本仓库），并将文档仓库嵌套克隆进站点工程的源码目录：

# 克隆站点工程 git clone https://github.com/adambard/learnxinyminutes-site # 克隆本文档仓库（替换为你的用户名），嵌套进站点工程 git clone https://github.com/<YOUR-USERNAME>/learnxinyminutes-docs ./learnxinyminutes-site/source/docs/

3. 安装依赖并运行构建：

cd learnxinyminutes-site pip install -r requirements.txt

4. 启动本地 HTTP 服务：

python build.py cd build python -m http.server

5. 在浏览器中访问http://localhost:8000/即可查看渲染后的站点。

从源码结构看，站点生成逻辑位于learnxinyminutes-site工程内，文档仓库只是其source/docs/目录下的内容源；而本仓库自带的 lint/ 目录则承担了提交前的静态校验职责，二者共同构成了"本地预览 + 自动校验"的完整工作流。对于本仓库的日常使用，你可以在任意时刻直接运行 lint/frontmatter.py 校验全部 Markdown 文件的元数据，运行 lint/encoding.sh 校验全部文件的编码，两者结合即可在提交 PR 前完成一次全面的格式自检。

• 文档
• 教程