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