格式标准

本页面介绍了 Istio 文档的格式标准。Istio 使用 Markdown 写作内容,并使用 Hugo 构建网站。为确保文档风格一致性,我们应遵循下面这些标准。

不要用大写字母表示强调

直接引用代码或配置文件中的值时,使用原始大小写字母,并使用反引号 `` 包裹该值。例如,应使用 IstioRoleBinding,而不是 Istio Role Bindingistio role binding

如果您不是直接引用值或代码,请使用普通的写法,例如,”The Istio role binding configuration takes place in a YAML file.”

使用尖括号作占位符

对于命令或代码示例,使用尖括号作占位符。并告诉读者占位符代表的是什么。例如:


1. 显示 pod 相关的信息:

    {{< text bash >}}
    $ kubectl describe pod <pod-name>
    {{< /text >}}

    其中 `<pod-name>` 是您一个 Pod 的名称。

使用 加粗 强调内容

正确做法错误做法
点击 Fork点击 “Fork”。
选择 Other选择 ‘Other’。

使用斜体强调新术语

正确做法错误做法
cluster 指的是节点的集合……_cluster_指的是节点的集合……
这些组件构成了 _控制平面_。这些组件构成了 控制平面

将新术语添加至术语表,并使用 gloss 短代码。

使用反引号包裹文件名、目录和路径

正确做法错误做法
打开 foo.yaml 文件。打开 foo.yaml 文件。
移动到 /content/en/docs/tasks 目录。移动到 /content/en/docs/tasks 目录。
打开 /data/args.yaml 文件。打开 /data/args.yaml 文件。

使用反引号包裹行内代码和命令

正确做法错误做法
foo run 命令创建了 Deployment“foo run” 命令创建了 Deployment
对于声明式管理,请使用 foo apply对于声明式管理,请使用 “foo apply”。

您希望读者执行的命令,应放到代码块中。行内代码和命令仅用于提及特定的标签、标志、值、函数、对象、变量、模块或命令。

使用反引号包裹对象字段名称

正确做法错误做法
设置配置文件中 ports 字段的值。设置配置文件中“ports”字段的值。
rule 字段的值是一个 Rule 类型的对象。“rule”字段的值是一个“Rule”类型的对象。
这些信息有用吗?
Do you have any suggestions for improvement?

Thanks for your feedback!