向 Kubernetes 博客提交文章

目前有两个官方 Kubernetes 博客,CNCF 也有自己的博客,你也可以在上面涵盖 Kubernetes 的相关内容。对于 Kubernetes 主博客,我们(Kubernetes 项目组)倾向于发表具有不同视角和重点,且与 Kubernetes 有关联的文章。

除了少数特殊情况外,我们只发布未在其他任何地方提交或发布过的内容。

为 Kubernetes 博客撰稿

作为作者,你有三种不同的发布路径。

推荐路径

Kubernetes 项目推荐的方法是:通过联系博客团队来推介(pitch)你的文章。你可以通过 Kubernetes Slack (#sig-docs-blog) 进行联系。对于只想发布到贡献者博客的文章,你也可以直接向 SIG ContribEx comms 推介。

除非你的提交存在问题,否则博客团队 / SIG ContribEx 将为你指派:

  • 一位博客编辑
  • 你的写作伙伴(另一位博客作者)

当团队为你指派另一位作者时,其意图是让你们通过审阅对方的初稿文章来互相支持。你不需要成为主题专家;阅读这篇文章的大多数读者也不会是专家。我们(Kubernetes 博客团队)将另一位作者称为“写作伙伴”。

编辑的作用是帮助你完成从草稿到发布的旅程。他们要么能够直接批准你的文章进行发布,要么可以安排相关的批准流程。

阅读 撰写博客文章 以了解更多关于该流程的信息。

从 Pull Request 开始

为我们的博客撰稿的第二条路径是直接在 GitHub 上发起 Pull Request。博客团队实际上并不推荐这种方式;GitHub 对于代码协作非常有用,但对于纯文稿来说并非理想之选。

完全可以只通过一次空的提交来创建一个占位 Pull Request,然后在其他地方工作,之后再回到你的占位 PR。

推荐路径类似,我们会尝试为你指派一名写作伙伴和一名博客编辑。他们将帮助你准备好文章以供发布。

发布后的博客文章流程

第三条路径适用于关于 Kubernetes 版本相关变更的博客文章。每当有版本发布时,发布沟通(Release Comms)团队就会接管博客发布计划。为版本添加功能的人,或计划进行项目需要宣布的其他变更的人,可以与发布沟通团队联络,以规划、起草、编辑并最终发布他们的文章。

文章排期

对于 Kubernetes 博客,博客团队通常将博客文章安排在工作日(使用美国及其他国家采用的公历)发布。当需要在周末的特定日期发布时,博客团队会尽量给予配合。

撰写博客文章 一节解释了需要执行的操作

  • 最初,不要为文章指定日期
  • 但是,务必将文章设置为草稿(在 front matter 中添加 draft: true

当 Prow 机器人合并你编写的 PR 时,它将作为一个草稿,不会被设置为发布。之后,Kubernetes 贡献者(你自己、你的写作伙伴或博客团队的成员)会提交一个小型的后续 PR,将其标记为发布。合并第二个 PR 将会释放之前处于草稿状态的文章,使其能够自动发布。

在文章计划发布的当天,自动化程序会触发网站构建,你的文章将变得可见。

撰写文章

在推介(pitch)完成后,我们鼓励你使用 HackMD(一个网页版 Markdown 编辑器)或 Google 文档来共享文章的可编辑版本。你的写作伙伴可以阅读你的草稿文本,并直接提出建议或提供反馈。如果你的草稿不符合 博客指南,他们也应该告知你。

同时,你通常也会成为他们的写作伙伴,并可以遵循我们关于如何支持他们工作的指南

初步行政步骤

如果你还没有签署 CLA,你应该签署。最好尽早确认这一点;如果你是作为工作的一部分进行撰写,你可能需要与公司的法律团队或主管沟通,以确保你有权签署该协议。

初稿撰写

博客团队建议你使用 HackMD(一个网页版 Markdown 编辑器)或 Google 文档来准备并共享文章的初始、实时可编辑版本。

说明

如果你选择使用 Google 文档,可以将文档设置为 Markdown 模式。

你的写作伙伴可以为你的初稿提供注释和/或反馈,并且会(或应该)检查其是否符合准则。同时,你也会是他们的写作伙伴,可以遵循解释如何支持他们工作的指南

不过,在现阶段不用太担心 Markdown 格式是否完全正确。

如果你有图片,可以粘贴一个位图副本以供初步反馈。博客团队(在流程后期)可以协助你将插图准备好以供最终发布。

用于发布的 Markdown

查看 GitHub 中网站仓库里现有博客文章的 Markdown 格式。

如果你还不熟悉,请阅读 贡献基础知识。本页的这一部分假设你没有 fork 的本地克隆,并且正在 GitHub Web UI 中进行操作。如果你还没有这样做,你确实需要远程 fork 网站仓库。

在 GitHub 仓库中,点击 Create new file(创建新文件)按钮。以 /content/en/blog/_posts/YYYY/abbreviated-post-title.md 的格式为博客文章命名,其中 …/YYYY/… 是包含对应年份文章的子文件夹。如果你需要为博客文章添加额外的图片、图表等,请创建一个 /content/blog/en/blog/_posts/YYYY/abbreviated-post-title/ 文件夹,并在其中放置 index.md 文件以及文章的其他文件。

从 HackMD 或 Google 文档中复制你现有的内容,然后将其粘贴到编辑器中。本节稍后会有关于该文件中应包含内容的更多详细信息。命名文件以匹配博客文章的提议标题,但不要在文件名中包含日期。博客审稿人将与你合作设定最终的文件名以及文章发布的日期。

  1. 当你保存文件时,GitHub 会引导你完成 Pull Request 流程。

  2. 你的写作伙伴可以审阅你的提交并与你一起处理反馈和最终细节。博客编辑会批准你的 Pull Request 进行合并,将其作为一个尚未安排发布的草稿。

Front matter(页首元数据)

你编写的 Markdown 文件应该使用 YAML 格式的 Hugo front matter

这是一个示例

---
layout: blog
title: "Your Title Here"
draft: true # will be changed to date: YYYY-MM-DD before publication
slug: lowercase-text-for-link-goes-here-no-spaces # optional
author: >
  Author-1 (Affiliation),
  Author-2 (Affiliation),
  Author-3 (Affiliation)  
---
  • 最初,不要为文章指定日期,也不要在 front matter 中放入任何日期占位符(不要这样做 date: XXXX-XX-XX
  • 但是,务必将文章设置为草稿(在文章的 front matter 中添加 draft: true

文章内容

请确保使用二级 Markdown 标题(## 而不是 #)作为文章的最顶层标题。你在 front matter 中设置的 title 将成为该页面的以及标题。

你应该遵循样式指南,但有以下例外情况:

  • 只要大多数读者能够理解所表达的观点,我们允许作者使用自己的写作风格撰写文章。
  • 在有多位作者的博客文章中,或者文章开头明确表明作者代表特定群体撰写时,使用“我们(we)”是可以的。你会注意到,尽管我们在文档中 避免使用“我们”,但做出合理的例外是允许的。
  • 我们避免为标注使用 Kubernetes 短代码(如 {{< caution >}})。这是因为标注是针对文档读者的,而博客文章不是文档。
  • 关于未来的陈述是可以的,尽管我们在代表 Kubernetes 的官方公告中使用时会格外谨慎。
  • 博客文章中使用的代码示例不需要使用 {{< code_sample >}} 短代码,而且通常不使用它会更好(更易于维护)。

图表和插图

对于插图、图表或图表,在可行的情况下可以使用 figure 短代码。你应该为可访问性设置 alt 属性。

对于插图和技术图表,请尽量使用矢量图形。博客团队推荐 SVG 而不是栅格(位图/像素)图表格式,也推荐 SVG 而不是 Mermaid(你仍然可以在注释中保留 Mermaid 源码)。倾向于使用 SVG 而非 Mermaid 的原因在于,当维护者升级 Mermaid 或更改图表渲染方式时,他们可能无法轻易联系到原始博客文章作者来确认更改是否合规。

图表指南 旨在用于 Kubernetes 文档,而非博客文章。遵循它仍然是好的,但

  • 没有必要给图表加标题(如“图 1”、“图 2”等)。

对可缩放(矢量)图像的要求使得不熟悉的人提交文章的过程变得更加困难;Kubernetes SIG Docs 将继续寻找降低这一门槛的方法。如果你有关于如何降低门槛的想法,请主动提供帮助。

对于其他图像(如照片),博客团队强烈鼓励使用 alt 属性。如果辅助技术软件完全不应该提及该图像,使用空的 alt 属性是可以的,但这属于极少数情况。

提交信息 (Commit messages)

当你将 Pull Request 标记为准备审阅时,每个提交信息都应该是对所做工作的简要总结。第一条提交信息应该作为一个博客文章的总体描述。

良好的提交信息示例

  • Add blog post on the foo kubernetes feature
  • blog: foobar announcement

糟糕的提交信息示例

  • Placeholder commit for announcement about foo
  • Add blog post
  • asdf
  • initial commit
  • draft post

压缩 (Squashing)

一旦你认为文章已准备好合并,你应该压缩 (squash) Pull Request 中的提交;如果你不确定如何操作,可以向博客团队寻求帮助。


最后修改时间:2026年2月19日 上午11:35 PST: 更新 submission.md (7de8214737)