向 Kubernetes 博客提交文章

有两个官方 Kubernetes 博客，CNCF 也有自己的博客，你也可以在上面介绍 Kubernetes。对于主 Kubernetes 博客，我们（Kubernetes 项目）喜欢发布具有不同视角和特别侧重点的文章，这些文章与 Kubernetes 相关。

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

为 Kubernetes 博客撰写文章

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

推荐路线

Kubernetes 项目推荐的方法是：通过联系博客团队来推销你的文章。你可以通过 Kubernetes Slack（#sig-docs-blog）进行操作。对于仅想发布到贡献者博客的文章，你也可以直接联系 SIG ContribEx comms。

除非你的提交有问题，否则博客团队/SIG ContribEx 将为你匹配

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

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

编辑将帮助你完成从草稿到发布的整个过程。他们将直接批准你的文章发布，或者安排批准流程。

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

从 pull request 开始

第二种为我们的博客撰写文章的途径是直接在 GitHub 上开始一个 pull request。博客团队实际上并不推荐这样做；GitHub 对于代码协作非常有用，但并不适合散文文本。

可以只包含一个空 commit 的占位符 pull request，然后在其他地方工作，然后再返回到你的占位符 PR，这是完全没问题的。

与推荐路线类似，我们将尝试为你匹配一位写作伙伴和一位博客编辑。他们将帮助你准备好文章以供发布。

发布后博客文章流程

第三种途径是关于 Kubernetes 发布相关变化的博客文章。每次发布时，发布沟通团队将接管博客的发布计划。为发布添加功能的人，或者计划其他项目需要宣布的变更的人，可以与发布沟通团队协调，以计划、起草、编辑并最终发布他们的文章。

文章排期

对于 Kubernetes 博客，博客团队通常将博客文章安排在工作日（公历，如美国和其他国家使用）发布。当需要在周末发生的特定日期发布时，博客团队会尽量安排。

关于撰写博客文章的部分解释了该做什么

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

当 Prow 机器人合并你写的 PR 时，它将是草稿状态，不会被设置为发布。然后，Kubernetes 贡献者（你、你的写作伙伴或博客团队的某人）将打开一个小型后续 PR，将其标记为发布。合并第二个 PR 将发布之前处于草稿状态的文章，使其能够自动发布。

在文章计划发布的那天，自动化将触发网站构建，你的文章将可见。

撰写文章

在您推销后，我们将鼓励您使用 HackMD（一个 Web Markdown 编辑器）或 Google 文档来共享文章文本的可编辑版本。您的写作伙伴可以阅读您的草稿文本，然后直接提出建议或提供其他反馈。他们还应该让您知道您正在起草的反馈是否符合博客指南。

同时，您通常将成为他们的写作伙伴，并可以遵循我们关于支持他们工作的指南。

初步行政步骤

如果您尚未签署 CLA，则应尽快签署。最好尽早开始此操作；如果您是作为工作的一部分写作，您可能需要与您所在公司的法律团队或经理确认，以确保您被允许签署。

初步起草

博客团队建议您使用 HackMD（一个 Web Markdown 编辑器）或 Google 文档来准备和共享文章文本的初始、实时可编辑版本。

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

在此阶段，请不要过于担心 Markdown 格式是否完全正确。

如果您有图片，可以粘贴一个位图副本以供早期反馈。博客团队可以在稍后的过程中帮助您准备插图以供最终发布。

用于发布的 Markdown

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

如果您还不熟悉，请阅读贡献基础知识。本页的这一部分假设您没有本地克隆的 fork，并且您正在使用 GitHub Web UI 工作。如果您还没有，您确实需要创建一个远程 fork（fork）网站存储库。

在 GitHub 存储库中，点击“创建新文件”按钮。从 HackMD 或 Google Docs 复制现有内容，然后粘贴到编辑器中。在本节的后面有更多关于该文件内容的详细信息。将文件命名为与博客文章的拟议标题相匹配，但不要在文件名中包含日期。博客审阅者将与您一起确定最终文件名和文章的发布日期。

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

文章内容

请确保使用二级 Markdown 标题（## 而不是 #）作为文章的最高标题级别。您在 front matter 中设置的 title 将成为该页面的第一级标题。

您应遵循风格指南，但有以下例外：

• 我们允许作者以自己的写作风格写文章，只要大多数读者都能理解其要点即可。
• 可以使用“我们”来撰写有多位作者的文章，或者当文章引言清楚表明作者代表特定团体写作时。正如您从本节注意到的，尽管我们在文档中避免使用“我们”，但在可以证明例外的情况下使用它是可以的。
• 我们避免在 Kubernetes 中使用短代码（shortcodes）来表示呼吁（例如 {{< caution >}}）。这是因为呼吁是针对文档阅读者的，而博客文章不是文档。
• 关于未来的陈述是可以的，尽管我们在代表 Kubernetes 发表官方公告时会谨慎使用。
• 博客文章中使用的代码示例不需要使用 {{< code_sample >}} 短代码，而且通常情况下不使用它们更好（更容易维护）。

图表和插图

对于插图、图表或示意图，如果可行，可以使用figure 短代码。为了无障碍访问，您应设置 alt 属性。

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

《图表指南》是针对 Kubernetes 文档的，而不是博客文章。遵循它仍然很好，但是：

• 无需将图表标注为图 1、图 2 等。

对可缩放（矢量）图像的要求增加了对不太熟悉的人提交文章的难度；Kubernetes SIG Docs 将继续寻找降低这一门槛的方法。如果您有关于如何降低门槛的想法，请志愿提供帮助。

对于其他图片（如照片），博客团队强烈鼓励使用 alt 属性。如果无障碍软件不应提及图片，可以使用空的 alt 属性，但这是一种罕见情况。

Commit 消息

当您将 pull request 标记为可审阅时，每个 commit 消息都应该是对正在进行的工作的简短总结。第一个 commit 消息应作为博客文章的整体描述而有意义。

良好 commit 消息的示例

• 为 foo Kubernetes 功能添加博客文章
• 博客：foobar 公告

不良 commit 消息的示例

• foo 公告的占位符 commit
• 添加博客文章
• asdf
• 初始 commit
• 草稿帖子

Squashing

一旦您认为文章已准备好合并，您应该压缩（squash）您的 pull request 中的 commits；如果您不确定如何操作，可以向博客团队寻求帮助。