restore how-to guides into contribute folder, update navigation and all internal links, remove problematic redirects.

leemthompo · leemthompo · commit 942577bbd0cd · 2025-11-06T10:35:15.000+01:00
diff --git a/docs/_docset.yml b/docs/_docset.yml
@@ -29,22 +29,23 @@ 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
       - file: redirects.md
       - 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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/contribute/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/contribute/branching-strategy.md b/docs/contribute/branching-strategy.md
diff --git 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/contribute/move.md b/docs/contribute/move.md
diff --git a/docs/contribute/redirects.md b/docs/contribute/redirects.md
diff --git a/docs/contribute/release-new-version.md b/docs/contribute/release-new-version.md
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
diff --git 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
@@ -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)
