企业官网建设流程全解析

• 文档
• 教程
• 知识库

roadmap.sh 是全球开发者社区广泛使用的交互式学习路线图平台，而本仓库（developer-roadmap）正是其背后的官方内容仓库。本文以仓库根目录的 readme.md 为骨架，结合scripts/同步工具链源码与真实内容文件，系统讲解该仓库的内容组织规范、文件命名约定、资源类型标注体系，以及内容在仓库与网站数据库之间的双向同步机制。读完本文，你将掌握这套"以 Markdown 驱动交互式路线图"的内容管线是如何运转的，并了解如何正确参与贡献。

一、项目定位：社区驱动的开发者成长路线图

readme.md 开篇即给出项目定位：

Community-driven roadmaps, articles and resources for developers

这是 roadmap.sh 的内容仓库——网站上的每一条路线图、每一个主题节点的内容，都以 Markdown 文件的形式保存在本仓库中。README 特别强调：

Roadmaps are now interactive, you can click the nodes to read more about the topics.

也就是说，路线图上的每个节点都是可点击的，点击后弹出的主题说明文字，正是由仓库内对应的 Markdown 文件渲染而来。整个仓库承载三种内容形态：

• Roadmaps（路线图）：面向不同职业方向与技术领域的学习路径；
• Best Practices（最佳实践）：交互式的最佳实践清单；
• Questions（测评问题）：帮助开发者自测、评估与提升知识水平的问题集。

此外，README 还提到一个"快速上手"入口（Get Started 页面），帮助用户选择适合自己的一条学习路径。

二、路线图全览：覆盖 80 余条路线图与多种实践/测评内容

README 中列出了完整的路线图清单，当前已覆盖前端、后端、AI、云原生、数据、安全、移动端、游戏、设计与管理等几乎全部热门方向，下面按主题归类呈现（以下清单完整继承自 README）。

前端与 Web 基础

• Frontend Roadmap / Frontend Beginner Roadmap
• HTML Roadmap、CSS Roadmap、JavaScript Roadmap、TypeScript Roadmap
• React Roadmap、Next.js Roadmap、React Native Roadmap、Vue Roadmap、Angular Roadmap
• Node.js Roadmap
• GraphQL Roadmap

后端、全栈与架构

• Backend Roadmap / Backend Beginner Roadmap
• Full Stack Roadmap
• API Design Roadmap
• System Design Roadmap、Software Design and Architecture Roadmap、Software Architect Roadmap
• C Roadmap、C++ Roadmap
• Java Roadmap、Kotlin Roadmap、Spring Boot Roadmap
• Go Roadmap、Rust Roadmap、Scala Roadmap
• PHP Roadmap、Laravel Roadmap、WordPress Roadmap
• Ruby Roadmap、Ruby on Rails Roadmap
• Django Roadmap
• ASP.NET Core Roadmap

运维、云与基础设施

• DevOps Roadmap / DevOps Beginner Roadmap
• DevSecOps Roadmap
• Docker Roadmap、Kubernetes Roadmap、Terraform Roadmap
• AWS Roadmap、Cloudflare Roadmap
• Linux Roadmap、Bash/Shell Roadmap
• Network Engineer Roadmap
• PostgreSQL Roadmap（postgresql-dba）、MongoDB Roadmap、Elasticsearch Roadmap、Redis Roadmap、SQL Roadmap

AI 与数据科学

• AI Engineer Roadmap
• AI and Data Scientist Roadmap
• AI Product Builder Roadmap
• AI Red Teaming Roadmap
• AI Agents Roadmap
• Machine Learning Roadmap、MLOps Roadmap
• Prompt Engineering Roadmap
• Data Analyst Roadmap、BI Analyst Roadmap、Data Engineer Roadmap
• Python Roadmap、Python for Data Analysis Roadmap
• R Programming Roadmap、Power BI Roadmap

移动端、桌面与游戏

• Android Roadmap、iOS Roadmap、Swift/Swift UI Roadmap、Flutter Roadmap
• Game Developer Roadmap / Server Side Game Developer Roadmap

设计、产品与工程管理

• Product Design Roadmap、UX Design Roadmap、Design System Roadmap
• Product Manager Roadmap、Engineering Manager Roadmap
• QA Roadmap、Technical Writer Roadmap、DevRel Engineer Roadmap
• SEO Roadmap

计算机基础与新兴方向

• Computer Science Roadmap、Data Structures and Algorithms Roadmap、Leetcode Roadmap
• Git and GitHub Roadmap / Git and GitHub Beginner Roadmap
• Blockchain Roadmap、Cyber Security Roadmap
• Claude Code Roadmap、OpenClaw Roadmap、Vibe Coding Roadmap、Forward Deployed Engineer Roadmap

交互式最佳实践（Best Practices）

• Backend Performance Best Practices
• Frontend Performance Best Practices
• Code Review Best Practices
• API Security Best Practices
• AWS Best Practices

知识测评问题（Questions）

• JavaScript Questions
• Node.js Questions
• React Questions
• Backend Questions
• Frontend Questions

三、仓库结构与内容文件规范

路径模板与文件名语义

README 的 "Repository Structure" 一节给出了内容文件的标准路径模板：

roadmaps/<roadmap-slug>/content/<topic-slug>@<node-id>.md

其含义是：

• roadmap-slug：路线图的标识（如frontend、backend、ai-agents），对应 roadmaps 目录下的子目录；
• topic-slug：主题的英文短横线标识（由主题标题经 slug 化生成）；
• node-id：该主题在路线图节点图中的节点 ID，文件名中的 node id 正是把文件与路线图上某个主题节点关联起来的关键，因此 README 明确要求"请保持文件名完整不变"（keep file names intact）。

实测仓库中的真实文件，例如 roadmaps/frontend/content/html@yWG2VUkaF5IJVVut6AiSy.md（HTML 主题）、roadmaps/ai-agents/content/what-are-ai-agents@aFZAm44nP5NefX_9TpT0A.md（AI Agent 基础主题），均严格遵循这一命名模式。

内容文件的内部格式

打开一个真实主题文件（以 HTML 主题为例），其内容结构如下：

# HTML HTML (Hypertext Markup Language) is the standard for creating web pages, structuring content with elements and attributes. Browsers interpret HTML tags to render pages. HTML5, the current standard, adds semantic elements, multimedia support, and form controls. It works with CSS for styling and JavaScript for interactivity, forming web development's foundation. Visit the following resources to learn more: - [@roadmap@Visit the Dedicated HTML Roadmap](https://roadmap.sh/html) - [@course@Responsive Web Design Certification](https://www.freecodecamp.org/learn/2022/responsive-web-design/) - [@video@HTML Full Course for Beginners](https://youtu.be/mJgBOIoGihA) - [@video@HTML Full Course - Build a Website Tutorial](https://www.youtube.com/watch?v=pQN-pnXPaVg)

即每个文件由三部分组成：

1. # 主题标题（H1）；
2. 一段精炼的主题说明（contributing.md 要求尽量用"单个段落"讲清楚主题，保持弹窗内容简洁）；
3. Visit the following resources to learn more:引导句 + 资源链接列表。

资源类型标注体系（@type@）

资源链接使用- @type@标题的形式标注资源类型。根据 contributing.md 的规范，@type@必须取以下值之一：

• @official@— 官方文档
• @opensource@— 开源项目/源码
• @article@— 文章
• @course@— 课程
• @podcast@— 播客
• @video@— 视频
• @book@— 书籍

而 scripts/lib/official-roadmap-topic.ts 中定义的allowedOfficialRoadmapTopicResourceType还额外包含roadmap与feed两种类型，说明资源类型的体系在源码层比贡献文档更宽，多出的类型用于指向"其他路线图"和"订阅源"类资源。

内容约束与"宁缺毋滥"原则

contributing.md 明确规定：

• 内容必须为英文；
• 每个主题最多 8 个资源链接；
• 不接受 GeeksforGeeks 链接；
• 项目的目标"不是拥有最大的条目列表，而是列出当下最相关的技能/条目"。

这也解释了为什么每个主题文件的正文都刻意保持精炼——路线图的价值在于"精"，而不在于"全"。

四、内容仓库与网站数据库的双向同步机制

README 说明"合并后的变更会自动同步到网站"（Merged changes are synced to the website automatically），而同步工具链全部位于 scripts 目录，具体用法详见 scripts/readme.md。同步由三个脚本组成，分别在"数据库 → 仓库"与"仓库 → 数据库"两个方向上工作。

命令入口与工程配置

三个脚本通过 package.json 中定义的 npm scripts 调用：

"scripts": { "format": "prettier --write .", "sync:content-to-repo": "tsx ./scripts/sync-content-to-repo.ts", "sync:repo-to-database": "tsx ./scripts/sync-repo-to-database.ts", "cleanup:orphaned-content": "tsx ./scripts/cleanup-orphaned-content.ts" }

工程使用tsx直接运行 TypeScript 脚本，核心依赖为markdown-it（Markdown → HTML）、node-html-parser（HTML DOM 解析）、turndown（HTML → Markdown），配套typescript、prettier用于类型检查与格式化。

数据库 → 仓库：sync-content-to-repo.ts

scripts/sync-content-to-repo.ts 负责把数据库中的主题内容拉取出来、写入roadmaps/<slug>/content/<label>@<nodeId>.md，用于"播种"或刷新某个路线图在仓库中的镜像。典型用法：

npm run sync:content-to-repo -- --roadmap-slug=frontend --secret=<GH_SYNC_SECRET>

从源码看，其工作流程是：

1. 调用v1-list-official-roadmap-topics/<roadmapId>?secret=...接口拉取该路线图的全部主题（scripts/sync-content-to-repo.ts）；
2. 调用v1-official-roadmap/<roadmapId>接口拉取路线图的节点图（nodes/edges），用于把 nodeId 解析为节点标签（label）；
3. 用 scripts/lib/slugger.ts 中的slugify函数（小写化 → 去除非字母数字下划线短横线字符 → 空格转短横线）由 label 生成 topic-slug，拼接出<topic-slug>@<nodeId>.md文件名；
4. 通过 scripts/lib/official-roadmap-topic.ts 的prepareOfficialRoadmapTopicContent把描述与资源列表组装为最终 Markdown（资源链接使用formatOfficialRoadmapTopicResourceLink生成- @type@标题格式，并对标题中的\ < > [ ]字符做转义），写入对应目录。

仓库 → 数据库：sync-repo-to-database.ts

scripts/sync-repo-to-database.ts 是社区 PR 的"落库通道"，负责解析每个内容文件、从描述中拆分资源列表、将@type@前缀映射为资源类型并 POST 到v1-sync-official-roadmap-topics接口。典型用法：

npm run sync:repo-to-database -- --files=roadmaps/frontend/content/html@node-id.md --secret=<GH_SYNC_SECRET>

其中--files为逗号分隔的文件列表。从源码看，其处理管线相当精细（scripts/sync-repo-to-database.ts）：

1. 文件过滤：只有以.md结尾且路径包含content/的文件才会被同步，其余文件直接跳过；
2. 解析路径：从roadmaps/<slug>/content/<label>@<nodeId>.md中拆出roadmapSlug、nodeSlug与nodeId；
3. 节点校验：拉取路线图 JSON，若nodeId在节点图中不存在则跳过；
4. Markdown → HTML：使用 scripts/lib/markdown.ts 中配置了html: true与linkify: true的 markdown-it 实例渲染内容，并通过replaceVariables替换@变量名@形式的占位符（内置currentYear变量）；
5. 资源列表提取：遍历<ul>，找出"每个<li>内部仅含一个链接"的列表，将其视为资源列表；再用正则/@([a-z.]+)@/从链接文本中提取@type@前缀，若类型不在允许清单内则回退为article；
6. 类型排序：按official → opensource → article → video → feed的优先级顺序对资源排序（scripts/sync-repo-to-database.ts），保证同一主题下官方与开源资料优先展示；
7. 描述清理：移除标题与资源列表后，若存在资源列表还会删除最后一个段落（源码注释说明这是"移除描述末尾的 see more 之类引导句"），再把剩余 HTML 通过htmlToMarkdown转回 Markdown，并重新拼上# 标题；
8. 上传同步：将{roadmapSlug, nodeId, description, resources}批量 POST 到https://roadmap.sh/api/v1-sync-official-roadmap-topics，携带secret鉴权（scripts/sync-repo-to-database.ts）。

孤儿内容清理：cleanup-orphaned-content.ts

scripts/cleanup-orphaned-content.ts 负责把磁盘上的文件与数据库中的路线图节点做比对，删除或重命名"对不上号"的残留文件。典型用法：

npm run cleanup:orphaned-content -- --roadmap-slug=frontend npm run cleanup:orphaned-content -- --roadmap-slug=__all__

其中__all__会遍历roadmaps/下所有含content/目录的路线图。从源码与 scripts/readme.md 的说明看，它处理三类场景：

• node id 相同但 slug 过时（主题被重命名）→ 重命名文件；
• slug 相同但 node id 过时→ 删除文件（正确的文件已存在）；
• 路线图上已不存在的主题→ 删除文件。

清理结束后会生成一份 Markdown 报告写入.cleanup-summary.md，该报告随后被工作流用作 PR 正文。

自动化工作流

三个脚本均由 GitHub Actions 工作流驱动（.github/workflows下的sync-content-to-repo.yml、sync-repo-to-database.yml、cleanup-orphaned-content.yml，见 scripts/readme.md），同时也可以在本地手动运行。其中sync-content-to-repo由后台管理端手动派发，sync-repo-to-database则承载社区 PR 的自动同步。

五、如何参与贡献

README 与 contributing.md 给出了完整的贡献路径：

修改既有路线图内容

本仓库只保存路线图内容，本地没有需要运行的应用。克隆后在roadmaps/<roadmap-slug>/content/下编辑对应 Markdown 并提交 PR 即可：

git clone https://gitcode.com/GitHub_Trending/de/developer-roadmap.git --depth 1 cd developer-roadmap

注意：

• 拼写修正：直接修改内容文件并提交 PR；
• 添加/删除节点、修改节点标题：需先提 issue 说明建议；
• 文件名务必保持原样，node id 是文件与路线图节点绑定的关键；
• 建议将内容改动合并为一个 PR，并书写有意义的 commit message。

新增路线图

有两种官方推荐方式：

1. 在 issue 中提交一份"文本化路线图"；
2. 使用路线图编辑器（draw.roadmap.sh）创建交互式路线图，并将链接提交到 issue。

内容贡献的质量准则

contributing.md 明确区分了"好贡献"与"不好贡献"：

• 好的贡献：新路线图、新鲜且有价值的内容链接、错别字与语法修正、对既有内容的增强、为缺少正文的主题补充说明；
• 不好的贡献：无意义的空白改动、不增值的内容重写、非英文内容、不符合风格指南且无描述的 PR、指向自己博客的链接。

同时项目强调三条铁律：不做自我宣传、不要"把网上能找到的东西全塞进来"、不要添加自己未曾亲自评估过的资源。

内容同步链路

一旦 PR 被合并，内容会自动同步到网站（"Merged changes are synced to the website automatically"）——这正是上一节所述双向同步管线的价值所在。

六、许可证

本仓库以开源许可证发布，具体条款见 license 文件。

结语

developer-roadmap 仓库的价值在于它把"学习路径"这种抽象知识，沉淀成了一套可版本化、可协作、可自动同步的 Markdown 内容管线：roadmaps/<slug>/content/<topic>@<nodeId>.md的命名约定让每个文件都能精确定位到路线图上的一个节点，@type@前缀让资源可以结构化分类，而三个同步脚本则保证了社区贡献与线上站点内容始终一致。无论你是想用 roadmap.sh 规划学习路线，还是希望为某个主题补充高质量资料，理解这套组织与同步机制都能让你更快地上手。

• 文档
• 教程
• 知识库