Quality documentation with good examples contributes to the adoption of your plugin.
The documentation that you write for your plugin will be generated and publishedin the Logstash Reference and theLogstash Versioned Plugin Reference.
Documentation is a required component of your plugin.It belongs in a single file called docs/index.asciidoc.The plugin generation utility creates a starter file for you.
Format heading anchors with variables that can support generated IDs. This approachcreates unique IDs when the Logstash Versioned Plugin Referenceis built. Unique heading IDs are required to avoid duplication over multiple versions of a plugin.
Example
Don’t hardcode a heading ID like this: [[config_models]]
Instead, use variables to define it:
[id="plugins-{type}s-{plugin}-config_models"]==== Configuration models
If you hardcode an ID, the Logstash Versioned Plugin Referencebuilds correctly the first time. The second time the doc build runs, the IDis flagged as a duplicate, and the build fails.
Correct link formatting is essential for directing users to the content youwant them to see. Incorrect link formatting or duplicate links can break thedocumentation build. Let’s not do that.
Use angle brackets to format links to content in the same asciidoc file.
Example
This link:
<<plugins-{type}s-{plugin}-config_models>>
Points to this heading in the same file:
[id="plugins-{type}s-{plugin}-config_models"]==== Configuration models
Use external link syntax for links that point to documentation for other plugins or content in the Logstash Reference Guide.
Examples
{logstash-ref}/plugins-codecs-multiline.html[Multiline codec plugin]
{logstash-ref}/getting-started-with-logstash.html
If you don’t specify link text, the URL is used as the link text.
Examples
If you want your link to display as http://www.elastic.co/guide/en/logstash/7.0/getting-started-with-logstash.html, use this format:
{logstash-ref}/getting-started-with-logstash.html
If you want your link to display as Getting Started with Logstash, use this format:
{logstash-ref}/getting-started-with-logstash.html[Getting Started with Logstash]
We all love code samples. Asciidoc supports code blocks and config examples.To include Ruby code, use the asciidoc [source,ruby]
directive.
Note that the hashmarks (#) are present to make the example render correctly.Don’t include the hashmarks in your asciidoc file.
# [source,ruby]# -----# match => {# "field1" => "value1"# "field2" => "value2"# ...# }# -----
The sample above (with hashmarks removed) renders in the documentation like this:
match => { "field1" => "value1" "field2" => "value2" ...}
Plugin documentation goes through several steps before it gets published in theLogstash Versioned Plugin Reference and the Logstash Reference.
Here’s an overview of the workflow:
index.asciidoc
file, the changelog.md
file, and the gemspec).index.asciidoc
file for inclusion in the doc build.We’re not done yet.
index.asciidoc
file for inclusion in the doc build.For more asciidoc formatting tips, see the excellent reference athttps://github.com/elastic/docs#asciidoc-guide.
For tips on contributing and changelog guidelines, seeCONTRIBUTING.md.
For general information about contributing, seeContributing to Logtash.