记录你的插件

文档是您插件的必需组成部分。高质量的文档和良好的示例有助于您的插件被广泛采用。

您为插件编写的文档将在 Logstash 参考和 Logstash 版本化插件参考中生成和发布。

Logstash 参考中的插件列表

如果您的插件符合我们的要求和质量标准，我们可能会在 Logstash 参考中列出您的插件。当您列出插件时，我们会指向您插件仓库中的您的文档—即 readme.md、docs/index.asciidoc，或两者都指向。有关此选项的更多信息，请参阅列出您的插件。

以下各节包含在 Github logstash-plugins 组织中托管的插件文档指南。

文档文件

文档应放在一个名为 docs/index.asciidoc 的文件中。插件生成实用工具会为您创建一个入门文件。

使用可支持生成 ID 的变量格式化标题锚点。此方法在构建 Logstash 版本化插件参考时创建唯一的 ID。需要唯一的标题 ID 以避免在插件的多个版本之间发生重复。

示例

不要像这样硬编码插件标题 ID：[[config_models]]

而是使用变量来定义它

		[id="plugins-{type}s-{plugin}-config_models"]
==== Configuration models

如果您硬编码 ID，Logstash 版本化插件参考将在第一次构建时正确生成。第二次运行文档构建时，ID 会被标记为重复，构建将失败。

正确的链接格式对于将用户引导至您希望他们看到的内容至关重要。错误的链接格式或重复链接可能会破坏文档构建。我们不希望这样。

使用尖括号格式化指向同一 asciidoc 文件中内容的链接。

示例

此链接

<<plugins-{type}s-{plugin}-config_models>>

指向同一文件中的此标题

		[id="plugins-{type}s-{plugin}-config_models"]
==== Configuration models

使用外部链接语法链接到其他插件的文档或 Logstash 参考指南中的内容。

示例

{logstash-ref}/plugins-codecs-multiline.html[Multiline codec plugin]

{logstash-ref}/getting-started-with-logstash.html

如果您不指定链接文本，则 URL 将用作链接文本。

示例

如果您希望链接显示为 https://elastic.ac.cn/guide/en/logstash/current/getting-started-with-logstash.html，请使用此格式

{logstash-ref}/getting-started-with-logstash.html

如果您希望链接显示为 Logstash 入门，请使用此格式

		{logstash-ref}/getting-started-with-logstash.html[Getting Started with Logstash]

	

我们对指向数据类型说明（例如 <<boolean,boolean>>）的链接例外，因为它们被频繁使用。我们在转换脚本中有一个清理步骤，可以将链接转换为正确的语法。

我们都喜欢代码示例。Asciidoc 支持代码块和配置示例。要包含 Ruby 代码，请使用 asciidoc [source,ruby] 指令。

请注意，哈希符号 (#) 用于使示例正确渲染。请勿在您的 asciidoc 文件中包含哈希符号。

		# [source,ruby]
# -----
# match => {
#  "field1" => "value1"
#  "field2" => "value2"
#  ...
# }
# -----

	

上面的示例（去掉哈希符号后）在文档中渲染如下

		match => {
  "field1" => "value1"
  "field2" => "value2"
  ...
}

	

插件文档在发布到 Logstash 版本化插件参考和 Logstash 参考之前会经历几个步骤。

以下是工作流程概述

我们还没有完成。

对于每个版本，我们将新的和更改的文档文件打包到一个拉取请求中，以添加或更新内容。（如果我们对插件文档进行了重大更改或添加了新插件，有时会在版本之间打包插件文档。）
脚本会检测新版本或更改的版本，并获取 index.asciidoc 文件以包含在文档构建中。
我们创建一个拉取请求，并将新的和更改的内容合并到相应的版本分支中。
对于新插件，我们会添加一个链接到 Logstash 参考中的插件列表。
您的新插件（或已更改插件）的文档已发布在 Logstash 参考中。

当您更新插件或文档时，请考虑在 changelog 和 gemspec（或 version 文件）中递增版本号。版本更改会触发文档构建，以获取您的更改并发布。

有关更多 asciidoc 格式化技巧，请参阅出色的参考文档：https://github.com/elastic/docs#asciidoc-guide。

有关贡献和 changelog 指南的技巧，请参阅 CONTRIBUTING.md。

有关贡献的一般信息，请参阅贡献 Logstash。