• 数据集

Remote In Tech（remoteintech.company）是一个社区维护的开源远程友好科技公司目录，整个站点的数据源就是仓库src/companies/目录下数百个 Markdown 公司档案。本文以其中一份典型档案 sticker-mule.md 为完整案例，逐字段拆解档案文件的 frontmatter 元数据与正文章节结构，并深入对应源码说明这些字段如何被校验、分组、渲染成页面，帮助你在阅读或贡献档案时准确理解每一行的含义与约束。

档案概览：一份公司档案包含什么

Sticker Mule 是一家主打"快速定制印刷产品"的公司，其档案 sticker-mule.md 完整覆盖了目录中公司档案的两种组成：

1. YAML frontmatter（文件头部的---分隔块）：机器可读的元数据，包括标题、slug、官网、招聘页、地区、远程政策、公司规模、技术栈和日期；
2. Markdown 正文（##二级标题组织的内容）：人类可读的介绍，包括 Company blurb、Company size、Remote status、Region、Company technologies、Office locations、How to apply。

仓库的 CONTRIBUTING.md 明确指出，所有公司档案统一存放于src/companies/{slug}.md，且{slug}必须与 frontmatter 中的slug值一致——这正是 sticker-mule.md 文件名的由来。

frontmatter 字段逐一解读

Sticker Mule 档案的 frontmatter 是目录结构的标准模板，逐字段对照源码说明其约束与用途：

枚举值：单一事实来源 labels.js

region、remote_policy、company_size、technologies的所有合法取值并非散落在文档中，而是集中定义在 src/_data/labels.js 里。该文件注释明确说明它是"单一事实来源"（single source of truth），同时服务于两处消费方：JavaScript 通过 src/_data/companyHelpers.js 导入复用，Nunjucks 模板则经由 Eleventy 数据级联以labels.*形式全局访问。

技术标签的完整集合包含javascript、typescript、react、nodejs、python、ruby、go、java、php、rust、dotnet、elixir、scala、swift、cloud、devops、docker、kubernetes、mobile、data、ml、sql、postgres、nosql、search。可以看到 Sticker Mule 档案中的graphql是一个值得注意的点：该标签并不在labels.js的tech枚举中，渲染时会按 company.njk 中labels.tech[tech] or tech的回退逻辑直接显示原文graphql。

日期字段

addedAt和updatedAt表示档案的添加与更新时间。在 sticker-mule.md 中两者同为2022-10-05，说明该档案自添加以来未再更新。这两项直接决定两个站点功能：

• collections.js 的getRecentCompanies按addedAt倒序筛出最近添加的 12 家公司；
• company.njk 页脚在存在updatedAt时渲染 "Last updated: …"（经formatDate过滤器格式化为如October 5, 2022的样式）。

正文章节结构与必填约束

CONTRIBUTING.md 规定 Markdown 正文必须包含三个##章节：Company blurb、Remote status、How to apply。Sticker Mule 档案在此之上还提供了Company size、Region、Company technologies、Office locations等常用可选章节。

Company blurb：一句话讲清公司做什么

blurb 是全站自动生成页面 meta description 的来源。在 companies.11tydata.js 中，eleventyComputed.description会通过正则##\s*Company\s*blurb截取该章节文本，再做四步清洗：

1. 移除 Markdown 链接语法text只留文字；
2. 去掉*、_、反引号；
3. 换行折叠为空格；
4. 连续空格压缩为单个。

随后按 155 字符上限截断：优先在句号处截断（要求句号位置超过 50% 长度），否则在单词边界截断并补...。Sticker Mule 的 blurb 强调"秒级下单、数日收货、免费样稿与免费设计协助"，最终会被提炼为搜索结果页和分享卡片上的描述文字。

Remote status：远程现状的证据

Sticker Mule 的remote_policy: fully-remote与正文相互印证：团队分布在 17 个国家，覆盖美国、阿根廷、波黑、巴西、加拿大、克罗地亚、芬兰、法国、德国、危地马拉、印度、意大利、波兰、斯洛伐克、西班牙、瑞典和英国。这一字段值在页面头部会渲染为可点击的Fully Remote标签，链接到/browse/fully-remote/聚合页。

How to apply：引导求职者到招聘页

该章节通常放置公司官方招聘入口。在页面渲染时，company.njk 会取careers_url or website作为主按钮地址：存在careers_url时按钮文案为 "Apply Now"，否则为 "Visit Website"。注意按钮均带target="_blank"、rel="noopener noreferrer"与data-track-outbound属性，用于外链安全与出站统计。

源码视角：档案如何被校验、分组与渲染

1. 构建期校验：validate-companies.js

档案质量的保障来自 .github/scripts/validate-companies.js，它由.github/workflows/validate-companies.yml工作流在 PR 中自动运行。对每个src/companies/下的 Markdown 文件，该校验器会：

• 解析 YAML frontmatter（简易逐行解析，支持数组项）；
• 检查title、slug、website、region、remote_policy、company_size六个必填字段；
• 用与渲染同源的labels.js枚举校验region、remote_policy、company_size及technologies的每个标签；
• 校验slug与文件名一致（Sticker Mule 即满足sticker-mule对应sticker-mule.md）；
• 用new URL()校验website/careers_url必须是https:或http:协议；
• 用正则^##\s+<section>\s*$（多行模式）检查三个必填章节是否存在，并对空 blurb 给出警告。

任何错误都会导致 exit code 1，从而阻止合并，这就是"机器人自动注释并拦截 PR"的实现机制。

2. 数据分组：collections.js

collections.js 将全部档案按多种维度聚合：

• getAllCompanies：按标题字母序排成全量公司列表；
• getCompaniesByRegion：按region分组（Sticker Mule 会落入worldwide组）；
• getCompaniesByTech：按technologies逐项分组（它会同时出现在cloud、go、javascript、nosql、python、ruby、sql、devops等多个技术浏览页中）；
• getCompanyTags：聚合出技术、地区、远程政策三类标签页及其计数，供 browse/tag 页面使用。

3. 页面渲染：company.njk 布局

src/_layouts/company.njk 是公司页面的骨架，页面 schema 为Organization。其渲染逻辑与 frontmatter 字段一一对应：

• 头部h1输出title；
• 主按钮取careers_url or website；
• region渲染为/browse/{region}/链接的区域标签；
• remote_policy渲染为/browse/{remote_policy}/链接的政策标签；
• 正文内容经content | safe输出；
• 存在technologies时，额外渲染 "Tech Stack" 区块，每个标签链接到对应技术浏览页；
• 页脚显示 "Last updated" 日期与编辑入口链接。

档案的持续维护：链接健康检查

远程公司档案中website、careers_url及正文内嵌链接会随时间失效，仓库为此提供了 scripts/check-links.sh 链接检查脚本。它以 CSV 形式输出每个 URL 的解析结果、最终状态码与说明：

• --refresh：重新从全部档案的 frontmatter 与正文中提取 URL；
• --quick：仅复检上次非 OK 的 URL，保留已通过的记录；
• 默认模式：全量检查。

检查通过 curl 跟随重定向（-L），区分 404（broken link）、403/401（可能拦截爬虫）、5xx（服务器错误）等状态；Sticker Mule 档案中的官网与招聘页地址正是这类脚本持续监控的对象，保证目录链接长期可用。

结语：一份档案，一套完整流水线

从 sticker-mule.md 这一份档案可以看到 Remote In Tech 目录的全部设计脉络：frontmatter 是机器可读的数据契约，由 labels.js 统一约束枚举、validate-companies.js 在 PR 期强制校验；正文章节是面向求职者的内容载体，由 companies.11tydata.js 自动提炼 meta 描述；最终 company.njk 与 collections.js 把结构化数据渲染成可浏览、可检索、可按地区与技术过滤的页面，再配合 check-links.sh 持续保障外链健康。理解这套档案格式，你既能快速读懂目录中任意一家公司，也能按 CONTRIBUTING.md 的模板向目录贡献新档案。

• 数据集