目录
使用 GitHub Actions 工作流,即可在推送到 main 时,将同一篇 Markdown 文章发布到 Zenn 和 Qiita。关键是将 Qiita 的文章 ID 保存到 Git 中。如果不保存,后续运行时可能会重复创建文章。
要点#
- 将 Zenn 文章放在
articles/中,生成的 Qiita 文件放在public/中,并保持文件名一致。 - 保留 Qiita 的文章 ID,以便编辑时更新现有文章。
- 将 Zenn 的
published: false视为停止发布的设置。现有 Qiita 文章不会因此变为私密。 - 发布后,提交 CLI 更新的文件,并显式处理删除操作。
以 Git 为原本#
将仓库关联到 Zenn,并在仓库根目录下创建必需的 articles/ 目录。例如,从源文件 articles/github-actions-sync.md 生成 Qiita 文件 public/github-actions-sync.md。
通过相同的文件名关联两个平台上的文章。无需单独的映射文件,但重命名源文件时需要小心。如果转换过程找不到之前的 Qiita 文件,就无法沿用 ID,可能会创建另一篇文章。
编辑的是 articles/ 中的源文件。应将 public/ 视为保存生成内容和持久化发布状态的位置,而非另一个撰写文章的地方。直接在 Qiita 上做出的修改可能会在下次同步时被覆盖。
配置工作流#
创建具有文章写入权限的 Qiita 访问令牌,并将其保存为仓库密钥 QIITA_TOKEN。为工作流授予 contents: write 权限,以便提交发布状态。仓库规则也必须允许该推送。
按以下方式配置 GitHub Actions。
- 以修改了
articles/**的main分支推送,以及用于手动运行的workflow_dispatch为触发条件。 - 在单一并发组中设置
cancel-in-progress: false,防止发布作业重复运行。 - 检出仓库,并安装受支持的 Node.js 版本。
- 安装固定版本的
@qiita/qiita-cli和js-yaml。建议使用已提交的锁文件和npm ci。
作业按检出、转换、发布、提交的顺序执行。选择 Node.js 和各个 Action 的版本前,请确认 CLI 的最新要求。不要直接将旧示例中的版本作为固定标准。将 Qiita 令牌设置为发布步骤的环境变量。
转换 Front Matter#
使用库解析 YAML,而非逐行替换。复制 Markdown 正文,并按下表生成 Qiita 的 Front Matter。
| Qiita 字段 | 值 | |---|---| | title | Zenn 的 title | | tags | 最多 5 个主题字符串 | | private | false | | id | 现有 Qiita ID,或 null | | updated_at | 现有值,或空字符串 | | organization_url_name | 现有值,或 null | | slide | false |
这些值对应 CLI 的 Markdown 格式,与 API 请求格式不同。在所示实现中,将标签设为字符串,并将新文章的 ID 和组织设为 null 后,解决了 Bad request 错误。请使用所固定的 CLI 版本验证此格式。
对于每个目标源文件,在覆盖前读取现有的 public/<slug>.md,沿用其中的 ID 和更新时间。如果发布元数据缺失或无效,应报错,以免将未完成的文章误判为可发布。
发布后保存 ID#
Qiita CLI 会在发布后将文章 ID 写回本地 Markdown 文件。GitHub Actions 运行器是临时环境,因此需要在下次运行前将这些更改同步到仓库。
发布成功后,提交 public/ 中发生更改的文件,并推送到 main。所示实现还保留了 CLI 的 public/.remote/ 缓存。如果发布成功但提交失败,请在重新运行前找回已发布文章的 ID,否则可能会重复创建文章。
除了让作业串行执行,还应在转换前获取分支的最新状态。仅靠串行执行,无法保证等待中的运行会检出机器人的最新提交。如果最后的推送与并行更改发生冲突,应在解决冲突时确保 ID 不丢失。开始新的编辑前,请先在本地拉取。将触发条件限定为 articles/**,可防止仅涉及生成文件的提交再次触发此工作流。
处理草稿和删除#
Zenn 和 Qiita 的发布控制方式不同。设置 published: false 可将 Zenn 文章恢复为草稿,但已发布的 Qiita 文章不会变为私密。流水线会保留该 Qiita 文章,不作更改。
实现中有一个容易忽略的陷阱。即使跳过转换,现有的 public/ 文件也不会被排除在 qiita publish --all 的处理范围之外。请明确列出要发布的文章,并使用所固定 CLI 版本支持的选择方式,仅发布这些文章。保留被跳过文章已保存的 ID。
删除需要单独的步骤。
- 首先将源文章从 Qiita 发布范围中排除,否则转换过程可能会重新创建它。
- 删除 Qiita 上的文章。
- 删除生成文件及对应的远程缓存,并提交。
- 发布前,检查共用的 Markdown、图片 URL 和标签。Zenn 专用块和使用仓库相对路径的图片需要转换或替换。
下一步#
通过工作流发布一篇测试文章,编辑后再次运行。确认 Qiita 上更新的是同一文章 ID 后,再启用仓库中其余文章的同步。
来源: https://zenn.dev/ot4ma_zenn/articles/20261025-sun-zenn_qiita_pipeline
目录
