文档是插件的必要组成部分。高质量的文档以及良好的示例有助于提高插件的采用率。
您为插件编写的文档将在 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.14/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 做贡献。