提交文章到 Kubernetes 博客

Kubernetes 有两个官方博客，CNCF 也有自己的博客，您可以在其中介绍 Kubernetes。对于主要的 Kubernetes 博客，我们 (Kubernetes 项目) 喜欢发表具有不同观点和特殊侧重、且与 Kubernetes 相关的文章。

除少数特殊情况外，我们仅发表尚未在其他地方提交或发表的内容。

为 Kubernetes 博客撰写文章

作为作者，您有三种不同的发表途径。

推荐途径

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

除非您的投稿有问题，否则博客团队 / SIG ContribEx 会为您安排

  • 一位博客编辑
  • 您的写作伙伴（另一位博客作者）

当团队为您安排另一位作者时，其目的是让您通过审阅对方的文章草稿来互相支持。您无需是主题专家；大多数阅读文章的人也不是专家。我们 Kubernetes 博客团队将另一位作者称为写作伙伴。

编辑会帮助您完成从草稿到发表的整个过程。他们要么可以直接批准您的文章发表，要么可以安排批准。

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

从拉取请求 (PR) 开始

第二种为我们的博客撰写文章的途径是直接在 GitHub 中开始一个拉取请求。博客团队实际上不推荐这样做；GitHub 对于协作代码非常有用，但对于散文文本来说并非理想选择。

完全可以只通过一个空提交打开一个占位的拉取请求，然后在其他地方进行工作，然后再回到您的占位 PR。

与推荐途径类似，我们将尝试为您安排一位写作伙伴和一位博客编辑。他们会帮助您准备好文章以供发表。

版本发布后博客文章流程

第三种途径是针对与 Kubernetes 版本发布相关的变更的博客文章。每次发布新版本时，发布沟通团队 (Release Comms) 会接管博客发表计划。为发布版本添加功能或计划进行项目需要公告的其他变更的人员，可以与发布沟通团队协调，以规划、起草、编辑并最终发表他们的文章。

文章排期

对于 Kubernetes 博客，博客团队通常会将博客文章安排在工作日（以美国和其他国家/地区使用的公历为准）发表。当需要在特定日期发表（该日期恰逢周末）时，博客团队会尽量予以安排。

撰写博客文章一节解释了如何做

  • 最初，不要指定文章的日期
  • 但是，请将文章设置为草稿（在 front matter 中放入 draft: true）

当 Prow bot 合并您提交的 PR 时，它将是一个草稿，不会设置为发表。然后，一位 Kubernetes 贡献者（可以是您、您的写作伙伴或来自博客团队的人）会打开一个小的后续 PR，将其标记为可以发表。合并第二个 PR 会发布之前处于草稿状态的文章，使其可以自动发表。

在文章预定发表的当天，自动化会触发网站构建，您的文章将变为可见。

撰写文章

推荐您在推荐后使用 HackMD（一个网页版 Markdown 编辑器）或 Google Doc，以便分享文章文本的可编辑版本。您的写作伙伴可以阅读您的草稿，然后直接提出建议或提供其他反馈。如果您的草稿与博客指南不符，他们也应该让您知道。

同时，您通常会是**他们**的写作伙伴，可以遵循我们的指南来支持他们的工作。

初步管理步骤

如果您尚未签署 CLA，应先签署 CLA。最好尽早开始这项工作；如果您是作为工作的一部分撰写文章，您可能需要咨询工作场所的法律团队或您的经理，以确保您被允许签署。

初步起草

博客团队推荐您使用 HackMD（一个网页版 Markdown 编辑器）或 Google Doc，以便准备和分享文章文本的初始可实时编辑版本。

您的写作伙伴可以为您的草稿文本提供评论和/或反馈，并将（或应该）检查它是否符合指南。同时，您将是他们的写作伙伴，可以遵循指南，该指南解释了您将如何支持他们的工作。

不过，在这个阶段，不必过于担心 Markdown 格式是否完全正确。

如果您有图片，可以粘贴位图副本以获取早期反馈。博客团队可以在流程后期帮助您准备插图以供最终发表。

用于发表的 Markdown

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

如果您还不熟悉，请阅读贡献基础知识。本节假设您没有本地克隆的 Fork，并且您正在使用 GitHub 网页 UI 进行工作。如果您还没有这样做，则需要创建一个远程 Fork 网站仓库。

在 GitHub 仓库中，单击**创建新文件**按钮。从 HackMD 或 Google Docs 复制现有内容，然后粘贴到编辑器中。本节后面会详细说明该文件中应包含的内容。文件命名应与建议的博客文章标题匹配，但不要在文件名中包含日期。博客审阅者将与您一起确定最终文件名和文章发表日期。保存文件时，GitHub 会引导您完成拉取请求流程。

  1. 保存文件时，GitHub 会引导您完成拉取请求流程。

  2. 您的写作伙伴可以审阅您的投稿，并与您一起处理反馈和最终细节。博客编辑将批准您的拉取请求合并，作为尚未排期的草稿。

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 中放入 draft: true）

文章内容

确保使用二级 Markdown 标题（##，而不是 #）作为文章中的顶级标题。您在 front matter 中设置的 title 会成为该页面的一级标题。

您应该遵循风格指南，但有以下例外情况

  • 我们允许作者以自己的写作风格撰写文章，只要大多数读者能理解其观点即可。
  • 在多位作者共同撰写的博客文章中，或者文章引言清晰表明作者代表特定团体撰写时，可以使用“我们”。正如您从本节中注意到的那样，虽然我们在文档中避免使用“我们”，但可以做出合理的例外。
  • 我们避免为提示（例如 {{< caution >}}）使用 Kubernetes 短代码（shortcode）。这是因为提示是面向文档读者的，而博客文章不是文档。
  • 关于未来的陈述是可以的，但我们在代表 Kubernetes 发表官方公告时会谨慎使用。
  • 博客文章中使用的代码示例不需要使用 {{< code_sample >}} 短代码，并且通常不使用更好（更容易维护）。

图示和插图

对于插图、图表或流程图，在可行的情况下可以使用figure 短代码。您应该设置 alt 属性以提高可访问性。

对于插图和技术图示，请尽量使用矢量图。博客团队推荐 SVG 格式而非栅格（位图/像素）图示格式，也推荐 SVG 而非 Mermaid（您仍然可以在注释中捕获 Mermaid 源代码）。之所以偏好 SVG 而非 Mermaid，是因为当维护者升级 Mermaid 或更改图示渲染时，他们可能无法轻松联系原博客文章作者以确认更改是否可行。

图示指南是针对 Kubernetes 文档而非博客文章的。与其保持一致仍然很好，但

  • 不需要将图示标注为图 1、图 2 等。

对可缩放（矢量）图片的要求使得不熟悉的人提交文章的过程更加困难；Kubernetes SIG Docs 仍在寻找降低这一门槛的方法。如果您对如何降低门槛有想法，请自愿提供帮助。

对于其他图片（如照片），博客团队强烈建议使用 alt 属性。如果辅助功能软件完全不应提及该图片，则可以使用空的 alt 属性，但这是一种罕见的情况。

Commit 消息

在您将拉取请求标记为准备好审阅时，每个 commit 消息都应该是正在进行的工作的简短摘要。第一个 commit 消息应能作为博客文章的总体描述。

良好 commit 消息的示例

  • 添加关于 Kubernetes foo 功能的博客文章
  • blog: foobar 公告

不良 commit 消息的示例

  • 关于 foo 公告的占位 commit
  • 添加博客文章
  • asdf
  • 初始 commit
  • 草稿文章

合并 (Squashing)

一旦您认为文章已准备好合并，您应该合并您的拉取请求中的 commit；如果您不确定如何操作，可以向博客团队寻求帮助。

最后修改时间 2025 年 4 月 18 日下午 12:56 PST: 更新 submission.md (434c1495f4)