关于此文档基础设施

Source: Dev.to

请提供您想要翻译的具体文本内容，我将按照要求保留链接和原始格式进行简体中文翻译。

文档结构

所有文档都以 Markdown 文件形式存放在 GitHub 仓库的 ./documentation 目录下。这是唯一的真实来源。

documentation/
├── index.md              # 入口点 / 概览
├── pitches.md            # 各种长度的摘要
├── SRDD-part1-of-4.md    # 系列文章 第 1 部分
├── SRDD-part2-of-4.md
├── SRDD-part3-of-4.md
├── SRDD-part4-of-4.md
├── CONTRIBUTING.md       # 贡献指南
├── about.md              # 本文件
└── .sync-state.json      # Dev.to 同步状态（自动生成）

每个 Markdown 文件使用 YAML 前置块来存放元数据（标题、描述等），并采用 GitHub‑flavored Markdown 编写正文。

内部链接占位符

文档使用占位符语法来表示内部链接：

See [Part 1]({{devto:SRDD-part1-of-4}}) for details.

{{devto:slug}} 模式会根据目标平台进行不同的转换。

这样，文档之间可以相互链接，而无需硬编码在不同平台上会变化的 URL。

Source: …

发布工作流

单个工作流（.github/workflows/deploy-and-sync.yml）处理所有发布步骤。

# Transform devto placeholders for GitHub Pages
- name: Transform devto placeholders for GHP
  run: |
    find ./documentation -name "*.md" -exec sed -i -E \
      's/\{\{devto:([^}]+)\}\}/.\/\1.md/g' {} \;

# Build with Jekyll
- name: Build with Jekyll
  uses: actions/jekyll-build-pages@v1
  with:
    source: ./documentation
    destination: ./_site

流程概览

1. 将资源复制到 documentation 目录。
2. 将 {{devto:slug}} 占位符转换为相对的 .md 链接。
3. 使用 Jekyll 构建站点。
4. 部署到 GitHub Pages。

GitHub Pages 部署完成后，会运行同步步骤：

sync-to-devto:
  needs: deploy  # Run after deploy so canonical URLs are live
  steps:
    - name: Sync posts to Dev.to
      env:
        DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}
        SITE_URL: ${{ vars.SITE_URL }}

同步脚本 (scripts/sync-to-devto/sync-to-devto.js)

该脚本执行 两遍同步：

第 1 遍 – 构建 URL 映射

对每个 Markdown 文件：

1. 解析 front matter 和正文。
2. 构建指向 GitHub Pages 的规范 URL。
3. 转换正文（将图片路径改为绝对 URL，去除样式）。
4. 通过 API 创建或更新 Dev.to 文章。
5. 捕获返回的 Dev.to URL。

得到的映射（示例）：

{
  "index": "https://dev.to/bbos/srdd-is-the-best...-4k2n",
  "SRDD-part1-of-4": "https://dev.to/bbos/why-srdd-exists-2j8m"
}

第 2 遍 – 解析占位符

重新解析包含 {{devto:slug}} 占位符的文档，用映射中的实际 Dev.to URL 替换它们，然后再次更新这些文章。

这样可以确保所有交叉引用在 Dev.to 动态生成 URL 的情况下也能正确解析。

增量同步与状态缓存

仅上传已更改的帖子，减少 API 调用并加快流水线速度。

• 哈希：对每篇帖子的内容进行哈希（SHA‑256，截断为 32 字符）。
• 状态文件：documentation/.sync-state.json 存储哈希值、同步时间戳以及 Dev.to URL。

{
  "index": {
    "hash": "a1b2c3d4e5f67890...",
    "syncedAt": "2026-01-07T10:00:00Z",
    "url": "https://dev.to/bbos/srdd-...-4k2n"
  },
  "pitches": {
    "hash": "f0e1d2c3b4a59687...",
    "syncedAt": "2026-01-07T10:00:00Z",
    "url": "https://dev.to/bbos/pitches-...-2j8m"
  }
}

url 字段缓存每篇文章的 Dev.to URL，即使在 API 速率限制阻止获取 URL 时，也能实现占位符解析。

强制完整同步

要同步 所有 帖子（不论是否有更改）：

env:
  FORCE_SYNC: 'true'

或在本地运行：

node sync-to-devto.js --force
# With .env file
export $(grep -v '^#' .env | xargs) && node sync-to-devto.js --force

刷新 URL 缓存

如果文章已被重命名或 URL 已更改，请刷新缓存的 URL：

env:
  REFRESH_URLS: 'true'

或在本地执行：

node sync-to-devto.js --refresh-urls
# 使用 .env 文件
export $(grep -v '^#' .env | xargs) && node sync-to-devto.js --refresh-urls

规范 URL

每篇 Dev.to 文章都包含一个指向 GitHub Pages 版本的 canonical_url，例如：

canonical_url: https://docs-bbos.github.io/srdd/SRDD-part1-of-4/

优势

• SEO 整合 – 搜索排名集中到单一 URL。
• 平台灵活性 – 内容可以出现在 Dev.to、Medium 或未来的平台上。
• 唯一真实来源 – 读者始终知道权威版本的所在位置。

添加新页面

1. 创建 documentation/new-page.md 并添加适当的 front matter。
2. 使用 {{devto:new-page}} 从其他页面进行链接。
3. 提交并推送到 main。

该流水线会自动部署到 GitHub Pages，并将新文章同步到 Dev.to。

必需的密钥和变量

此基础设施实现了 “一次编写，随处发布”，用于随方法论演进而不断更新的活文档。