• 数据集

本篇技术指南以 remote-jobs 开源仓库（remoteintech.company 网站的源码）中的公司档案文档 src/companies/paylocity.md 为主体，系统拆解一个远程友好科技公司条目是如何以 Markdown + Frontmatter 形式组织的，并追踪它从数据定义、元数据计算、标签聚合到最终 HTML 页面渲染的完整链路。读完本文，你将掌握该仓库公司档案的标准字段模型、合法取值约束、描述自动生成逻辑以及按地区 / 远程政策 / 技术栈聚合的实现方式，并了解如何为目录新增或校验同类档案。

一、档案在仓库中的位置与项目定位

remote-jobs 仓库的package.json将其描述为"A list of semi to fully remote-friendly companies in or around tech"，即一个由社区维护的、收录科技行业内半远程至全远程友好公司的目录。每家公司对应src/companies/目录下的一个独立 Markdown 文件，paylocity.md 便是 Paylocity（一家美国 HR 与薪酬技术公司）在目录中的完整档案。

该档案包含两部分：

• Frontmatter（YAML 元数据）：标题、slug、官网、招聘页、地区、远程政策、公司规模、技术栈标签、收录与更新时间；
• Markdown 正文：公司简介、规模、远程现状、地区、技术栈、办公地点、申请方式等固定章节。

这份档案是 Paylocity 在 remoteintech.company 站点上所有展示、检索与聚合行为的唯一数据来源，理解它的结构即理解整个目录的数据约定。

二、Frontmatter 元数据逐项拆解

paylocity.md 的 Frontmatter 如下：

--- title: "Paylocity" slug: paylocity website: https://www.paylocity.com/ careers_url: https://www.paylocity.com/careers/career-opportunities/ region: americas remote_policy: remote-friendly company_size: enterprise technologies: - dotnet - javascript addedAt: 2018-04-24 updatedAt: 2020-10-23 ---

各字段的含义与合法取值，均可在仓库的 CONTRIBUTING.md 与标签定义文件 src/_data/labels.js 中找到依据：

值得注意的是一处"双轨"现象：正文## Company technologies一节罗列的是 HTML、JavaScript、CSS、AJAX、ASP.NET、C# 与 SQL（信息更细、带完整技术名），而 Frontmatter 的technologies仅收录了dotnet与javascript两个标准化标签。原因在于：Frontmatter 标签用于站点聚合与筛选（必须命中 labels.js 的受控词表），而正文保留的是原始公司描述。这体现了"正文承载信息、元数据承载结构化"的目录设计思想。

三、正文章节结构：一条档案包含哪些信息

paylocity.md 正文依次包含以下固定##章节，这与 CONTRIBUTING.md 规定的结构完全一致（必选：Company blurb、Remote status、How to apply；常用可选：Company size、Region、Company technologies）：

• Company blurb（公司简介）：档案写道"At Paylocity, caring is in our makeup. It's who we are. We're more than a cutting-edge HR and payroll tech company…We're people."——直接点明公司业务（HR 与薪酬技术）与价值观基调；
• Company size（公司规模）：3300+，并明确标注"As of October 2020"，即该数据为 2020 年 10 月时点值；
• Remote status（远程现状）：说明大量员工远程办公，且公司技术使远程协作"如同身处同一房间"（甚至连同宠物）；
• Region（地区）：USA，对应 Frontmatter 的region: americas（美洲区域，见 labels.js）；
• Company technologies（公司技术）：HTML、JavaScript、CSS、AJAX、ASP.NET、C# 和 SQL；
• Office locations（办公地点）：总部地址为 1400 American Lane, Schaumburg, IL 60173；
• How to apply（如何申请）：指向官方职业机会页，对应 Frontmatter 的careers_url。

由于档案的updatedAt为 2020-10-23，正文中的规模数字与远程政策均代表该时点的信息，阅读与引用时应以档案标注时间为准——这也是该目录"社区维护、按更新时间标注"的通用惯例。

四、SEO 描述自动生成：companies.11tydata.js 的计算逻辑

Paylocity 这类档案的 meta description 并非手工填写，而是由 src/companies/companies.11tydata.js 中的eleventyComputed在构建期自动生成。其算法要点：

1. 若已有description字段则直接使用；
2. 否则对data.page.rawInput（原始 Markdown）用正则/##\s*Company\s*blurb\s*\n+([\s\S]*?)(?=\n##|$)/i提取## Company blurb之后、下一个##之前的段落作为候选文本；
3. 对文本做清理：text还原为text、移除 `* _ `` 等 Markdown 符号、合并换行与多余空格；
4. 按约 155 字符截断：优先在句号边界截断，其次在空格边界截断并追加...。

这意味着每条公司档案的简介质量会直接影响其搜索引擎摘要——写好Company blurb是档案 SEO 的基础。同理，站点还会为每个公司页面注入 JSON-LD 结构化数据，见 src/_includes/schemas/Organization.njk：以schema.org/Organization类型输出name、url，并将careers_url放入sameAs数组，帮助搜索引擎理解公司实体的官网与招聘页归属。

五、从 Markdown 到页面的渲染链路

公司的渲染模板是 src/_layouts/company.njk（在 eleventy.config.js 中以addLayoutAlias('company', 'company.njk')注册，并由 src/companies/companies.json 中的"layout": "company"指定）。该布局的关键行为：

• 主 CTA 按钮：{% set buttonUrl = careers_url or website %}——优先使用招聘页，缺省时回退到官网；有careers_url时按钮文案为 "Apply Now"；
• 地区与远程政策标签：<a href="/browse/{{ region }}/">与<a href="/browse/{{ remote_policy }}/">，文案经labels.region[region]、labels.remotePolicy[remote_policy]从内部键映射为人类可读的 "Americas"、"Remote Friendly"；
• Tech Stack 区块：遍历 Frontmatter 的technologies，逐个渲染为指向/browse/{tech}/的标签，经labels.tech将dotnet、javascript映射为 ".NET"、"JavaScript"；
• 更新时间展示：{{ updatedAt | formatDate('MMMM D, YYYY') }}将日期格式化为可读形式（过滤器定义见 src/_config/filters）。

因此，Paylocity 档案的region、remote_policy、technologies三个字段不仅是元数据，更是页面内导航标签与聚合页面的路由键。

六、聚合、浏览与检索：档案如何进入目录视图

src/_config/collections.js 通过getFilteredByGlob('./src/companies/**/*.md')一次性读取全部公司档案（带缓存避免重复过滤约 850 个条目），并导出多种集合：

• getAllCompanies：按title小写化后localeCompare字母排序，供"所有公司"列表使用；
• getRecentCompanies：按addedAt降序取前 12，实现"最近收录"区块；
• getCompaniesByRegion/getCompaniesByTech：将公司按region字段与technologies数组分组，支撑/browse/{region|tech}/聚合页；
• getCompanyTags：汇总technology、region、remote-policy三类标签及其公司列表，按数量降序排列。

在前端浏览页 src/pages/companies.njk 中，所有档案以卡片网格呈现，每个.company-item携带data-region与data-name属性，配合 Pagefind 全文搜索（new PagefindUI({...})）与客户端地区下拉过滤（region-filter的change事件）实现按地区即时筛选，且支持?region=americas这类 URL 参数直达过滤结果。

七、如何新增与校验同类档案

若要在目录中新增一家公司档案，CONTRIBUTING.md 给出了明确流程：

1. 在src/companies/下创建{slug}.md，文件名必须与slug一致；
2. 按 Frontmatter 模板填写元数据并撰写 Markdown 正文（必含Company blurb、Remote status、How to apply三节）；
3. 本地执行npm run build验证构建；
4. 提交 Pull Request。

涉及公司文件的 PR 会自动触发Validate Company ProfilesGitHub Action 校验，机器人会在 PR 中评论问题并阻塞合并，直到问题解决。目录的收录标准也较为严格：必须是员工本人或可验证信息、直接雇佣员工（不接受训练营、中介或自由职业平台）、提供真正的远程职位（佣金制或独立承包销售机会不算）、处于科技行业或与之相关，且careers_url必须指向公司自己的招聘页。维护者还会拒绝内容过少（minimal or no meaningful content）的档案——这正是 paylocity.md 等档案保持七节完整结构的原因。

八、小结

透过 Paylocity 这一条档案，可以看到 remote-jobs 仓库"一个公司 = 一个 Markdown 文件"的数据驱动设计：Frontmatter 提供受控的标准化元数据（地区、远程政策、规模、技术栈），正文提供人类可读的完整信息，构建期的计算数据（description 生成）、Nunjucks 布局（标签与 CTA 渲染）、JSON-LD schema 与集合聚合共同完成从数据到站点的全链路。如果你需要为远程友好雇主编写可被搜索引擎、Agent 与 LLM 高效索引的公司档案，或想为这类社区目录贡献条目，paylocity.md 与本文梳理的字段约定、取值约束和渲染机制就是可直接复用的范式。

• 数据集