Refactor Migrations and Upgrades Documentation

.github/vale/styles/Vocab/OpenSearch/Plugins/accept.txt

@@ -15,6 +15,7 @@ Index Management plugin
 Job Scheduler
 Job Scheduler plugin
 k-NN plugin
+Metadata Migration Tool
 ML Commons
 ML Commons plugin
 Neural Search plugin

.github/vale/styles/Vocab/OpenSearch/Products/accept.txt

@@ -98,6 +98,7 @@ Querqy
 Query Workbench
 RankLib
 Reindex-from-Snapshot
+Replayer
 RCF Summarize
 RPM Package Manager
 Ruby

_api-reference/snapshots/index.md

@@ -13,4 +13,4 @@ redirect_from:
 **Introduced 1.0**
 {: .label .label-purple }
 
-The snapshot APIs allow you to manage snapshots and snapshot repositories.
+The snapshot APIs allow you to manage snapshots and snapshot repositories.

_benchmark/quickstart.md

@@ -12,7 +12,7 @@ This tutorial outlines how to quickly install OpenSearch Benchmark and run your
 
 To perform the Quickstart steps, you'll need to fulfill the following prerequisites:
 
-- A currently active OpenSearch cluster. For instructions on how to create an OpenSearch cluster, see [Creating a cluster]({{site.url}}{{site.baseurl}}//tuning-your-cluster/index/).
+- A currently active OpenSearch cluster. For instructions on how to create an OpenSearch cluster, see [Creating a cluster]({{site.url}}{{site.baseurl}}/tuning-your-cluster/index/).
 - Git 2.3 or greater.
 - Python 3.8 or later
 

_config.yml

@@ -89,6 +89,9 @@ collections:
   data-prepper: 
     permalink: /:collection/:path/
     output: true
+  migrate-or-upgrade:
+    permalink: /:collection/:path/
+    output: true
   migration-assistant:
     permalink: /:collection/:path/
     output: true
@@ -142,7 +145,10 @@ opensearch_collection:
       name: Tutorials
       nav_fold: true
     install-and-configure:
-      name: Install and upgrade
+      name: Install and configure
+      nav_fold: true
+    migrate-or-upgrade:
+      name: Migrate or upgrade
       nav_fold: true
     tuning-your-cluster:
       name: Creating and tuning your cluster
@@ -218,7 +224,7 @@ clients_collection:
 migration_assistant_collection:
   collections:
     migration-assistant:
-        name: Migration Assistant
+        name: Migration Assistant for OpenSearch
         nav_fold: true
 
 benchmark_collection:
@@ -265,7 +271,7 @@ defaults:
       path: "_migration-assistant"
     values:
       section: "migration-assistant"
-      section-name: "Migration Assistant"
+      section-name: "Migration Assistant for OpenSearch"
 
 # Enable or disable the site search
 # By default, just-the-docs enables its JSON file-based search. We also have an OpenSearch-driven search functionality.
@@ -352,4 +358,4 @@ exclude:
   - .bundle/
   - _site/
   - spec-insert
-  - release-notes
+  - release-notes

_data/migration-scenarios.yml

@@ -0,0 +1,91 @@
+scenarios:
+  - title: "Scenario 1: Backfill only"
+    steps:
+      - title: "Assessment"
+        url: "/migration-assistant/migration-phases/assessment/"
+      - title: "Deploy"
+        url: "/migration-assistant/migration-phases/deploy/"
+        substeps:
+          - title: "Verify backfill components"
+            url: "/migration-assistant/migration-phases/deploy/verifying-backfill-components/"
+          - title: "Configuration options"
+            url: "/migration-assistant/migration-phases/deploy/configuration-options/"
+          - title: "IAM and security groups for existing clusters"
+            url: "/migration-assistant/migration-phases/deploy/iam-and-security-groups-for-existing-clusters/"
+      - title: "Create a snapshot"
+        url: "/migration-assistant/migration-phases/create-snapshot/"
+      - title: "Migrate metadata"
+        url: "/migration-assistant/migration-phases/migrate-metadata/"
+        substeps:
+          - title: "Managing type mapping deprecation"
+            url: "/migration-assistant/migration-phases/migrate-metadata/handling-type-mapping-deprecation/"
+          - title: "Handling breaking changes in field types"
+            url: "/migration-assistant/migration-phases/migrate-metadata/handling-field-type-breaking-changes/"
+      - title: "Backfill"
+        url: "/migration-assistant/migration-phases/backfill/"
+      - title: "Teardown"
+        url: "/migration-assistant/migration-phases/remove-migration-infrastructure/"
+
+  - title: "Scenario 2: Live capture only"
+    steps:
+      - title: "Assessment"
+        url: "/migration-assistant/migration-phases/assessment/"
+      - title: "Deploy"
+        url: "/migration-assistant/migration-phases/deploy/"
+        substeps:
+          - title: "IAM and security groups for existing clusters"
+            url: "/migration-assistant/migration-phases/deploy/iam-and-security-groups-for-existing-clusters/"
+          - title: "Configuration options"
+            url: "/migration-assistant/migration-phases/deploy/configuration-options/"
+          - title: "Verify live capture components"
+            url: "/migration-assistant/migration-phases/deploy/verifying-live-capture-components/"
+      - title: "Reroute traffic from the source to the Capture Proxy"
+        url: "/migration-assistant/migration-phases/reroute-source-to-proxy/"
+      - title: "Migrate metadata"
+        url: "/migration-assistant/migration-phases/migrate-metadata/"
+        substeps:
+          - title: "Managing type mapping deprecation"
+            url: "/migration-assistant/migration-phases/migrate-metadata/handling-type-mapping-deprecation/"
+          - title: "Handling breaking changes in field types"
+            url: "/migration-assistant/migration-phases/migrate-metadata/handling-field-type-breaking-changes/"
+      - title: "Replay captured traffic"
+        url: "/migration-assistant/migration-phases/replay-captured-traffic/"
+      - title: "Reroute traffic from the Capture Proxy to the target"
+        url: "/migration-assistant/migration-phases/reroute-traffic-from-capture-proxy-to-target/"
+      - title: "Teardown"
+        url: "/migration-assistant/migration-phases/remove-migration-infrastructure/"
+
+  - title: "Scenario 3: Live capture with backfill"
+    steps:
+      - title: "Assessment"
+        url: "/migration-assistant/migration-phases/assessment/"
+      - title: "Deploy"
+        url: "/migration-assistant/migration-phases/deploy/"
+        substeps:
+          - title: "IAM and security groups for existing clusters"
+            url: "/migration-assistant/migration-phases/deploy/iam-and-security-groups-for-existing-clusters/"
+          - title: "Configuration options"
+            url: "/migration-assistant/migration-phases/deploy/configuration-options/"
+          - title: "Verify backfill components"
+            url: "/migration-assistant/migration-phases/deploy/verifying-backfill-components/"
+          - title: "Verify live capture components"
+            url: "/migration-assistant/migration-phases/deploy/verifying-live-capture-components/"
+      - title: "Reroute traffic from the source to the Capture Proxy"
+        url: "/migration-assistant/migration-phases/reroute-source-to-proxy/"
+      - title: "Create a snapshot"
+        url: "/migration-assistant/migration-phases/create-snapshot/"
+      - title: "Migrate metadata"
+        url: "/migration-assistant/migration-phases/migrate-metadata/"
+        substeps:
+          - title: "Managing type mapping deprecation"
+            url: "/migration-assistant/migration-phases/migrate-metadata/handling-type-mapping-deprecation/"
+          - title: "Handling breaking changes in field types"
+            url: "/migration-assistant/migration-phases/migrate-metadata/handling-field-type-breaking-changes/"
+      - title: "Backfill"
+        url: "/migration-assistant/migration-phases/backfill/"
+      - title: "Replay captured traffic"
+        url: "/migration-assistant/migration-phases/replay-captured-traffic/"
+      - title: "Reroute traffic from the Capture Proxy to the target"
+        url: "/migration-assistant/migration-phases/reroute-traffic-from-capture-proxy-to-target/"
+      - title: "Teardown"
+        url: "/migration-assistant/migration-phases/remove-migration-infrastructure/"

_includes/home_cards.html

@@ -63,10 +63,9 @@
     <div class="home-card">
       <a href="{{site.url}}{{site.latesturl}}/migration-assistant/" class='card-link'></a>
         <p class="heading">Migration Assistant</p>
-        <p class="description">Migrate to OpenSearch.</p>
+        <p class="description">Simplify your upgrade or migration to OpenSearch.</p>
         <p class="last-link">Documentation &#x2192;</p>
       </div>  
   </div>
 
 </div>
-

_includes/migration-scenarios.html

@@ -0,0 +1,33 @@
+{% assign scenarios = include.scenarios %}
+
+{% for scenario in scenarios %}
+<div class="scenario-container" id="scenario-{{ forloop.index }}">
+  <div class="scenario-title">{{ scenario.title }}</div>
+
+  <ol>
+    {% for step in scenario.steps %}
+      <li>
+        {% if step.url %}
+          <a href="{{ site.url }}{{ site.baseurl }}{{ step.url }}">{{ step.title }}</a>
+        {% else %}
+          {{ step.title }}
+        {% endif %}
+
+        {% if step.substeps %}
+          <ul>
+            {% for substep in step.substeps %}
+              <li>
+                {% if substep.url %}
+                  <a href="{{ site.url }}{{ site.baseurl }}{{ substep.url }}">{{ substep.title }}</a>
+                {% else %}
+                  {{ substep.title }}
+                {% endif %}
+              </li>
+            {% endfor %}
+          </ul>
+        {% endif %}
+      </li>
+    {% endfor %}
+  </ol>
+</div>
+{% endfor %}

_includes/nav.html

@@ -66,7 +66,28 @@
     {%- if node.parent == nil -%}
       {%- unless node.nav_exclude -%}
       {% assign nested_owned_tree_id = include.owned_tree_id | append: "_" | append: forloop.index | append: "_" | append: node.title | append: "_navitems" | replace: " ", "_" %}
-      <li role="none" class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
+      {%- comment -%}Check if current page is a descendant of this node{%- endcomment -%}
+      {%- assign is_ancestor = false -%}
+      {%- if page.collection == include.key -%}
+        {%- if page.url == node.url or page.parent == node.title or page.grand_parent == node.title -%}
+          {%- assign is_ancestor = true -%}
+        {%- else -%}
+          {%- comment -%}Check for 4-level deep pages{%- endcomment -%}
+          {%- for child in pages_list -%}
+            {%- if child.parent == node.title -%}
+              {%- for grand_child in pages_list -%}
+                {%- if grand_child.parent == child.title and grand_child.grand_parent == node.title -%}
+                  {%- if page.parent == grand_child.title -%}
+                    {%- assign is_ancestor = true -%}
+                    {%- break -%}
+                  {%- endif -%}
+                {%- endif -%}
+              {%- endfor -%}
+            {%- endif -%}
+          {%- endfor -%}
+        {%- endif -%}
+      {%- endif -%}
+      <li role="none" class="nav-list-item{% if is_ancestor %} active{% endif %}">
         {%- if node.has_children -%}
           <a
             role="treeitem"
@@ -89,7 +110,22 @@
           <ul role="tree" class="nav-list" id="{{ nested_owned_tree_id }}">
           {%- for child in children_list -%}
             {%- unless child.nav_exclude -%}
-            <li role="none" class="nav-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
+            {%- comment -%}Check if current page is a descendant of this child{%- endcomment -%}
+            {%- assign child_is_ancestor = false -%}
+            {%- if page.url == child.url or page.parent == child.title -%}
+              {%- assign child_is_ancestor = true -%}
+            {%- else -%}
+              {%- comment -%}Check for 4-level deep pages{%- endcomment -%}
+              {%- for grand_child in pages_list -%}
+                {%- if grand_child.parent == child.title and grand_child.grand_parent == node.title -%}
+                  {%- if page.parent == grand_child.title -%}
+                    {%- assign child_is_ancestor = true -%}
+                    {%- break -%}
+                  {%- endif -%}
+                {%- endif -%}
+              {%- endfor -%}
+            {%- endif -%}
+            <li role="none" class="nav-list-item{% if child_is_ancestor %} active{% endif %}">
               {%- if child.has_children -%}
                 {% assign nested_nested_owned_tree_id = nested_owned_tree_id | append: "_" | append: forloop.index | append: "_" | append: child.title | append: "_navitems" | replace: " ", "_" %}
                 <a
@@ -112,13 +148,46 @@
                 <ul role="tree" class="nav-list" id="{{ nested_nested_owned_tree_id }}">
                 {%- for grand_child in grand_children_list -%}
                   {%- unless grand_child.nav_exclude -%}
-                  <li role="none" class="nav-list-item {% if page.url == grand_child.url %} active{% endif %}">
+                  {%- comment -%}Check if current page is a descendant of this grand_child{%- endcomment -%}
+                  {%- assign grand_child_is_ancestor = false -%}
+                  {%- if page.url == grand_child.url or page.parent == grand_child.title -%}
+                    {%- assign grand_child_is_ancestor = true -%}
+                  {%- endif -%}
+                  <li role="none" class="nav-list-item{% if grand_child_is_ancestor %} active{% endif %}">
+                    {%- if grand_child.has_children -%}
+                      {% assign nested_nested_nested_owned_tree_id = nested_nested_owned_tree_id | append: "_" | append: forloop.index | append: "_" | append: grand_child.title | append: "_navitems" | replace: " ", "_" %}
+                      <a
+                        role="treeitem"
+                        aria-owns="{{ nested_nested_nested_owned_tree_id }}"
+                        {%- if page.url == grand_child.url -%}aria-current="page"{%- endif -%}
+                        href="#" 
+                        class="nav-list-expander"
+                      ><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
+                    {%- endif -%}
                     <a
                       role="treeitem"
+                      {%- if grand_child.has_children -%}aria-owns="{{ nested_nested_nested_owned_tree_id }}"{%- endif -%}
                       {%- if page.url == grand_child.url -%}aria-current="page"{%- endif -%}
                       href="{{ grand_child.url | absolute_url }}" 
                       class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}"
                     >{{ grand_child.title }}</a>
+                    {%- if grand_child.has_children -%}
+                      {%- assign great_grand_children_list = pages_list | where: "parent", grand_child.title -%}
+                      <ul role="tree" class="nav-list" id="{{ nested_nested_nested_owned_tree_id }}">
+                      {%- for great_grand_child in great_grand_children_list -%}
+                        {%- unless great_grand_child.nav_exclude -%}
+                        <li role="none" class="nav-list-item {% if page.url == great_grand_child.url %} active{% endif %}">
+                          <a
+                            role="treeitem"
+                            {%- if page.url == great_grand_child.url -%}aria-current="page"{%- endif -%}
+                            href="{{ great_grand_child.url | absolute_url }}" 
+                            class="nav-list-link{% if page.url == great_grand_child.url %} active{% endif %}"
+                          >{{ great_grand_child.title }}</a>
+                        </li>
+                        {%- endunless -%}
+                      {%- endfor -%}
+                      </ul>
+                    {%- endif -%}
                   </li>
                   {%- endunless -%}
                 {%- endfor -%}

_install-and-configure/configuring-opensearch/index.md

@@ -4,8 +4,8 @@ title: Configuring OpenSearch
 nav_order: 10
 has_children: true
 redirect_from:
-  - /install-and-configure/configuring-opensearch/
   - /opensearch/configuration/
+  - /install-and-configure/configuring-opensearch/
 ---
 
 # Configuring OpenSearch

_install-and-configure/index.md

@@ -28,8 +28,4 @@ OpenSearch and OpenSearch Dashboards are available on any compatible host that s
 
 After you've installed OpenSearch, learn about [configuring]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/) it for your deployment.
 
-For more information about upgrading your OpenSearch cluster, see the [upgrade guide]({{site.url}}{{site.baseurl}}/install-and-configure/upgrade-opensearch/index/).
-
-For information about upgrade tools, see [OpenSearch upgrade, migration, and comparison tools]({{site.url}}{{site.baseurl}}/tools/index/#opensearch-upgrade-migration-and-comparison-tools).
-
 For plugin installation, see [Installing plugins]({{site.url}}{{site.baseurl}}/install-and-configure/plugins/).