elasticsearch Documentation

1. Project Overview & Quickstart (elastic/elasticsearch) Copy Chapter

Elasticsearch docs

[!IMPORTANT]
Elastic docs migration from asciidoc to Markdown is ongoing for 9.0.
Elasticians can reach out in #docs or #es-docs on Slack if you have questions.

[!TIP]
If you need to update the 8.x docs, you'll have to use the old asciidoc system. Refer to the 8.x README for more information.

This is a guide for writing, editing, and building the Elasticsearch docs.

Where do the docs source files live? Copy Chapter

As of 9.0.0, the Elasticsearch docs have been redistributed as part of the Elastic docs migration, with the aim of telling a more cohesive story across Elastic products, features, and tools.

Docs live in three places:

1. Reference content lives in this repo. This covers low-level stuff like settings and configuration information that is tightly coupled to code.

• 👩🏽‍💻 Engineers own the bulk of this content.

2. API reference docs live in the Elasticsearch specification
   • This is where you need to update API docs published in the new API docs system

• 👩🏽‍💻 Engineers own this content.

3. Narrative, overview, and conceptual content mostly lives in the docs-content repo.

• ✍🏼 Tech writers own the bulk of this content.

Where can I find the source files for a specific page? Copy Section

Once the docs are published, you'll be able to choose the Edit this page option to find the source file in the appropriate GitHub repo.

In the meantime, grep around in the Elasticsearch or docs-content repos to identify the source file.

Build the docs Copy Chapter

For 9.0.0+, all (ex-API reference) docs are written in Elastic docs V3 Markdown syntax and stored in .md files.

You can:

• Build the docs locally
• Make single-page edits using the GitHub UI

Preview links for PRs Copy Section

For open PRs, a GitHub action generates a live preview of any docs changes. If the check runs successfully, you can find the preview at:

https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull//reference/

To re-run CI checks, an Elastic employee can select the Re-run this job option in the GitHub Actions tab.

Backporting Copy Chapter

[!TIP]
As of 9.0.0, we are currently only publishing from the main branch.
We will continue to backport changes as usual, in case we need to revisit this approach in the future.

If you need to update the 8.x docs, you'll have to use the old asciidoc system. Refer to the 8.x README for more information.

[!NOTE]
If you need to make changes to 9.x docs and 8.x docs, you'll need to use two different workflows:

• For 9.x docs, create a PR using the new Markdown system against the main branch and backport as necessary.
• For 8.x docs, create a PR using the old AsciiDoc system against the 8.x branch and backport the changes to any other 8.x branches needed.

Test code snippets Copy Chapter

[!IMPORTANT]
Snippet testing has been temporarily disabled for Elasticsearch docs. This is a WIP and should be re-enabled soon for the new Markdown docs.

Snippets in console syntax are automatically tested by the command ./gradlew -pdocs check. To test just the docs from a single page, use e.g. ./gradlew -pdocs yamlRestTest --tests "*rollover*".

By default each console snippet runs as its own isolated test. You can manipulate the test execution in the following ways:

• % TEST: Explicitly marks a snippet as a test. Snippets marked this way are tests even if they don't have `` ```
  /* Detailed source-code truncated for AI context efficiency. */

console-result ``: Matches this snippet against the body of the response of the last test. If the response is JSON then order is ignored. If you add `% TEST[continued]` to the snippet after `` console-result `` it will continue in the same test, allowing you to interleave requests with responses to check.

• % TESTRESPONSE: Explicitly marks a snippet as a test response even without ```console-result. Similarly to % TEST this is mostly used for its modifiers.

  • You can't use ```console-result immediately after % TESTSETUP. Instead, consider using % TEST[continued] or rearrange your snippets.

  [!NOTE]
  Previously we only used % TESTRESPONSE instead of ```console-result so you'll see that a lot in older branches but we prefer `` ```
  /* Detailed source-code truncated for AI context efficiency. */

startyaml
  - compare_analyzers: {index: thai_example, first: thai, second: rebuilt_thai}
endyaml

This allows slightly more expressive testing of the snippets. Since that syntax is not supported by ```console the usual way to incorporate it is with a % TEST[s//] marker like this:

% TEST[s/\n$/\nstartyaml\n  - compare_analyzers: {index: thai_example, first: thai, second: rebuilt_thai}\nendyaml\n/]

Any place you can use json you can use elements like $body.path.to.thing which is replaced on the fly with the contents of the thing at path.to.thing in the last response.

2. Official Technical Reference & Guides (elastic/docs-content) Copy Chapter

Elastic Docs Content

This repo is the source for the narrative user documentation published at https://www.elastic.co/docs/: concepts, guides, and troubleshooting for Elastic products. It covers current versions and deployments: Elastic Stack v9 and Serverless, Elastic Cloud Enterprise v4, Elastic Cloud on Kubernetes v3 and later, Elastic Cloud Hosted, and a range of Elastic tools.

Pages are MyST Markdown with Elastic extensions, built by docs-builder. After a merge to main, the published site refreshes within minutes.

What belongs here, and what doesn't Copy Chapter

This repo hosts the cross-product, narrative user documentation for the products and versions above. Some content lives elsewhere:

• Reference docs that sit next to the code they describe. Reference content generated from or maintained alongside a codebase stays in that code repo. API references are the clearest case: they're generated from OpenAPI specs, most often in elastic/kibana or elastic/elasticsearch-specification, not authored as Markdown here. The same holds for other in-repo reference material that ships with the product.
• Legacy-version content. Documentation for versions earlier than the ones this repo covers, essentially Elastic v8 and before, lives in the respective code repositories, on older branches, in AsciiDoc, and is not built by docs-builder. Update those repos directly when relevant, but only for a clear product behavior change or critical fix.

Repository layout Copy Chapter

Key files:

Reusable prose lives in _snippets/ folders and is pulled in with an include directive. Check for an existing snippet before duplicating content across pages.

Contribute Copy Chapter

New to contributing? Start with the contribution guide, which covers our style, content types, and how to build and preview locally with docs-builder.

If you find any bugs in our documentation, or want to request an enhancement, open an issue. We also welcome contributions in the form of PRs. Before you submit a PR, make sure that you have signed our Contributor License Agreement.

We write our docs in Markdown. Refer to our syntax quick reference for examples and additional functionality. If you contribute with the help of AI agents or tools, see AGENTS.md and AI.md.

Preview your changes Copy Section

When you open a PR, your changes are built, deployed, and ready to be previewed within minutes.

License Copy Chapter

This work is licensed under a
Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International License.