Contributing to the docs

The Beats documentation is Markdown in docs/, built by docs-builder. docs/docset.yml defines the docset.

Beats does not publish production docs from main. The branch each published environment builds is the beats entry in docs-builder assembler.yml: production builds current, staging builds next, and edge builds edge. Read those three refs there. A docs change is on the live site only once it is on the current branch. Open the pull request against main, as Contribute to Beats describes, and backport it to the current branch when it should be live now.

• docs/reference/<beat>/ is the reference for that Beat. docs/reference/libbeat/ is shared by all Beats.
• docs/extend/ is this developer guide.
• docs/release-notes/ holds the breaking changes, deprecations, and known issues. Its top-level pages are maintained by hand. The release entries under _snippets/ are generated from changelog fragments by .github/workflows/release-notes.yml.
• docs/reference/_snippets/ holds text included by more than one page. Edit a snippet only when every page that includes it should change.

For wording, follow the Elastic style guide. Write what you can now do, see, or configure. Use "you", present tense, and sentence case headings. Put settings, field names, and file names in backticks.

Product names that have a substitution in docs/docset.yml are written as {{filebeat}}, {{agent}}, {{kib}}, and the rest of that list. Match the page you are editing.

Add to the page that already covers the topic. Add a new page only when no existing page can carry it, and then add it to that section's toc.yml.

Look through docs/ and the published docs before you add a page. Each fact belongs in one place. Link to it from the other pages instead of repeating it.

A page you move, rename, or delete needs an entry in docs/redirects.yml.

Link to a page in another Elastic docset with its docset link (docs-content://..., integration-docs://...), not with a URL on elastic.co.

Since Elastic Stack 9.0.0, one page stays valid across versions. Mark a version or deployment difference with applies_to on the page or on the section that differs, instead of copying the page. Read Write cumulative documentation and the applies_to reference.

When a GA or deprecated feature, field, or setting is removed from a versioned product, keep the content and mark it removed <version> with applies_to. Readers on versions that still have it need the page. Delete it only when it was only ever a preview or beta, or only ever existed in a product that has no versions.

For generated content, the version label comes from fields.yml. See Update fields.yml. Do not edit applies_to in the generated Markdown. The next make update overwrites it.

Edit most Markdown files directly. These are generated, and each one says so with % This file is generated! at the top of the body:

• Exported fields, for example AWS fields
• Module docs, for example the AWS module
• Metricset and dataset docs, for example the AWS billing metricset

The comment names the script that writes the file. Edit the source, then regenerate. An edit to the generated file is overwritten on the next run.

The fields.yml files in _meta directories describe the fields a module, dataset, fileset, or metricset emits.

• title becomes the page title, so capitalize it.
• description is full sentences with punctuation.
• version becomes the applies_to label on the generated page. Use preview, beta, ga, deprecated, and removed. A field can carry more than one, to show how it changed:

version:
  preview: 9.0.0
  beta: 9.1.0
  ga: 9.2.0
  deprecated: 9.3.0
		

The source can include a patch version, but the rendered badge displays the major and minor version and applies to the latest patch of that minor.

The docs.md files in _meta directories are the source for generated module documentation.

After you edit fields.yml or docs.md, regenerate from the repository root:

1. Use the Go version in .go-version at the root of the branch you are updating. See Setting up your dev environment.
2. Run make update.

Each generated file names the script that writes it in the % This file is generated! comment. That comment is the list. It stays right when a script moves, and a list kept here would not.

A docs-only change does not get a changelog fragment. Add the skip-changelog label. A user-visible behavior change still gets a fragment, as AGENTS.md describes, and the fragment stays out of the doc page.