## 1. Project Overview & Quickstart (elastic/elasticsearch)

# 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](https://github.com/elastic/elasticsearch/blob/8.x/docs/README.asciidoc) for more information.

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

## Where do the docs source files live?

As of 9.0.0, the Elasticsearch docs have been redistributed as part of the [Elastic docs migration](https://elastic.github.io/docs-builder/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](https://github.com/elastic/elasticsearch-specification/blob/main/README.md#how-to-generate-the-openapi-representation)
    - This is where you need to update API docs published in the [new API docs system](https://www.elastic.co/docs/api/doc/elasticsearch/v8/)
- 👩🏽‍💻 **Engineers** own this content.
3. **Narrative, overview, and conceptual content** mostly lives in the [`docs-content`](https://github.com/elastic/docs-content/) repo. 
- ✍🏼 **Tech writers** own the bulk of this content.

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

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

For 9.0.0+, all (ex-API reference) docs are written in [Elastic docs V3 Markdown syntax](https://elastic.github.io/docs-builder/syntax/) and stored in `.md` files.

You can:
* Build the [docs locally](https://elastic.github.io/docs-builder/contribute/locally/)
* Make single-page edits using the [GitHub UI](https://elastic.github.io/docs-builder/contribute/on-the-web/)

### Preview links for PRs

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

> [!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](https://github.com/elastic/elasticsearch/blob/8.x/docs/README.asciidoc) 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

> [!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)

# 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](https://elastic.github.io/docs-builder/). After a merge to `main`, the published site refreshes within minutes.

## What belongs here, and what doesn't

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

| Path | What it documents |
|---|---|
| `get-started/` | Onboarding and first-run content across products. Fundamental knowledge about Elastic |
| `solutions/` | Docs for solutions and serverless project types packaged on top of Elasticsearch and Kibana: Search, Observability, Security, Vector DB |
| `explore-analyze/` | Home for core Kibana features such as Discover, dashboards, visualizations, alerting, AI features, ML |
| `deploy-manage/` | Deploying, scaling, securing, and operating orchestrators, clusters, deployments, and projects |
| `manage-data/` | Ingesting, transforming, and lifecycle-managing data |
| `reference/` | Reference material such as settings, APIs, CLIs, and config that isn't naturally sitting in other code repos |
| `troubleshoot/` | Troubleshooting and diagnostics |
| `release-notes/` | Release notes and changelogs for Elastic products. Generally generated from code changes. |
| `cloud-account/` | Elastic Cloud account and billing |
| `extend/` | Extending and integrating with Elastic, for external developers |
| `contribute-docs/` | The public contribution guide: style, content types, cumulative docs, syntax |
| `serverless/`, `archive.md` | Serverless landing content and archived material. This content should not be updated. It's legacy and no longer published. |

Key files:

| File | Purpose |
|---|---|
| `docset.yml` | Site config: navigation, products, substitutions |
| `redirects.yml` | Redirect map for moved, renamed, or deleted pages. Update it when you move or delete a page. |
| `frontmatter.config.yml` | Frontmatter schema and defaults |
| `versions.md` | Version and lifecycle reference |

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

New to contributing? Start with the [contribution guide](https://www.elastic.co/docs/contribute-docs), which covers our style, content types, and how to [build and preview locally with docs-builder](https://www.elastic.co/docs/contribute-docs/locally).

If you find any bugs in our documentation, or want to request an enhancement, [open an issue](https://github.com/elastic/docs-content/issues). We also welcome contributions in the form of PRs. Before you submit a PR, make sure that you have signed our [Contributor License Agreement](https://www.elastic.co/contributor-agreement/).

We write our docs in Markdown. Refer to our [syntax quick reference](https://elastic.co/docs/contribute-docs/syntax-quick-reference) for examples and additional functionality. If you contribute with the help of AI agents or tools, see [`AGENTS.md`](AGENTS.md) and [`AI.md`](AI.md).

### Preview your changes

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

## License

[![CC BY-NC-ND 4.0][cc-by-nc-nd-image]][cc-by-nc-nd] [![CC BY-NC-ND 4.0][cc-by-nc-nd-shield]][cc-by-nc-nd]

This work is licensed under a
[Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International License][cc-by-nc-nd].

[cc-by-nc-nd]: http://creativecommons.org/licenses/by-nc-nd/4.0/
[cc-by-nc-nd-image]: https://licensebuttons.net/l/by-nc-nd/4.0/88x31.png
[cc-by-nc-nd-shield]: https://img.shields.io/badge/License-CC%20BY--NC--ND%204.0-lightgrey.svg