From b57bd9fd8f9ee4aecea85c225afc575bdd6a5b04 Mon Sep 17 00:00:00 2001
From: Liam Thompson <leemthompo@gmail.com>
Date: Wed, 5 Nov 2025 18:22:02 +0100
Subject: [PATCH 1/6] [docs] clean up after migrating some contributions,
 syntax guide

---
 docs/_docset.yml                              | 19 ++++++++---------
 docs/_redirects.yml                           |  5 +++++
 .../assembled-documentation.md                |  2 +-
 docs/building-blocks/index.md                 |  4 ++--
 docs/cli/docset/diff-validate.md              |  2 +-
 docs/cli/docset/index.md                      |  2 +-
 docs/configure/site/index.md                  |  2 +-
 docs/contribute/_snippets/tagged-warning.md   |  4 ++--
 docs/contribute/index.md                      |  3 ++-
 docs/{contribute => how-to}/add-repo.md       |  6 +++++-
 .../branching-strategy.md                     |  2 +-
 docs/how-to/index.md                          | 21 +++++++++++++++++++
 docs/{contribute => how-to}/move.md           |  0
 docs/{contribute => how-to}/redirects.md      |  2 +-
 .../release-new-version.md                    |  4 ++++
 docs/migration/versioning.md                  |  2 +-
 16 files changed, 57 insertions(+), 23 deletions(-)
 rename docs/{contribute => how-to}/add-repo.md (93%)
 rename docs/{contribute => how-to}/branching-strategy.md (99%)
 create mode 100644 docs/how-to/index.md
 rename docs/{contribute => how-to}/move.md (100%)
 rename docs/{contribute => how-to}/redirects.md (99%)
 rename docs/{contribute => how-to}/release-new-version.md (97%)

diff --git a/docs/_docset.yml b/docs/_docset.yml
index 2dfe98c06..0a79609c2 100644
--- a/docs/_docset.yml
+++ b/docs/_docset.yml
@@ -29,20 +29,19 @@ toc:
   - file: index.md
   - hidden: 404.md
   - hidden: developer-notes.md
-  - folder: contribute
+  - hidden: contribute/index.md
+  - hidden: contribute/locally.md
+  - hidden: contribute/on-the-web.md
+  - hidden: contribute/cumulative-docs/index.md
+  - hidden: contribute/cumulative-docs/guidelines.md
+  - hidden: contribute/cumulative-docs/badge-placement.md
+  - hidden: contribute/cumulative-docs/example-scenarios.md
+  - hidden: contribute/cumulative-docs/reference.md
+  - folder: how-to
     children:
       - file: index.md
-      - file: locally.md
-      - file: on-the-web.md
       - file: move.md
       - file: redirects.md
-      - folder: cumulative-docs
-        children:
-          - file: index.md
-          - hidden: guidelines.md
-          - hidden: badge-placement.md
-          - hidden: example-scenarios.md
-          - hidden: reference.md
       - file: branching-strategy.md
       - file: add-repo.md
       - file: release-new-version.md
diff --git a/docs/_redirects.yml b/docs/_redirects.yml
index df2983983..a07c19886 100644
--- a/docs/_redirects.yml
+++ b/docs/_redirects.yml
@@ -24,3 +24,8 @@ redirects:
   'testing/redirects/third-page.md':
     anchors:
       'removed-anchor':
+  'contribute/move.md': 'how-to/move.md'
+  'contribute/redirects.md': 'how-to/redirects.md'
+  'contribute/branching-strategy.md': 'how-to/branching-strategy.md'
+  'contribute/add-repo.md': 'how-to/add-repo.md'
+  'contribute/release-new-version.md': 'how-to/release-new-version.md'
diff --git a/docs/building-blocks/assembled-documentation.md b/docs/building-blocks/assembled-documentation.md
index 171314350..3f26c9ccb 100644
--- a/docs/building-blocks/assembled-documentation.md
+++ b/docs/building-blocks/assembled-documentation.md
@@ -19,7 +19,7 @@ The assembler:
 
 Assembled documentation is configured through the site configuration, which defines:
 
-* [assembler.yml](../configure/site/index.md): Which repositories to include and [their branching strategy](../contribute/branching-strategy.md).
+* [assembler.yml](../configure/site/index.md): Which repositories to include and [their branching strategy](../how-to/branching-strategy.md).
 * [navigation.yml](../configure/site/index.md): Navigation and url prefixes for TOC's.
 * [versions.yml](../configure/site/versions.md): Defines the various versioning schemes of products/solutions being documented.
 * [products.yml](../configure/site/products.md): Defines the product catalog (id, name) and ties it to a specific versioning scheme.
diff --git a/docs/building-blocks/index.md b/docs/building-blocks/index.md
index 087ffc58f..2a65397a4 100644
--- a/docs/building-blocks/index.md
+++ b/docs/building-blocks/index.md
@@ -1,8 +1,8 @@
 ---
-navigation_title: Building blocks
+navigation_title: Core architecture concepts
 ---
 
-# Building blocks
+# Core architecture concepts and building blocks
 
 This section explains the core concepts and building blocks that make up the docs-builder architecture. Understanding these concepts will help you work effectively with distributed documentation and cross-repository linking.
 
diff --git a/docs/cli/docset/diff-validate.md b/docs/cli/docset/diff-validate.md
index 59513c5f9..94b9447ed 100644
--- a/docs/cli/docset/diff-validate.md
+++ b/docs/cli/docset/diff-validate.md
@@ -4,7 +4,7 @@ Gathers the local changes by inspecting the git log, stashed and unstashed chang
 
 It currently validates the following:
 
-* Ensures that renames and deletions are reflected in [redirects.yml](../../contribute/redirects.md).
+* Ensures that renames and deletions are reflected in [redirects.yml](../../how-to/redirects.md).
 
 ## Usage
 
diff --git a/docs/cli/docset/index.md b/docs/cli/docset/index.md
index d3e794c05..e75258a51 100644
--- a/docs/cli/docset/index.md
+++ b/docs/cli/docset/index.md
@@ -22,5 +22,5 @@ locate the `docset.yml` anywhere in the directory tree automatically and build t
 ## Refactor commands
 
 - [mv](mv.md) - move a file or folder to a new location. This will rewrite all links in all files too.
-- [diff validate](diff-validate.md) - validate that local changes are reflected in [redirects.yml](../../contribute/redirects.md)
+- [diff validate](diff-validate.md) - validate that local changes are reflected in [redirects.yml](../../how-to/redirects.md)
 
diff --git a/docs/configure/site/index.md b/docs/configure/site/index.md
index f4d783f3a..6882d7867 100644
--- a/docs/configure/site/index.md
+++ b/docs/configure/site/index.md
@@ -14,7 +14,7 @@ Configure the documentation site in these files:
 
 ## Redirects
 
-Redirects are also configured at the site-level. See [](../../contribute/redirects.md) for more information.
+Redirects are also configured at the site-level. See [](../../how-to/redirects.md) for more information.
 
 ## Synonyms
 
diff --git a/docs/contribute/_snippets/tagged-warning.md b/docs/contribute/_snippets/tagged-warning.md
index e189ed229..6b7a0d3b1 100644
--- a/docs/contribute/_snippets/tagged-warning.md
+++ b/docs/contribute/_snippets/tagged-warning.md
@@ -1,7 +1,7 @@
 :::{warning}
-Some repositories use a [tagged branching strategy](/contribute/branching-strategy.md), which means that their docs are published from a branch that is not `main` or `master`. In these cases, documentation changes need to be made to `main` or `master`, and then backported to the relevant branches.
+Some repositories use a [tagged branching strategy](/how-to/branching-strategy.md), which means that their docs are published from a branch that is not `main` or `master`. In these cases, documentation changes need to be made to `main` or `master`, and then backported to the relevant branches.
 
-For detailed backporting guidance, refer to the example in [Choose the docs branching strategy for a repository](/contribute/branching-strategy.md#workflow-2-tagged).
+For detailed backporting guidance, refer to the example in [Choose the docs branching strategy for a repository](/how-to/branching-strategy.md#workflow-2-tagged).
 
 To determine the published branches for a repository, find the repository in [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml).
 :::
diff --git a/docs/contribute/index.md b/docs/contribute/index.md
index 198f3684e..4992f5a31 100644
--- a/docs/contribute/index.md
+++ b/docs/contribute/index.md
@@ -1,4 +1,5 @@
-# Elastic Docs contribution guide
+
+# Contribute to docs
 
 :::{note}
 👋 This page has moved to [elastic.co/docs](https://www.elastic.co/docs/contribute-docs/).
diff --git a/docs/contribute/add-repo.md b/docs/how-to/add-repo.md
similarity index 93%
rename from docs/contribute/add-repo.md
rename to docs/how-to/add-repo.md
index 2290ef0db..a09ee7780 100644
--- a/docs/contribute/add-repo.md
+++ b/docs/how-to/add-repo.md
@@ -1,3 +1,7 @@
+---
+navigation_title: "Add a new repo to the docs"
+---
+
 # Add a new repository to the docs
 
 Elastic documentation is built from many assembled repositories using `docs-builder assemble`. Adding a new repository requires making the assembly process aware of its existence.
@@ -55,7 +59,7 @@ references:
 ```
 
 :::{tip}
-In this file, you can optionally specify custom branches to deploy docs from, depending on your preferred [branching strategy](/contribute/branching-strategy.md). You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
+In this file, you can optionally specify custom branches to deploy docs from, depending on your preferred [branching strategy](/how-to/branching-strategy.md). You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
 :::
 
 Then, edit the [`navigation.yml`](https://github.com/elastic/docs-builder/blob/main/config/navigation.yml) file to add the repository to the navigation. Refer to [navigation.yml](../configure/site/navigation.md) for more information.
diff --git a/docs/contribute/branching-strategy.md b/docs/how-to/branching-strategy.md
similarity index 99%
rename from docs/contribute/branching-strategy.md
rename to docs/how-to/branching-strategy.md
index dfddcb47d..8677aadb4 100644
--- a/docs/contribute/branching-strategy.md
+++ b/docs/how-to/branching-strategy.md
@@ -1,5 +1,5 @@
 ---
-navigation_title: Choose a branching strategy
+navigation_title: Choose a repo branch strategy
 ---
 
 # Choose the docs branching strategy for a repository
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
new file mode 100644
index 000000000..0386949cd
--- /dev/null
+++ b/docs/how-to/index.md
@@ -0,0 +1,21 @@
+# How-to guides
+
+:::{tip}
+Looking for contribution guides on how to write the docs? Refer to [Contribute to docs](https://www.elastic.co/docs/contribute-docs/) on the main Elastic documentation site.
+:::
+
+Use these guides for tasks like managing documentation files and folders, configuring repositories, and handling releases.
+
+## Manage files and links
+
+- [Move files and folders](move.md): Move files or folders and automatically update all links in the documentation.
+- [Manage redirects across doc sets](redirects.md): Set up redirects when moving or deleting pages to prevent broken links.
+
+## Repository management
+
+- [Add a new repository to the docs](add-repo.md): Add a new docs repository to the assembly process.
+- [Choose a branching strategy](branching-strategy.md): Choose the right docs branching strategy for your repository.
+
+## Release management
+
+- [Release a new documentation version](release-new-version.md): Update the docs site when a new version of the Elastic Stack or other versioned product is released.
diff --git a/docs/contribute/move.md b/docs/how-to/move.md
similarity index 100%
rename from docs/contribute/move.md
rename to docs/how-to/move.md
diff --git a/docs/contribute/redirects.md b/docs/how-to/redirects.md
similarity index 99%
rename from docs/contribute/redirects.md
rename to docs/how-to/redirects.md
index 022e03b99..2f1a5f370 100644
--- a/docs/contribute/redirects.md
+++ b/docs/how-to/redirects.md
@@ -1,5 +1,5 @@
 ---
-navigation_title: "Redirects"
+navigation_title: "Set up redirects"
 ---
 
 # Manage redirects across doc sets
diff --git a/docs/contribute/release-new-version.md b/docs/how-to/release-new-version.md
similarity index 97%
rename from docs/contribute/release-new-version.md
rename to docs/how-to/release-new-version.md
index 56cb0496d..8b408c967 100644
--- a/docs/contribute/release-new-version.md
+++ b/docs/how-to/release-new-version.md
@@ -1,3 +1,7 @@
+---
+navigation_title: Release a new docs version
+---
+
 # Release a new documentation version
 
 When a new version of the Elastic Stack (or another versioned product) is released, the docs site must be updated to recognize it. This process primarily involves updating version metadata in the shared site configuration.
diff --git a/docs/migration/versioning.md b/docs/migration/versioning.md
index eec00093b..c14a62fa0 100644
--- a/docs/migration/versioning.md
+++ b/docs/migration/versioning.md
@@ -19,5 +19,5 @@ In this new system, documentation is written **cumulatively**. This means that a
 
 In Docs V3, a single branch is published per repository. This branch is set to `main` by default, but it is possible to instead publish a different branch by changing your repository's branching strategy. You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
 
-* [Learn how to choose the right branching strategy for your repository](/contribute/branching-strategy.md)
+* [Learn how to choose the right branching strategy for your repository](/how-to/branching-strategy.md)
 * [Learn how to set up your selected branching strategy](/configure/content-sources.md)

From ec850df2f157b071a22b39cc75a02f46298a0da0 Mon Sep 17 00:00:00 2001
From: Liam Thompson <leemthompo@gmail.com>
Date: Wed, 5 Nov 2025 18:23:38 +0100
Subject: [PATCH 2/6] empty syntax quick ref and soft redirect

---
 docs/syntax/quick-ref.md | 673 +--------------------------------------
 1 file changed, 3 insertions(+), 670 deletions(-)

diff --git a/docs/syntax/quick-ref.md b/docs/syntax/quick-ref.md
index e7cbf5332..1d619cf35 100644
--- a/docs/syntax/quick-ref.md
+++ b/docs/syntax/quick-ref.md
@@ -2,675 +2,8 @@
 navigation_title: "Quick reference"
 ---
 
-<!-- TODO docs writers: A version of this quick reference also exists at elastic.co/docs. Try to keep these in sync!! -->
-
 # Syntax quick reference
 
-This page offers quick guidance on Elastic Docs v3 syntax, including usage tips. Elements are in alphabetical order. The [full syntax guide](index.md) provides implementation details.
-
-## Admonitions
-
-Use admonitions to caution users, or to provide helpful tips or extra information.
-
-::::{dropdown} Types
-
-These examples show the syntax first, followed by the rendered admonition.
-
- **Warning**
-
-  ```markdown
-      :::{warning}
-      Users could permanently lose data or leak sensitive information.
-      :::
-  ```
-  :::{warning}
-  Users could permanently lose data or leak sensitive information.
-  :::
-
-  **Important**
-
-  ```markdown
-      :::{important}
-      Less dire than a warning. Users might encounter issues with performance or stability.
-      :::
-  ```
-  :::{important}
-  Less dire than a warning. Users might encounter issues with performance or stability.
-  :::
-
-  **Note**
-  ```markdown
-      :::{note}
-      Supplemental information that provides context or clarification.
-      :::
-  ```
-  :::{note}
-  Supplemental information that provides context or clarification.
-  :::
-
-  **Tip**
-  ```markdown
-      :::{tip}
-      Advice that helps users work more efficiently or make better choices.
-      :::
-  ```
-  :::{tip}
-  Advice that helps users work more efficiently or make better choices.
-  :::
-
-  **Custom**
-  ```markdown
-      :::{admonition} Special note
-      Custom admonition with custom label.
-      :::
-  ```
-  :::{admonition} Special note
-  Custom admonition with custom label.
-  :::
-
-::::
-
-**DOs**<br>
-✅ **Do:** Use custom admonitions as needed
-
-**DON'Ts**<br>
-❌ **Don't:** Stack admonitions<br>
-❌ **Don't:** Overload a page with too many admonitions
-
-[More details: Admonitions →](admonitions.md)
-<br>
-<br>
-
----
-
-## Anchors
-
-A default anchor is automatically created for each [heading](#headings), in the form `#heading-text` (hyphenated, lowercase, special characters and spaces trimmed). To create a custom anchor, add it in square brackets at the end of a heading: `[my-better-anchor]`
-
-:::{dropdown} Default anchor
-```markdown
-#### Hello world!
-<!-- Auto-generated default anchor: #hello-world -->
-```
-:::
-
-
-:::{dropdown} Custom anchor
-```markdown
-#### Hello world! [get-started]
-```
-:::
-
-**DOs**<br>
-✅ **Do:** Create custom anchors for repeated structural headings like "Example request"<br>
-
-**DON'Ts**<br>
-❌ **Don't:** Include punctuation marks in custom anchors<br>
-❌ **Don't:** Define custom anchors in text that is not a heading
-
-[More details: Links →](links.md#same-page-links-anchors)
-<br>
-<br>
-
----
-
-## 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](https://www.elastic.co/docs/contribute-docs/how-to/cumulative-docs/example-scenarios) in Elastic Docs v3.
-
-**Example: Section tag**
-
-:::{dropdown} Syntax
-````markdown
-# Stack-only content
-```{applies_to}
-stack:
-```
-````
-:::
-
-:::{dropdown} Output
-#### Stack-only content
-```{applies_to}
-stack:
-```
-:::
-
-For full syntax and more examples, see [](applies.md).
-
-<!--
-:::{tip}
-The `applies_to` tags are scope signals for readers, not comprehensive metadata. If a page contains general information that applies to all contexts, it doesn't need tags.
-:::
--->
-
-% TODO restore details when guidance has settled
-
-**DOs**<br>
-✅ **Do:** Define a set of [page-level tags](applies.md#page-level) in a front matter block<br>
-✅ **Do:** Add section-level tags in an `{applies_to}` [directive](applies.md#section-level) after a heading<br>
-✅ **Do:** Indicate versions (`major.minor` with an optional `[.patch]`) and release phases like `beta`
-
-**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>
-
----
-
-## Code blocks
-
-Multi-line blocks for code, commands, configuration, and similar content. Use three backticks ` ``` ` on separate lines to start and end the block. For syntax highlighting, add a language identifier after the opening backticks.
-
-:::{dropdown} Syntax
-```markdown
-    ```yaml
-    server.host: "0.0.0.0"
-    elasticsearch.hosts: ["http://localhost:9200"]
-    ```
-```
-:::
-
-:::{dropdown} Output
-```yaml
-server.host: "0.0.0.0"
-elasticsearch.hosts: ["http://localhost:9200"]
-```
-:::
-
-
-**DOs**<br>
-✅ **Do:** Include code blocks within lists or other block elements as needed<br>
-✅ **Do:** Add language identifiers like `yaml`, `json`, `bash`
-
-**DON'Ts**<br>
-❌ **Don't:** Place code blocks in admonitions<br>
-❌ **Don't:** Use inline code formatting (single backticks) for multi-line content
-
-[More details: Code →](code.md)
-<br>
-<br>
-
----
-
-## Code callouts
-
-Inline annotations that highlight or explain specific lines in a code block.
-
-### Explicit callout
-To explicitly create a code callout, add a number marker in angle brackets (`<1>`, `<2>`, ...) at the end of a line. Add the corresponding callout text below the code block, in a numbered list that matches the markers.
-
-:::{dropdown} Syntax
-
-  ````markdown callouts=false
-      ```json
-      {
-        "match": {
-          "message": "search text" <1>
-        }
-      }
-      ```
-      1. Searches the `message` field for the phrase "search text"
-  ````
-:::
-
-:::{dropdown} Output
-
-```json
-{
-  "match": {
-    "message": "search text" <1>
-  }
-}
-```
-1. Searches the `message` field for the phrase "search text"<br>
-:::
-
-### Magic (comment-based) callout [magic-callout]
-Add comments with `//` or `#` to magically create callouts.
-
-:::{dropdown} Syntax
-  ````markdown callouts=false
-    ```json
-    {
-      "match": {
-        "message": "search text" // Searches the message field
-      }
-    }
-    ```
-  ````
-:::
-
-:::{dropdown} Output
-
-```json
-{
-  "match": {
-    "message": "search text" // Searches the message field
-  }
-}
-```
-:::
-
-**DOs**<br>
-✅ **Do:** Keep callout text short and specific<br>
-✅ **Do:** Use only one type of callout per code block (don't mix [explicit](#explicit-callout) and [magic](#magic-callout))<br>
-✅ **Do:** Make sure there's a corresponding list item for each explicit callout marker in a code block
-
-**DON'Ts**<br>
-❌ **Don't:** Overuse callouts &mdash; they can impede readability
-
-[More details: Code callouts→](code.md#code-callouts)
-<br>
-<br>
-
----
-
-## Comments
-
-Use `%` to add single-line comments. Use HTML-style `<!--` and `-->` for multi-line comments.
-
-:::{dropdown} Syntax
-```markdown
-    % This is a comment
-    This is regular text
-
-    <!--
-    so much depends
-    upon
-    a multi-line
-    comment
-    -->
-    Regular text after multi-line comment
-```
-:::
-
-:::{dropdown} Output
-% This is a comment
-This is regular text
-
-<!--
-so much depends
-upon
-a multi-line
-comment
--->
-Regular text after multi-line comment
-
-:::
-
-**DOs**<br>
-✅ **Do:** Add a space after the `%` in single-line comments
-
-**DON'Ts**<br>
-❌ **Don't:** Use `#` or `//` for comments (reserved for [magic callouts](#magic-callout))
-<br>
-<br>
-
----
-
-## Dropdowns
-
-Collapsible blocks for hiding and showing content.
-
-::::{dropdown} Syntax
-```markdown
-    :::{dropdown} Title or label
-    Collapsible content
-    :::
-```
-::::
-
-::::{dropdown} Output
-:::{dropdown} Title or label
-Collapsible content
-:::
-::::
-
-**DOs**<br>
-✅ **Do:** Use dropdowns for text, lists, images, code blocks, and tables<br>
-✅ **Do:** Add `:open:` to auto-expand a dropdown by default
-
-**DON'Ts**<br>
-❌ **Don't:** Use dropdowns for very long paragraphs or entire sections
-
-[More details: Dropdowns →](dropdowns.md)
-<br>
-<br>
-
----
-
-## Headings
-Title of a page or a section. To create a heading, add number signs `#` at the beginning of the line (one `#` for each heading level).
-
-:::{dropdown} Syntax
-```markdown
-# Heading 1
-## Heading 2
-### Heading 3
-#### Heading 4
-```
-:::
-
-::::{dropdown} Output
-:::{image} images/headings.png
-:screenshot:
-:alt: Heading levels
-:width: 300px
-:::
-
-::::
-
-**DOs**<br>
-✅ **Do:** Start every page with a Heading 1<br>
-✅ **Do:** Use only one Heading 1 per page<br>
-✅ **Do:** Define custom anchors for repeated headings
-
-**DON'Ts**<br>
-❌ **Don't:** Use headings in tabs or dropdowns<br>
-❌ **Don't:** Go deeper than Heading 4
-
-[More details: Headings →](headings.md)
-<br>
-<br>
-
----
-
-## Images
-Standard Markdown images: `[alt text]` in square brackets, followed by the image path in parentheses.
-
-:::{dropdown} Syntax
-```markdown
-![Bear emerging from hibernation](images/bear.png)
-```
-:::
-
-:::{dropdown} Output
-![Bear emerging from hibernation](images/bear.png)
-:::
-
-**DOs**<br>
-✅ **Do:** Store images in a centralized directory<br>
-✅ **Do:** Follow v3 [best practices for screenshots](https://www.elastic.co/docs/contribute-docs/how-to/cumulative-docs/badge-placement#images)<br>
-✅ **Do:** Specify `:screenshot:` in an [image directive](images.md#screenshots) to add a border
-
-**DON'Ts**<br>
-❌ **Don't:** Use lots of UI screenshots that create a maintenance burden<br>
-❌ **Don't:** Include confidential info or PII in an image<br>
-❌ **Don't:** Add a drop shadow or torn edge effect
-
-[More details: Images →](images.md)
-<br>
-<br>
-
----
-
-
-## Inline formatting
-Elastic Docs v3 supports standard Markdown inline formatting.
-
-`_emphasis_` &nbsp;&nbsp;&nbsp; _italics_ <br>
-`**strong**` &nbsp;&nbsp;&nbsp;**bold**  <br>
-\` `monospace` \` &nbsp;&nbsp;&nbsp; `inline code` (single backticks) <br>
-`~~strikethrough~~` &nbsp;&nbsp;&nbsp; ~~strikethrough~~ <br>
-`\* escaped` &nbsp;&nbsp;&nbsp; \* escaped character
-
-**DOs**<br>
-✅ **Do:** Use `_emphasis_` to introduce a term<br>
-✅ **Do:** Use inline `code` in headings and other elements as needed
-
-**DON'Ts**<br>
-❌ **Don't:** Overuse `**strong**` or `_emphasis_` &mdash; aim for readability
-<br>
-<br>
-
----
-
-## Links
-
-Standard Markdown links to doc pages, sections (anchors), or external content. Prefer absolute paths for links within the doc set.
-
-:::{dropdown} Syntax
-```markdown
-    [link text](/absolute/file.md#anchor)
-    [link text](https://external-site.com)
-    [link text](other-repo://path/file.md)
-    (#same-page-anchor)
-```
-:::
-
-**DOs**<br>
-✅ **Do:** Use inline formatting in link text: `[**bold link**](bold-page.md)`<br>
-✅ **Do:** Autogenerate link text from the page or section title: `[](use-title.md#section)`<br>
-✅ **Do:** Define a custom [anchor](#anchors) by adding `[anchor-text]` at the end of a heading line
-
-**DON'Ts**<br>
-❌ **Don't:** Use unclear, inaccessible link text like "click here" or "this"<br>
-❌ **Don't:** Include terminal punctuation in link text
-
-[More details: Links →](links.md)
-<br>
-<br>
-
----
-
-## Lists
-
-Standard Markdown ordered (numbered) and unordered (bulleted) lists. Indent with four spaces to nest paragraphs and other elements under a list item. Unordered lists can start with hyphens `-`, asterisks `*`, or plus signs `+`.
-
-:::{dropdown} Syntax
-
-  ```
-      - Unordered item 1
-      ····Paragraph within item 1
-      - Unordered item 2
-  ```
-
-  ```
-  1. Ordered item 1
-  2. Ordered item 2
-  ```
-:::
-
-**DOs** <br>
-✅ **Do:** Add code blocks, images, admonitions, and other content within a list item<br>
-✅ **Do:** Nest lists, mixing ordered and unordered as needed<br>
-✅ **Do:** Use parallel structure and phrasing in list items<br>
-✅ **Do:** Capitalize only the first word of list items (sentence case)<br>
-✅ **Do:** Use terminal punctuation consistently and only for complete sentences
-
-**DON'Ts** <br>
-❌ **Don't:** Use lists solely for layout purposes <br>
-❌ **Don't:** Use lists for structured data or comparisons — use tables instead
-
-[More details: Lists →](lists.md)
-<br>
-<br>
-
----
-
-## Navigation title
-
-Optional [front matter](frontmatter.md) element that sets a custom title for docs navigation features: appears in the left nav (table of contents), breadcrumbs, and previous/next links. Compare [headings](#headings) (H1 = page title).
-
-:::{dropdown} Syntax
-
-Page front matter (yaml):
-
-```yaml
-  ---
-    navigation_title: "Minimalist identifier"
-  ---
-```
-
-Page title (Markdown H1):
-
-```markdown
-    # Full descriptive page title with product context
-```
-
-:::
-
-:::{dropdown} Output
-
-![Rendered nav title](images/nav-title.png)
-
-:::
-
-
-**DOs**<br>
-✅ **Do:** Use active phrasing and shorter forms<br>
-✅ **Do:** Make sure the navigation title clearly identifies the page topic<br>
-✅ **Do:** Omit product names that appear in the full H1 page title
-
-**DON'Ts**<br>
-❌ **Don't:** Duplicate the H1 page title<br>
-❌ **Don't:** Use a long navigation title or lots of punctuation<br>
-❌ **Don't:** Abbreviate with periods or ellipses
-
-[More details: Title →](./titles.md)
-<br>
-<br>
-
----
-
-## Substitutions
-Key-value pairs that define reusable variables. They help ensure consistency and enable short forms. To use a substitution (or "sub"), surround the key with curly brackets: `{{variable}}`<br>
-
-% TODO: link to our global docset.yml?
-
-### Define a sub
-
-:::{dropdown} Syntax
-
-In `docset.yml`:
-
-```
-subs:
-  ccs: "cross-cluster search"
-  ech: "Elastic Cloud Hosted"
-  kib: "Kibana"
-```
-:::
-
-
-### Use a sub
-
-This example uses the sub defined in `docset.yml` above.
-
-:::{dropdown} Syntax
-
-In `myfile.md`:
-
-```
-{{ech}} supports most standard {{kib}} settings.
-```
-:::
-
-:::{dropdown} Output
-% TODO replace with actual subs once _docset.yml is updated
-
-Elastic Cloud Hosted supports most standard Kibana settings.
-:::
-
-**DOs** <br>
-✅ **Do:** Check the global `docset.yml` file for existing product and feature name subs<br>
-✅ **Do:** Use substitutions in code blocks by setting `subs=true`  <br>
-✅ **Do:** Define new page-specific substitutions as needed
-
-**DON'Ts**<br>
-❌ **Don't:** Override a `docset.yml` sub by defining a page-level sub with the same key (causes build errors)<br>
-❌ **Don't:** Use substitutions for common words that don't need to be standardized
-
-[More details: Substitutions →](./substitutions.md)
-<br>
-<br>
-
----
-
-## Tabs
-
-Block element that displays content in switchable tabs to help users zero in on the right context (such as a deployment or language). [Synced tab groups](/syntax/tabs.md#tab-groups) are supported.
-
-:::::{dropdown} Syntax
-```markdown
-    ::::{tab-set}
-
-    :::{tab-item} Tab 1 title
-    Tab 1 content
-    :::
-
-    :::{tab-item} Tab 2 title
-    Tab 2 content
-    :::
-
-    ::::
-```
-:::::
-
-:::::{dropdown} Output
-::::{tab-set}
-
-:::{tab-item} Tab 1 title
-Tab 1 content
-:::
-
-:::{tab-item} Tab 2 title
-Tab 2 content
-:::
-
-::::
-:::::
-
-**DOs**<br>
-✅ **Do:** Use clear, descriptive tab labels<br>
-✅ **Do:** Make sure all tabs have the same type of content and similar goals<br>
-✅ **Do:** Keep tab content scannable and self-contained (don't make users switch tabs to follow steps or compare content)<br>
-✅ **Do:** Include other block elements in tabs, like [admonitions](#admonitions)
-
-**DON'Ts**<br>
-❌ **Don't:** Nest tabs<br>
-❌ **Don't:** Split step-by-step procedures across tabs<br>
-❌ **Don't:** Use more than 6 tabs (use as few as possible)<br>
-❌ **Don't:** Use tabs in [dropdowns](#dropdowns)
-
-
-[More details: Tabs →](tabs.md)
-<br>
-<br>
-
----
-
-## Tables
-
-Standard table layout for structured data. Automatically scrolls horizontally if needed. The **header** row is optional.
-
-:::{dropdown} Syntax
-```markdown
-    | Header | Header |
-    | ------ | ------ |
-    | Data   | Info   |
-    | Info	 | Data   |
-```
-:::
-
-:::{dropdown} Output
-| Header | Header |
-| ------ | ------ |
-| Data   | Info   |
-| Info	 | Data   |
-:::
-
-**DOs**<br>
-✅ **Do:** Use leading and trailing pipes for clarity<br>
-✅ **Do:** Add spaces for readability (they're trimmed)<br>
-✅ **Do:** Keep cell content scannable and parallel<br>
-✅ **Do:** Use standard Markdown text alignment when necessary (`:-- --: :--:`)
-
-**DON'Ts**<br>
-❌ **Don't:** Insert block elements or multiple paragraphs in a table cell<br>
-❌ **Don't:** Use a table solely for position or spacing purposes
-
-[More details: Tables →](tables.md)
+:::{note}
+👋 This page has moved to the main Elastic docs: [Syntax quick reference](https://www.elastic.co/docs/contribute-docs/syntax-quick-reference)
+:::
\ No newline at end of file

From 234149e6c7dd7561d7edd1f9494b4c25749f7fc5 Mon Sep 17 00:00:00 2001
From: Liam Thompson <leemthompo@gmail.com>
Date: Thu, 6 Nov 2025 09:44:14 +0100
Subject: [PATCH 3/6] move redirects

---
 docs/_redirects.yml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/_redirects.yml b/docs/_redirects.yml
index a07c19886..b6aa11db0 100644
--- a/docs/_redirects.yml
+++ b/docs/_redirects.yml
@@ -1,4 +1,9 @@
 redirects:
+  'contribute/move.md': 'how-to/move.md'
+  'contribute/redirects.md': 'how-to/redirects.md'
+  'contribute/branching-strategy.md': 'how-to/branching-strategy.md'
+  'contribute/add-repo.md': 'how-to/add-repo.md'
+  'contribute/release-new-version.md': 'how-to/release-new-version.md'
   'migration/freeze/gh-action.md' : 'index.md'
   'migration/freeze/index.md' : 'index.md'
   'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
@@ -23,9 +28,4 @@ redirects:
           "yy": "bb"
   'testing/redirects/third-page.md':
     anchors:
-      'removed-anchor':
-  'contribute/move.md': 'how-to/move.md'
-  'contribute/redirects.md': 'how-to/redirects.md'
-  'contribute/branching-strategy.md': 'how-to/branching-strategy.md'
-  'contribute/add-repo.md': 'how-to/add-repo.md'
-  'contribute/release-new-version.md': 'how-to/release-new-version.md'
+      'removed-anchor':
\ No newline at end of file

From cbacb4c01743da059007619c6f0210a09209bf1d Mon Sep 17 00:00:00 2001
From: Liam Thompson <leemthompo@gmail.com>
Date: Thu, 6 Nov 2025 10:08:10 +0100
Subject: [PATCH 4/6] just redirect mved files to root

---
 docs/_redirects.yml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/_redirects.yml b/docs/_redirects.yml
index b6aa11db0..cf1940499 100644
--- a/docs/_redirects.yml
+++ b/docs/_redirects.yml
@@ -1,9 +1,9 @@
 redirects:
-  'contribute/move.md': 'how-to/move.md'
-  'contribute/redirects.md': 'how-to/redirects.md'
-  'contribute/branching-strategy.md': 'how-to/branching-strategy.md'
-  'contribute/add-repo.md': 'how-to/add-repo.md'
-  'contribute/release-new-version.md': 'how-to/release-new-version.md'
+  'contribute/move.md': 'index.md'
+  'contribute/redirects.md': 'index.md'
+  'contribute/branching-strategy.md': 'index.md'
+  'contribute/add-repo.md': 'index.md'
+  'contribute/release-new-version.md': 'index.md'
   'migration/freeze/gh-action.md' : 'index.md'
   'migration/freeze/index.md' : 'index.md'
   'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'

From 942577bbd0cde00f5ca3d791cb0a4123de173641 Mon Sep 17 00:00:00 2001
From: Liam Thompson <leemthompo@gmail.com>
Date: Thu, 6 Nov 2025 10:35:15 +0100
Subject: [PATCH 5/6] restore how-to guides into contribute folder, update
 navigation and all internal links, remove problematic redirects.

---
 docs/_docset.yml                              | 19 +++++++--------
 docs/_redirects.yml                           |  5 ----
 .../assembled-documentation.md                |  2 +-
 docs/cli/docset/diff-validate.md              |  2 +-
 docs/cli/docset/index.md                      |  2 +-
 docs/configure/site/index.md                  |  2 +-
 docs/contribute/_snippets/tagged-warning.md   |  4 ++--
 docs/{how-to => contribute}/add-repo.md       |  2 +-
 .../branching-strategy.md                     |  0
 docs/contribute/index.md                      | 23 +++++++++++++++----
 docs/{how-to => contribute}/move.md           |  0
 docs/{how-to => contribute}/redirects.md      |  0
 .../release-new-version.md                    |  0
 docs/how-to/index.md                          | 21 -----------------
 docs/index.md                                 |  6 ++---
 docs/migration/versioning.md                  |  2 +-
 16 files changed, 40 insertions(+), 50 deletions(-)
 rename docs/{how-to => contribute}/add-repo.md (93%)
 rename docs/{how-to => contribute}/branching-strategy.md (100%)
 rename docs/{how-to => contribute}/move.md (100%)
 rename docs/{how-to => contribute}/redirects.md (100%)
 rename docs/{how-to => contribute}/release-new-version.md (100%)
 delete mode 100644 docs/how-to/index.md

diff --git a/docs/_docset.yml b/docs/_docset.yml
index 0a79609c2..e30354365 100644
--- a/docs/_docset.yml
+++ b/docs/_docset.yml
@@ -29,15 +29,7 @@ toc:
   - file: index.md
   - hidden: 404.md
   - hidden: developer-notes.md
-  - hidden: contribute/index.md
-  - hidden: contribute/locally.md
-  - hidden: contribute/on-the-web.md
-  - hidden: contribute/cumulative-docs/index.md
-  - hidden: contribute/cumulative-docs/guidelines.md
-  - hidden: contribute/cumulative-docs/badge-placement.md
-  - hidden: contribute/cumulative-docs/example-scenarios.md
-  - hidden: contribute/cumulative-docs/reference.md
-  - folder: how-to
+  - folder: contribute
     children:
       - file: index.md
       - file: move.md
@@ -45,6 +37,15 @@ toc:
       - file: branching-strategy.md
       - file: add-repo.md
       - file: release-new-version.md
+      - hidden: locally.md
+      - hidden: on-the-web.md
+      - folder: cumulative-docs
+        children:
+          - hidden: index.md
+          - hidden: guidelines.md
+          - hidden: badge-placement.md
+          - hidden: example-scenarios.md
+          - hidden: reference.md
   - folder: building-blocks
     children:
       - file: index.md
diff --git a/docs/_redirects.yml b/docs/_redirects.yml
index cf1940499..424ba69a5 100644
--- a/docs/_redirects.yml
+++ b/docs/_redirects.yml
@@ -1,9 +1,4 @@
 redirects:
-  'contribute/move.md': 'index.md'
-  'contribute/redirects.md': 'index.md'
-  'contribute/branching-strategy.md': 'index.md'
-  'contribute/add-repo.md': 'index.md'
-  'contribute/release-new-version.md': 'index.md'
   'migration/freeze/gh-action.md' : 'index.md'
   'migration/freeze/index.md' : 'index.md'
   'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
diff --git a/docs/building-blocks/assembled-documentation.md b/docs/building-blocks/assembled-documentation.md
index 3f26c9ccb..171314350 100644
--- a/docs/building-blocks/assembled-documentation.md
+++ b/docs/building-blocks/assembled-documentation.md
@@ -19,7 +19,7 @@ The assembler:
 
 Assembled documentation is configured through the site configuration, which defines:
 
-* [assembler.yml](../configure/site/index.md): Which repositories to include and [their branching strategy](../how-to/branching-strategy.md).
+* [assembler.yml](../configure/site/index.md): Which repositories to include and [their branching strategy](../contribute/branching-strategy.md).
 * [navigation.yml](../configure/site/index.md): Navigation and url prefixes for TOC's.
 * [versions.yml](../configure/site/versions.md): Defines the various versioning schemes of products/solutions being documented.
 * [products.yml](../configure/site/products.md): Defines the product catalog (id, name) and ties it to a specific versioning scheme.
diff --git a/docs/cli/docset/diff-validate.md b/docs/cli/docset/diff-validate.md
index 94b9447ed..59513c5f9 100644
--- a/docs/cli/docset/diff-validate.md
+++ b/docs/cli/docset/diff-validate.md
@@ -4,7 +4,7 @@ Gathers the local changes by inspecting the git log, stashed and unstashed chang
 
 It currently validates the following:
 
-* Ensures that renames and deletions are reflected in [redirects.yml](../../how-to/redirects.md).
+* Ensures that renames and deletions are reflected in [redirects.yml](../../contribute/redirects.md).
 
 ## Usage
 
diff --git a/docs/cli/docset/index.md b/docs/cli/docset/index.md
index e75258a51..d3e794c05 100644
--- a/docs/cli/docset/index.md
+++ b/docs/cli/docset/index.md
@@ -22,5 +22,5 @@ locate the `docset.yml` anywhere in the directory tree automatically and build t
 ## Refactor commands
 
 - [mv](mv.md) - move a file or folder to a new location. This will rewrite all links in all files too.
-- [diff validate](diff-validate.md) - validate that local changes are reflected in [redirects.yml](../../how-to/redirects.md)
+- [diff validate](diff-validate.md) - validate that local changes are reflected in [redirects.yml](../../contribute/redirects.md)
 
diff --git a/docs/configure/site/index.md b/docs/configure/site/index.md
index 6882d7867..f4d783f3a 100644
--- a/docs/configure/site/index.md
+++ b/docs/configure/site/index.md
@@ -14,7 +14,7 @@ Configure the documentation site in these files:
 
 ## Redirects
 
-Redirects are also configured at the site-level. See [](../../how-to/redirects.md) for more information.
+Redirects are also configured at the site-level. See [](../../contribute/redirects.md) for more information.
 
 ## Synonyms
 
diff --git a/docs/contribute/_snippets/tagged-warning.md b/docs/contribute/_snippets/tagged-warning.md
index 6b7a0d3b1..e189ed229 100644
--- a/docs/contribute/_snippets/tagged-warning.md
+++ b/docs/contribute/_snippets/tagged-warning.md
@@ -1,7 +1,7 @@
 :::{warning}
-Some repositories use a [tagged branching strategy](/how-to/branching-strategy.md), which means that their docs are published from a branch that is not `main` or `master`. In these cases, documentation changes need to be made to `main` or `master`, and then backported to the relevant branches.
+Some repositories use a [tagged branching strategy](/contribute/branching-strategy.md), which means that their docs are published from a branch that is not `main` or `master`. In these cases, documentation changes need to be made to `main` or `master`, and then backported to the relevant branches.
 
-For detailed backporting guidance, refer to the example in [Choose the docs branching strategy for a repository](/how-to/branching-strategy.md#workflow-2-tagged).
+For detailed backporting guidance, refer to the example in [Choose the docs branching strategy for a repository](/contribute/branching-strategy.md#workflow-2-tagged).
 
 To determine the published branches for a repository, find the repository in [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml).
 :::
diff --git a/docs/how-to/add-repo.md b/docs/contribute/add-repo.md
similarity index 93%
rename from docs/how-to/add-repo.md
rename to docs/contribute/add-repo.md
index a09ee7780..d1798ae30 100644
--- a/docs/how-to/add-repo.md
+++ b/docs/contribute/add-repo.md
@@ -59,7 +59,7 @@ references:
 ```
 
 :::{tip}
-In this file, you can optionally specify custom branches to deploy docs from, depending on your preferred [branching strategy](/how-to/branching-strategy.md). You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
+In this file, you can optionally specify custom branches to deploy docs from, depending on your preferred [branching strategy](branching-strategy.md). You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
 :::
 
 Then, edit the [`navigation.yml`](https://github.com/elastic/docs-builder/blob/main/config/navigation.yml) file to add the repository to the navigation. Refer to [navigation.yml](../configure/site/navigation.md) for more information.
diff --git a/docs/how-to/branching-strategy.md b/docs/contribute/branching-strategy.md
similarity index 100%
rename from docs/how-to/branching-strategy.md
rename to docs/contribute/branching-strategy.md
diff --git a/docs/contribute/index.md b/docs/contribute/index.md
index 4992f5a31..0386949cd 100644
--- a/docs/contribute/index.md
+++ b/docs/contribute/index.md
@@ -1,6 +1,21 @@
+# How-to guides
 
-# Contribute to docs
-
-:::{note}
-👋 This page has moved to [elastic.co/docs](https://www.elastic.co/docs/contribute-docs/).
+:::{tip}
+Looking for contribution guides on how to write the docs? Refer to [Contribute to docs](https://www.elastic.co/docs/contribute-docs/) on the main Elastic documentation site.
 :::
+
+Use these guides for tasks like managing documentation files and folders, configuring repositories, and handling releases.
+
+## Manage files and links
+
+- [Move files and folders](move.md): Move files or folders and automatically update all links in the documentation.
+- [Manage redirects across doc sets](redirects.md): Set up redirects when moving or deleting pages to prevent broken links.
+
+## Repository management
+
+- [Add a new repository to the docs](add-repo.md): Add a new docs repository to the assembly process.
+- [Choose a branching strategy](branching-strategy.md): Choose the right docs branching strategy for your repository.
+
+## Release management
+
+- [Release a new documentation version](release-new-version.md): Update the docs site when a new version of the Elastic Stack or other versioned product is released.
diff --git a/docs/how-to/move.md b/docs/contribute/move.md
similarity index 100%
rename from docs/how-to/move.md
rename to docs/contribute/move.md
diff --git a/docs/how-to/redirects.md b/docs/contribute/redirects.md
similarity index 100%
rename from docs/how-to/redirects.md
rename to docs/contribute/redirects.md
diff --git a/docs/how-to/release-new-version.md b/docs/contribute/release-new-version.md
similarity index 100%
rename from docs/how-to/release-new-version.md
rename to docs/contribute/release-new-version.md
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
deleted file mode 100644
index 0386949cd..000000000
--- a/docs/how-to/index.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# How-to guides
-
-:::{tip}
-Looking for contribution guides on how to write the docs? Refer to [Contribute to docs](https://www.elastic.co/docs/contribute-docs/) on the main Elastic documentation site.
-:::
-
-Use these guides for tasks like managing documentation files and folders, configuring repositories, and handling releases.
-
-## Manage files and links
-
-- [Move files and folders](move.md): Move files or folders and automatically update all links in the documentation.
-- [Manage redirects across doc sets](redirects.md): Set up redirects when moving or deleting pages to prevent broken links.
-
-## Repository management
-
-- [Add a new repository to the docs](add-repo.md): Add a new docs repository to the assembly process.
-- [Choose a branching strategy](branching-strategy.md): Choose the right docs branching strategy for your repository.
-
-## Release management
-
-- [Release a new documentation version](release-new-version.md): Update the docs site when a new version of the Elastic Stack or other versioned product is released.
diff --git a/docs/index.md b/docs/index.md
index 7e999138f..acbc29ef5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -8,8 +8,8 @@ Elastic Docs V3 is our next-generation documentation platform designed to improv
 
 ## What do you want to do today?
 
-* [Contribute to Elastic documentation](./contribute/index.md)
-* [Learn about migration to Elastic Docs V3](./migration/index.md)
-* [Configure content sets in V3](./configure/index.md)
+* [Contribute to Elastic documentation](https://www.elastic.co/docs/contribute-docs/)
 * [Learn about V3 syntax](./syntax/index.md)
+* [Configure content sets in V3](./configure/index.md)
 * [Contribute to V3 (developer guide)](./development/index.md)
+* [Learn about migration to Elastic Docs V3](./migration/index.md)
diff --git a/docs/migration/versioning.md b/docs/migration/versioning.md
index c14a62fa0..eec00093b 100644
--- a/docs/migration/versioning.md
+++ b/docs/migration/versioning.md
@@ -19,5 +19,5 @@ In this new system, documentation is written **cumulatively**. This means that a
 
 In Docs V3, a single branch is published per repository. This branch is set to `main` by default, but it is possible to instead publish a different branch by changing your repository's branching strategy. You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
 
-* [Learn how to choose the right branching strategy for your repository](/how-to/branching-strategy.md)
+* [Learn how to choose the right branching strategy for your repository](/contribute/branching-strategy.md)
 * [Learn how to set up your selected branching strategy](/configure/content-sources.md)

From cb811f99716ad698d287fd8024b47689f1befc27 Mon Sep 17 00:00:00 2001
From: Liam Thompson <leemthompo@gmail.com>
Date: Thu, 6 Nov 2025 10:37:06 +0100
Subject: [PATCH 6/6] rehide cumulative docs properly

---
 docs/_docset.yml | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/docs/_docset.yml b/docs/_docset.yml
index e30354365..d53c3cbe4 100644
--- a/docs/_docset.yml
+++ b/docs/_docset.yml
@@ -29,6 +29,11 @@ toc:
   - file: index.md
   - hidden: 404.md
   - hidden: developer-notes.md
+  - hidden: contribute/cumulative-docs/index.md
+  - hidden: contribute/cumulative-docs/guidelines.md
+  - hidden: contribute/cumulative-docs/badge-placement.md
+  - hidden: contribute/cumulative-docs/example-scenarios.md
+  - hidden: contribute/cumulative-docs/reference.md
   - folder: contribute
     children:
       - file: index.md
@@ -39,13 +44,6 @@ toc:
       - file: release-new-version.md
       - hidden: locally.md
       - hidden: on-the-web.md
-      - folder: cumulative-docs
-        children:
-          - hidden: index.md
-          - hidden: guidelines.md
-          - hidden: badge-placement.md
-          - hidden: example-scenarios.md
-          - hidden: reference.md
   - folder: building-blocks
     children:
       - file: index.md