• 数据集

本文以社区维护的远程友好科技公司目录Remote In Tech（源码仓库 remote-jobs）中的 Drupal Jedi 公司档案 为样本，系统讲解公司档案 Markdown 文件的 frontmatter 字段规范、正文章节结构、技术栈标注规则，并深入追踪该档案从原始数据到最终公司页面的完整 Eleventy 构建链路。读完本文，你将掌握如何解读目录中任意一家公司的档案，也具备新增或维护公司档案的完整实操能力。

一、档案速览：一条 65 人远程团队的完整记录

src/companies/drupal-jedi.md是目录中数百份公司档案的标准样本之一。Drupal Jedi 是一家专注构建高级 Web 应用（advanced web apps）的机构（agency），团队规模 65 人，面向全球招聘，采用完全远程（fully remote）的工作模式。整份档案由两部分构成：位于文件顶部的 YAML frontmatter（结构化元数据）和 Markdown 正文（人类可读的公司介绍）。

该文件在仓库中的原始内容如下（frontmatter 部分）：

--- title: "Drupal Jedi" slug: drupal-jedi website: https://drupaljedi.com/ careers_url: https://drupaljedi.com/careers region: worldwide remote_policy: fully-remote company_size: medium technologies: - devops - go - javascript - php addedAt: 2018-06-14 updatedAt: 2018-06-14 ---

正文部分则包含六个##章节：Company blurb（公司简介）、Company size（公司规模 65 人）、Remote status（远程状态）、Region（招聘地区 Worldwide）、Company technologies（公司技术栈）以及How to apply（申请方式）。

这份档案的字段取值完全符合 CONTRIBUTING.md 中定义的有效值枚举，是研究公司档案格式规范的最佳参考案例。

二、frontmatter 字段逐项解读：数据从哪来、有何约束

公司档案的核心是结构化 frontmatter。依据 CONTRIBUTING.md 的字段定义，逐一解读 Drupal Jedi 档案中的每个字段：

值得注意的细节是：company_size: medium与正文## Company size中标注的"65"形成互补——frontmatter 使用区间档位（51-200 人归为 medium，见 labels.js 中的定义），正文则保留精确数字，两者同时服务于不同的渲染场景。

技术标签同样是受控枚举。labels.js 是标签的"单一事实来源"（single source of truth），定义了完整的合法技术列表，包括javascript、go、php、devops、docker、kubernetes等。Drupal Jedi 档案中的四个标签全部落在合法集合内。

三、正文章节结构：六段式公司档案模板

公司档案的 Markdown 正文需包含规定的##章节。Drupal Jedi 档案完整呈现了这套结构：

• ## Company blurb（必填）——公司简介。原文指出：Drupal Jedi 是一家专注构建高级 Web 应用的领先机构，始终追求最佳解决方案，提倡"为正确的任务使用正确的技术"（use the right technology for the right task），因此"Drupal 与现代 JS 框架的混合"是其首选技术组合。
• ## Company size（可选）——精确团队规模：65 人。
• ## Remote status（必填）——远程工作方式：正在全球范围内扩充团队，寻找各地人才。
• ## Region（可选）——招聘地区：Worldwide（全球）。
• ## Company technologies（可选）——按后端/前端/DevOps 分层的技术清单：
  • Backend：Drupal、Go、NodeJS
  • Frontend：React、Angular、VueJS
  • DevOps：k8s、docker
• ## How to apply（必填）——申请指引：引导求职者前往 careers 页面获取详细信息（drupaljedi.com/careers）。

注意## Company technologies章节的粒度比 frontmatter 的technologies字段更细——正文细分了具体框架（React、Angular、VueJS、NodeJS），而 frontmatter 只保留目录索引所需的粗粒度标签（javascript、go、php、devops）。这正是"面向读者的正文"与"面向索引的元数据"分工的体现。

四、技术栈解读：Drupal 与现代 JS 框架的混合模式

Drupal Jedi 的技术组合在远程 Web 开发机构中很有代表性，其核心思路是"混合架构"（mix of Drupal with modern JS frameworks）：

• 后端体系：以 Drupal（PHP 生态的内容管理系统）为内容与业务底座，辅以 Go 处理高并发或专用服务，NodeJS 承担 API 层或工具链职责。
• 前端体系：React、Angular、VueJS 三大主流框架并列——从档案表述看，团队推崇"为正确任务选择正确技术"，因此在不同项目中按需选用不同前端框架。
• DevOps 体系：k8s（Kubernetes）与 docker 构成容器化部署链路。

在目录层面，这套技术栈被抽象为 frontmatter 中的四个枚举标签。构建时，每个标签会生成对应的技术浏览页入口（详见下文构建链路），求职者可以通过 collections.js 中getCompaniesByTech生成的技术分组，找到所有使用 Go、PHP、JavaScript 或 DevOps 的远程公司。

五、从档案到页面：Eleventy 构建链路逐级追踪

一份公司档案最终渲染成线上公司详情页，要经过 Eleventy 的完整数据处理管线。以 Drupal Jedi 档案为线索，逐级追踪：

5.1 指定布局：companies.json

src/companies/companies.json是目录级数据文件，为src/companies/下所有公司档案统一指定布局：

{ "layout": "company" }

它相当于目录级"默认配置"，让每一份公司档案（包括 Drupal Jedi）自动套用 company.njk 布局，无需在每个文件里重复声明。

5.2 页面渲染：company.njk

company.njk 是公司详情页的 Nunjucks 模板，它消费 frontmatter 字段并输出完整页面，关键渲染逻辑包括：

• 申请按钮（company.njk#L11-L16）：优先使用careers_url作为按钮跳转地址，按钮文案为 "Apply Now"；若不存在careers_url则回退到website，文案变为 "Visit Website"。Drupal Jedi 档案同时提供了careers_url与website，因此页面会渲染 "Apply Now" 主按钮。
• 地区与远程策略标签（company.njk#L17-L22）：region与remote_policy分别渲染为指向/browse/{region}/与/browse/{remote_policy}/的可点击标签，文案经 labels.js 转换（如fully-remote显示为 "Fully Remote"）。
• Tech Stack 区块（company.njk#L29-L38）：遍历technologies数组，为每个标签渲染指向/browse/{tech}/的标签链接。Drupal Jedi 的四个标签会生成 Go、PHP、JavaScript、DevOps 四个技术入口。
• 页脚（company.njk#L54-L56）：当存在updatedAt时，通过formatDate('MMMM D, YYYY')过滤器展示 "Last updated: June 14, 2018"。

5.3 元描述自动生成：companies.11tydata.js

companies.11tydata.js 为每家公司自动计算 SEO meta description。其逻辑通过正则/##\s*Company\s*blurb\s*\n+([\s\S]*?)(?=\n##|$)/i提取## Company blurb章节文本，依次剥离 Markdown 链接语法、*/_/反引号、合并换行与多余空格，最终截断至约 155 字符（优先在句号边界截断）。这意味着 Drupal Jedi 简介中"Drupal Jedi is a leading agency with the focus on building advanced web apps..."这段文字会被自动加工成页面的 meta 描述。

5.4 集合与浏览页：collections.js

collections.js 定义了一系列公司集合，直接决定档案在站点的呈现位置：

• getAllCompanies（collections.js#L24-L30）：按标题字母序排序全部约 850 家公司，供/companies/列表页使用；
• getCompaniesByRegion（collections.js#L50-L68）：按region字段分组，Drupal Jedi 的worldwide会落入 Worldwide 分组；
• getCompaniesByTech（collections.js#L71-L91）：按technologies数组分组，Drupal Jedi 会同时出现在 Go、PHP、JavaScript、DevOps 四个技术浏览页；
• getRecentCompanies（collections.js#L42-L47）：按addedAt日期取最近 12 家。

从源码结构看，所有公司档案统一通过getFilteredByGlob('./src/companies/**/*.md')收集（collections.js#L13），并带有备忘录缓存以避免对约 850 个条目重复过滤。

六、档案生命周期与链接健康维护

公司档案不是静态文件，其 URL 字段会随时间老化。仓库提供了专门的链接维护管线，见 scripts/README.md：

• check-links.sh：爬取src/companies/*.md中所有外链（frontmatter 与正文），记录 HTTP 状态与重定向终点，输出link-check-results.csv。支持--quick（只复查上次异常项）与--refresh（先重新提取 URL）模式。
• fix-links.mjs：读取扫描结果并分类处置。其中CAREERS_DEAD类别（careers URL 重定向到首页、登录页或错误页）会被自动修复——直接移除careers_url字段，让页面按钮回退到website。PARKED（域名被停放）与DEAD_DNS（域名完全无法解析）则直接删除整份档案文件。

这意味着如果 Drupal Jedi 的 careers 页面失效，维护者只需运行./scripts/check-links.sh --refresh && node scripts/fix-links.mjs --reverify --apply，即可自动从档案中移除失效的careers_url，保持目录数据的新鲜度。

七、实操：如何新增一份同规格的公司档案

若要为目录贡献一家类似 Drupal Jedi 的公司，按 CONTRIBUTING.md 的流程：

1. 在src/companies/下创建{slug}.md，确保文件名与slug字段一致；
2. 按官方 frontmatter 模板填写字段，参考 Drupal Jedi 档案的写法：

--- title: "Example Co" slug: example-co website: https://example.com careers_url: https://example.com/careers region: worldwide remote_policy: fully-remote company_size: small technologies: - javascript - python ---

3. 正文至少包含## Company blurb、## Remote status、## How to apply三个必填章节，可选补充## Company size、## Region、## Company technologies；
4. 运行npm run build（Node.js 22+）验证构建通过；
5. 提交 Pull Request，由Validate Company Profiles自动化校验机器人检查字段合法性。

需要提醒的是，addedAt/updatedAt由维护者统一管理，贡献者的 PR 中不应包含这两个字段。入库公司必须直接雇佣员工（不接受中介或自由职业平台代发职位），且提供的岗位必须是真实可远程的薪酬岗位。

结语

通过 Drupal Jedi 这份档案，可以完整看到 Remote In Tech 目录"一份 Markdown 数据 → 一个结构化公司页面"的整个数据流：frontmatter 承担结构化索引职责，正文章节面向求职者阅读，company.njk 负责渲染、companies.11tydata.js 自动生成 SEO 元数据、collections.js 驱动浏览页分组，而 check-links.sh 与 fix-links.mjs 守护链接长期健康。理解这套机制后，你既能快速解读目录中任何一家公司的档案，也能以完全合规的方式参与这份社区维护的远程工作公司清单。

• 数据集