文档是插件的必要组成部分。高质量的文档以及良好的示例有助于你的插件被采用。
你为插件编写的文档将在 Logstash 参考 和 Logstash 版本化插件参考 中生成和发布。
Logstash 参考中的插件列表
如果你的插件符合我们的要求和质量标准，我们可能会将你的插件列在 Logstash 参考 中。当我们列出你的插件时，我们会指向你插件仓库中的你的文档——readme.md、docs/index.asciidoc 或两者都有。有关此选项的更多信息，请参阅列出你的插件。
以下部分包含在 Github logstash-plugins 组织中托管的插件的文档编写指南。
文档属于一个名为 docs/index.asciidoc 的单独文件。它属于一个名为 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/8.17/getting-started-with-logstash.html，请使用以下格式
{logstash-ref}/getting-started-with-logstash.html
如果你希望你的链接显示为 Logstash 入门，请使用以下格式
{logstash-ref}/getting-started-with-logstash.html[Getting Started with Logstash]
我们都喜欢代码示例。Asciidoc 支持代码块和配置示例。要包含 Ruby 代码，请使用 asciidoc [source,ruby] 指令。
请注意，井号 (#) 的存在是为了使示例正确呈现。不要在你的 asciidoc 文件中包含井号。
# [source,ruby]
# -----
# match => {
# "field1" => "value1"
# "field2" => "value2"
# ...
# }
# -----
上面的示例（删除井号后）在文档中呈现如下
match => {
"field1" => "value1"
"field2" => "value2"
...
}
插件文档在发布到 Logstash 版本化插件参考 和 Logstash 参考 之前要经过几个步骤。
以下是工作流程的概述
- 请确保你已签署贡献者许可协议 (CLA) 并获得所有必要的批准和签字。
- 合并你的插件的拉取请求（包括
index.asciidoc文件、changelog.md文件和 gemspec）。 - 等待持续集成构建成功完成。
- 将插件发布到 https://rubygems.org.cn。
- 脚本会检测新的或更改的版本，并获取
index.asciidoc文件以包含在文档构建中。 - 你的新插件的文档将发布在 Logstash 版本化插件参考 中。
我们还没完成。
- 对于每个版本，我们将新的和更改的文档文件打包到一个拉取请求中，以添加或更新内容。（如果我们对插件文档进行重大更改或添加新插件，我们有时会在版本之间打包插件文档。）
- 脚本会检测新的或更改的版本，并获取
index.asciidoc文件以包含在文档构建中。 - 我们创建一个拉取请求，并将新的和更改的内容合并到相应的版本分支中。
- 对于新插件，我们在 Logstash 参考 的插件列表中添加一个链接。
- 你的新的（或更改的）插件的文档将发布在 Logstash 参考 中。
有关更多 asciidoc 格式设置技巧，请参阅 https://github.com/elastic/docs#asciidoc-guide 上的优秀参考。
有关贡献和更改日志指南的提示，请参阅 CONTRIBUTING.md。
有关贡献的一般信息，请参阅 为 Logstash 做贡献。