记录您的插件文档

文档是插件的必要组成部分。高质量且带有良好示例的文档有助于推广您的插件。

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

以下各节包含为托管在 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://esdocs.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 参考指南》之前，需要经过几个步骤。

这是工作流程概述

• 请确保您已签署贡献者许可协议 (CLA)，并获得了所有必要的批准和许可。
• 合并您的插件的拉取请求（包括 index.asciidoc 文件、changelog.md 文件和 gemspec）。
• 等待持续集成构建成功完成。
• 将插件发布到 https://rubygems.org.cn。
• 脚本会检测到新的或更改的版本，并提取 index.asciidoc 文件以包含在文档构建中。
• 您新插件的文档将发布在《Logstash 版本化插件参考指南》中。

我们还没有完成。

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

当您更新插件或文档时，请考虑在变更日志 (changelog) 和 gemspec（或版本文件）中增加版本号。版本更改会触发文档构建，从而提取您的更改以进行发布。

有关更多 asciidoc 格式设置技巧，请参阅 https://github.com/elastic/docs#asciidoc-guide 上的优秀参考资料。

有关贡献技巧和变更日志准则，请参阅 CONTRIBUTING.md。

有关贡献的一般信息，请参阅“为 Logstash 做贡献”。