Rename legacy-docs to asciidoc-guide, remove .md from docs-builder URLs

Author: leemthompo

contribute-docs/_snippets-contribute/guide-intro.md

@@ -1,3 +1,3 @@
-To contribute to elastic.co/guide, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses ASCIIDoc as its markup language.
+To contribute to `elastic.co/guide` (Asciidoc), you must work with our [Asciidoc documentation build system](https://github.com/elastic/docs). This system uses ASCIIDoc as its markup language.
 
 Docs for {{stack}} 8.x, {{ece}} 3.x, and {{eck}} 2.x can all be found on this site.

contribute-docs/_snippets-contribute/two-systems.md

@@ -1,6 +1,6 @@
 Because the new documentation site only hosts documentation for newer releases, the way that you contribute depends on the version that you want to document.
 
-For a list of versions covered on [elastic.co/docs](https://www.elastic.co/docs), refer to [Find docs for your product version](https://www.elastic.co/docs/get-started/versioning-availability#find-docs-for-your-product-version). Versions prior to the versions listed on that page are documented on our legacy system, [elastic.co/guide](https://www.elastic.co/guide). 
+For a list of versions covered on [elastic.co/docs](https://www.elastic.co/docs) (Markdown), refer to [Find docs for your product version](https://www.elastic.co/docs/get-started/versioning-availability#find-docs-for-your-product-version). Versions prior to the versions listed on that page are documented on [elastic.co/guide](https://www.elastic.co/guide) (Asciidoc). 
 
 :::{tip}
 Unversioned products, such as {{ech}} and {{serverless-full}}, are documented on [elastic.co/docs](https://www.elastic.co/docs).

contribute-docs/legacy-docs.md renamed to contribute-docs/asciidoc-guide.md

@@ -1,14 +1,14 @@
 ---
-navigation_title: Contribute to legacy docs
+navigation_title: Contribute to Asciidoc docs
 ---
 
-# Contribute to legacy documentation
+# Contribute to `elastic.co/guide` (Asciidoc)
 
-To contribute to pages that live at [elastic.co/guide](https://www.elastic.co/guide/index.html), you must work with our [legacy documentation build system](https://github.com/elastic/docs).
+To contribute to pages that live at [elastic.co/guide](https://www.elastic.co/guide/index.html), you must work with our [Asciidoc documentation build system](https://github.com/elastic/docs).
 
 This system uses the [ASCIIDoc](https://asciidoc.org/) markup language.
 
-The following versions are considered legacy and use this system:
+The following versions use this system:
 
 - {{stack}}: `8.x` and earlier
 - {{ece}}: `3.x` and earlier
@@ -31,7 +31,7 @@ If you are working in a repo like Kibana or the cloud repo, backports can be com
 
 ## Contribute locally
 
-For complex or multi-page updates to legacy documentation, refer to the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation).
+For complex or multi-page updates to `elastic.co/guide` (Asciidoc) documentation, refer to the [Asciidoc documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation).
 
 ## Updating docs in both systems
 
@@ -44,4 +44,4 @@ If you need to merge changes that are published in both systems (usually because
    2. If you just need to port a specific section you can use: `pandoc -f gfm -t asciidoc ./<file-name>.md` and the output of the file will be in your command window from which you can copy.
 4. Follow the steps in [Contribute on the web](#contribute-on-the-web) to publish your changes.
 5. If the change is too large or complicated, create a new issue in the [`docs-content`](https://github.com/elastic/docs-content) or [`docs-content-internal`](https://github.com/elastic/docs-content-internal) repository detailing the changes made for the team to triage.
-6. Merge the changes and close the issue once the updates are reflected in the documentation.
+6. Merge the changes and close the issue (if applicable) once the updates are reflected in the documentation.

contribute-docs/index.md

@@ -4,29 +4,32 @@ navigation_title: Contribute to the docs
 
 # Contribute to Elastic documentation
 
-In April 2025, Elastic migrated to a new documentation system at [elastic.co/docs](https://www.elastic.co/docs), using Markdown and the [`docs-builder`](https://elastic.github.io/docs-builder/) toolchain.
+In April 2025, Elastic migrated to a new documentation system at [elastic.co/docs](https://www.elastic.co/docs), using Markdown and the [`docs-builder`](https://elastic.github.io/docs-builder/) toolchain, which coincided with the release of {{stack}} 9.0.0, {{ece}} 4.0.0, and {{eck}} 3.0.0.
 
-This documentation site includes docs for
+This documentation site includes docs for:
 - {{stack}} 9.x
 - {{ece}} 4.x
 - {{eck}} 3.x
-- All unversioned products like {{ech}} and {{serverless-full}}.
+- {{ech}}
+- {{serverless-full}}
+
+Refer to [versioning and availability](/get-started/versioning-availability.md) to learn more.
 
 This documentation is [**cumulative**](how-to/cumulative-docs/index.md): a new set of docs is not published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes.
 
 :::{tip}
 To learn more about the new docs UX, read [how to use the documentation](/get-started/howto-use-the-docs.md).
 :::
 
-## Contribute to current docs
+## Contribute to `elastic.co/docs` (Markdown)
 
 |System|What it covers|Published at|Format|How to contribute
 |----|----|----|----|----|----|
 |Main docs|Guides, troubleshooting, release notes, etc.|[elastic.co/docs](https://www.elastic.co/docs)|Markdown|- [On the web](on-the-web.md) (quick edits) <br> - [Locally](locally.md) (complex changes) <br> - [Syntax guide](syntax/index.md)|
 |API references|Elastic REST APIs|[elastic.co/docs/api](https://www.elastic.co/docs/api/)|[OpenAPI](https://swagger.io/specification/)|[Contribute to API docs](api-docs/index.md)|
 
 :::{note}
-If you need to update documentation in both the current and legacy systems, you'll need two separate PRs. Refer to [Updating docs in both systems](legacy-docs.md#updating-docs-in-both-systems).
+If you need to update documentation in both the MarkDown and Asciidoc systems, you'll need two separate PRs. Refer to [Updating docs in both systems](asciidoc-guide.md#updating-docs-in-both-systems).
 :::
 
 ## Report issues or request features
@@ -36,8 +39,8 @@ If you need to update documentation in both the current and legacy systems, you'
 |Documentation|- [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) or [fix it yourself](locally.md) <br> - Elastic employees can use the [internal repo](https://github.com/elastic/docs-content-internal/issues/new/choose)|
 |`docs-builder`|- [Bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml) <br> - [Discussion](https://github.com/elastic/docs-builder/discussions)|
 
-## Contribute to legacy docs
+## Contribute to `elastic.co/guide` (Asciidoc)
 
 |System|What it covers|Published at|Format/toolchain|How to contribute
 |----|----|----|----|----|----|
-|Legacy docs|Elastic docs & API references for 8.x and earlier|[elastic.co/guide](https://www.elastic.co/guide/index.html)|Asciidoc|[Contribute to legacy docs](./legacy-docs.md)|
+|`elastic.co/guide` (Asciidoc)|Elastic docs & API references for 8.x and earlier|[elastic.co/guide](https://www.elastic.co/guide/index.html)|Asciidoc|[Contribute to the Asciidoc docs](./asciidoc-guide.md)|

contribute-docs/locally.md

@@ -113,7 +113,7 @@ This documentation is **cumulative**. This means that a new set of docs is not p
 
 ## Build the docs
 
-Before pushing your changes, verify all of them locally .
+Before pushing your changes, verify them locally by running:
 
 ```
 docs-builder
@@ -130,7 +130,7 @@ After you've made your changes locally:
 
 ## Preview locally [#local-docs-preview]
 
-Static-site generators like docs-builder can serve docs locally. This means you can edit the source and see the result in the browser in real time.
+`docs-builder` can serve docs locally. This means you can edit the source and see the result in the browser in real time.
 
 To serve the local copy of the documentation in your browser, follow these steps:
 

contribute-docs/on-the-web.md

@@ -30,7 +30,7 @@ For more details on editing files on GitHub, refer to [GitHub's documentation on
 :::{include} _snippets-contribute/tagged-warning.md
 :::
 
-## Editing legacy docs
+## Editing `elastic.co/guide` docs (Asciidoc)
 
-If you need to contribute to [elastic.co/guide](https://elastic.co/guide) pages, refer to [Contribute to legacy documentation](legacy-docs.md) to learn about the asciidoc system.
+If you need to contribute to [elastic.co/guide](https://elastic.co/guide) pages, refer to [Contribute to `elastic.co/guide` (Asciidoc)](asciidoc-guide.md) to learn about the Asciidoc system.
 

contribute-docs/syntax/index.md

@@ -8,8 +8,8 @@ The [quick reference](quick-ref.md) provides a cheat sheet of commonly used synt
 
 ## Full syntax reference
 
-For the complete syntax documentation, refer to the [full syntax reference](https://elastic.github.io/docs-builder/syntax/) in the `elastic/docs-builder` repository.
+For the full syntax reference, go to [elastic.github.io/docs-builder/syntax/](https://elastic.github.io/docs-builder/syntax/).
 
-## Contributing to legacy docs
+## Contributing to `elastic.co/guide` (Asciidoc)
 
-If you need to work on [elastic.co/guide](https://elastic.co/guide) pages (written in AsciiDoc), refer to [Contribute to legacy documentation](../legacy-docs.md).
+If you need to work on [elastic.co/guide](https://elastic.co/guide) pages (written in AsciiDoc), refer to [Contribute to `elastic.co/guide` (Asciidoc)](../asciidoc-guide.md).

contribute-docs/syntax/quick-ref.md

@@ -114,7 +114,9 @@ A default anchor is automatically created for each [heading](#headings), in the
 
 ## Applies to
 
-Tags that identify technical contexts: the feature base (stack/serverless), deployments, and project types that a piece of content "applies to." Use `applies_to` tags to help users determine whether content is right for their deployments and configuration. These tags are a [version content pattern](../how-to/cumulative-docs/example-scenarios.md) in Elastic Docs v3.
+Use applies_to metadata to tag content for specific contexts, for example whether a feature is available on certain products, versions, or deployment types.
+
+This metadata enables you to write [cumulative documentation](../how-to/cumulative-docs/index.md), because Elastic no longer publishes separate docs sets for every minor release.
 
 **Example: Section tag**
 
@@ -134,7 +136,11 @@ stack:
 ```
 :::
 
-For full syntax and more examples, see [](https://elastic.github.io/docs-builder/syntax/applies).
+For full syntax and more examples, refer to [the `applies_to` documentation](https://elastic.github.io/docs-builder/syntax/applies).
+
+:::{tip}
+The syntax for `applies_to` metadata differs depending on whether it's added at the [page level](https://elastic.github.io/docs-builder/syntax/applies/#page-level) (in frontmatter), [section level](https://elastic.github.io/docs-builder/syntax/applies/#section-level) (after a heading), or [inline](https://elastic.github.io/docs-builder/syntax/applies/#inline-level).
+:::
 
 <!--
 :::{tip}
@@ -152,7 +158,6 @@ The `applies_to` tags are scope signals for readers, not comprehensive metadata.
 **DON'Ts**<br>
 ❌ **Don't:** Include `applies_to` tags in admonitions<br>
 ❌ **Don't:** Add `applies_to` tags to general, broadly applicable content<br>
-❌ **Don't:** Use `Coming (x.x.x)` tags, except in special cases (don't pre-announce features)
 <br>
 <br>
 

contribute-docs/toc.yml

@@ -30,4 +30,4 @@ toc:
           - file: kibana-api-docs-quickstart.md
       - file: workflows.md
       - file: help.md
-  - file: legacy-docs.md
+  - file: asciidoc-guide.md