格式标准

本页面介绍了 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!