ravendb · ppekrol · Jan 23, 2026 · Jan 23, 2026 · Jan 23, 2026
diff --git a/docs/migration/client-api/client-migration.mdx b/docs/migration/client-api/client-migration.mdx
@@ -18,7 +18,7 @@ import LanguageContent from "@site/src/components/LanguageContent";
    * [Client migration to RavenDB `7.x`](../../migration/client-api/client-migration.mdx#client-migration-to-ravendb-7x)
 
 </Admonition>
-## Client migration to RavenDB `7.x`
+## Client migration to RavenDB 7.x
 
 Prior to version `7.0`, our default HTTP compression algorithm was `Gzip`.  
 From version `7.0` on, our default HTTP compression algorithm is `Zstd`.  
@@ -30,7 +30,7 @@ Version `7.0`'s client API ability to connect to a server depends on the
 * But if you want to connect the client to a server of version `5.4` or earlier, 
   you must switch the client algorithm back to `Gzip` for the connection to succeed.  
   <Admonition type="info" title="">
-  [See how to switch the algorithm to Gzip](../../migration/client-api/client-breaking-changes.mdx#http-compression-algorithm-is-now-zstd-by-default)
+  [See how to switch the algorithm to Gzip](../../migration/client-api/previous-versions-client-breaking-changes#http-compression-algorithm-is-now-zstd-by-default)
   </Admonition>
 
 
diff --git a/docs/migration/client-api/previous-versions-client-breaking-changes.mdx b/docs/migration/client-api/previous-versions-client-breaking-changes.mdx
diff --git a/docs/migration/server/assets/breaking-changes_SQL-ETL-task.png b/docs/migration/server/assets/breaking-changes_SQL-ETL-task.png
diff --git a/docs/migration/server/assets/breaking-changes_identity-parts-separator.png b/docs/migration/server/assets/breaking-changes_identity-parts-separator.png
diff --git a/docs/migration/server/assets/breaking-changes_new-separator.png b/docs/migration/server/assets/breaking-changes_new-separator.png
diff --git a/docs/migration/server/data-migration.mdx b/docs/migration/server/data-migration.mdx
@@ -10,98 +10,64 @@ import TabItem from '@theme/TabItem';
 import CodeBlock from '@theme/CodeBlock';
 import LanguageSwitcher from "@site/src/components/LanguageSwitcher";
 import LanguageContent from "@site/src/components/LanguageContent";
+import Panel from "@site/src/components/Panel";
+import ContentFrame from "@site/src/components/ContentFrame";
 
 # Data Migration
 <Admonition type="note" title="">
 
+* Upgrading RavenDB `6.x` and above to a higher version supports in-place data migration: exporting and re-importing the data are not needed.  
+
+* Create a backup of your data before upgrading, to avoid any data loss in case of unexpected issues.
+
+* Find a migration guide for RavenDB `5.x` and earlier versions [here](../../migration/server/legacy-versions-data-migration.mdx).
+
 * In this article:
-    * [Migration to RavenDB `7.x`](../../migration/server/data-migration.mdx#migration-to-ravendb-7x)
-    * [Migration from RavenDB 5.x to 6.x](../../migration/server/data-migration.mdx#migration-from-ravendb-5x-to-6x)
-    * [Migration from RavenDB 4.x to RavenDB 5.x and 6.x](../../migration/server/data-migration.mdx#migration-from-ravendb-4x-to-ravendb-5x-and-6x)
-    * [Migration from RavenDB 3.x](../../migration/server/data-migration.mdx#migration-from-ravendb-3x)
+    * [Migration to RavenDB 7.x from a lower version](../../migration/server/data-migration#migration-to-ravendb-7-x-from-a-lower-version)
+       * [Migration and NLog](../../migration/server/data-migration#migration-and-nlog)
+       * [Migration and HTTP compression](../../migration/server/data-migration#migration-and-http-compression)
     * [Migrating data into a sharded database](../../migration/server/data-migration.mdx#migrating-data-into-a-sharded-database)
 
 </Admonition>
-## Migration to RavenDB `7.x`
 
-<Admonition type="note" title="Migration and NLog:" id="migration-and-nlog" href="#migration-and-nlog">
+<Panel heading="Migration to RavenDB 7.x from a lower version">
+
+<ContentFrame>
+
+### Migration and NLog
 
 Starting with version `7.0`, RavenDB incorporates the 
-[NLog logging frmework](../../server/troubleshooting/logging.mdx) and writes all log 
+[NLog logging framework](../../server/troubleshooting/logging.mdx) and writes all log 
 data through it.  
 
 Logging settings applied in earlier RavenDB versions are respected by RavenDB `7.x`, 
 and logging should continue by these settings without interference after the migration.  
 
 If you want to use NLog-specific features, though, you will have to address a different set 
 of settings that NLog requires.  
-You can [learn more here about migration and the new logging system](../../server/troubleshooting/logging.mdx#customize-after-migration).  
+[Learn more here about migration and the new logging system.](../../server/troubleshooting/logging.mdx#customize-after-migration).  
+
+</ContentFrame>
+<ContentFrame>
 
-</Admonition> 
-<Admonition type="note" title="Migration and HTTP Compression:" id="migration-and-http-compression" href="#migration-and-http-compression">
+### Migration and HTTP compression
 
 From RavenDB `7.0` on, the default HTTP compression algorithm is `Zstd`.  
 Earlier versions used `Gzip`.  
 
-* If your current server version is `6.0` or higher, the compression algorithm 
-  will present no problem while connecting it to a server of version `7.0` and 
-  migrating your data.  
+* If your current server version is `6.0` or higher, the compression algorithm will present no problem while connecting it to RavenDB `7.0` or higher and migrating your data.  
 
-* If your current server version is `5.4` or earlier, attempting to connect it 
-  to a server that uses the `Zstd` compression algorithm will fail.  
-  For the connection to succeed, you need to:  
-   1. Temporarily switch the target version `7.0` server compression algorithm to `Gzip`.  
+* If your current server version is `5.4` or earlier, attempting to connect it to a server that uses the `Zstd` compression algorithm will fail.  
+  For the connection to succeed, you need to:
+   1. Temporarily switch the target version `7.x` server compression algorithm to `Gzip`.  
       Do this by defining a `RAVEN_HTTP_COMPRESSION_ALGORITHM` environment variable on 
-      the `7.0` server machine and setting its value to `Gzip`, and restarting the server.  
+      the `7.x` server machine and setting its value to `Gzip`, and restarting the server.  
    2. Connect your current server to the new server and perform the migration.  
    3. When the new server is updated, remove the environment variable and restart the server.  
 
-</Admonition>
-
-
-
-## Migration from RavenDB 5.x to 6.x
-
-* RavenDB `6.x` supports in-place data migration from RavenDB `5.x`.
-* RavenDB `5.x` product licenses **do not apply** to RavenDB `6.x`.  
-  To upgrade a valid `5.x` license to a RavenDB `6.x` license,  
-  please use the **License upgrade tool** [as explained here](../../start/licensing/replace-license.mdx#upgrade-a-license-key-for-ravendb-6x).
-
-<Admonition type="warning" title="">
-Please note that once upgraded, RavenDB `6.x` cannot be downgraded to version `5.x`,  
-and the migrated data will no longer be accessible via RavenDB `5.x`.  
-**Please create a backup of your data before migrating.**  
-</Admonition>
-
-
-
-## Migration from RavenDB 4.x to RavenDB 5.x and 6.x
-
-* RavenDB `5.x` supports in-place data migration from RavenDB `4.x`.
-  <Admonition type="info" title="">
-  Upgrading directly from version `4.x` to `6.x` is possible,  
-  but it is recommended to upgrade RavenDB `4.x` to `5.x` first,  
-  and then proceed with an upgrade from version `5.x` to `6.x`.
-  </Admonition>
-* RavenDB `4.x` product licenses **do not apply** to RavenDB `6.x`.  
-  To upgrade a valid `4.x` license to a RavenDB `6.x` license,  
-  please use the **License upgrade tool** [as explained here](../../start/licensing/replace-license.mdx#upgrade-a-license-key-for-ravendb-6x).
-
-<Admonition type="warning" title="">
-Please note that once upgraded, RavenDB `6.x` cannot be downgraded to version `4.x`,  
-and data migrated to `5.x` or `6.x` will no longer be accessible via RavenDB `4.x`.  
-**Please create a backup of your data before migrating.**  
-</Admonition>
-
-
-
-## Migration from RavenDB 3.x
-
-* The information above relates only to data migration from RavenDB `4.x` to `5.x`/`6.x` and from `5.x` to `6.x`.
-* If you want to migrate your data from a RavenDB version earlier than `4.x`,  
-  please read the dedicated article [here](https://ravendb.net/docs/article-page/4.2/csharp/migration/server/data-migration).
-
+</ContentFrame>
 
+</Panel>
 
 ## Migrating data into a sharded database
 

diff --git a/docs/migration/server/docker.mdx b/docs/migration/server/docker.mdx
@@ -1,7 +1,7 @@
 ---
-title: "Migration: Migrating from Docker Image 5.x or lower to 6.0 or higher"
+title: "Migration: Migrating from Docker image 5.x or lower to 6.0 or higher"
 sidebar_label: Docker
-sidebar_position: 1
+sidebar_position: 2
 ---
 
 import Admonition from '@theme/Admonition';
@@ -10,30 +10,30 @@ import TabItem from '@theme/TabItem';
 import CodeBlock from '@theme/CodeBlock';
 import LanguageSwitcher from "@site/src/components/LanguageSwitcher";
 import LanguageContent from "@site/src/components/LanguageContent";
+import Panel from "@site/src/components/Panel";
+import ContentFrame from "@site/src/components/ContentFrame";
 
-# Migration: Migrating from Docker Image 5.x or lower to 6.0 or higher
+# Migration: Migrating from Docker image 5.x or lower to 6.0 or higher
 <Admonition type="note" title="">
 
-* Starting from version `6.0` RavenDB for Docker introduces an 
-  improved security model, using a dedicated user rather than `root`.  
+* Starting with version `6.0`, RavenDB for Docker introduces an improved security model, using a dedicated user rather than `root`.  
 * RavenDB `6.0` and up also use a Debian archive file 
-  ([.deb package](../../start/installation/gnu-linux/deb.mdx)), 
-  applying a uniform internal structure for Ubuntu OS platforms.  
-* To conform with these changes, installing RavenDB `6.0` or higher 
-  in a system that already hosts RavenDB `5.x` or lower requires 
-  the migration procedure explained below.  
+  ([.deb package](../../start/installation/gnu-linux/deb.mdx)), applying a uniform internal structure for Ubuntu OS platforms.  
+* To conform with these changes, installing RavenDB `6.0` or higher in a system that already hosts RavenDB `5.x` or lower requires the migration procedure explained below.  
 * Read [here](../../start/containers/image-usage.mdx) more about running a RavenDB Docker image.  
 
 * In this article:  
-  * [Changes Made In RavenDB `6.0` And Up](../../migration/server/docker.mdx#changes-made-in-ravendb-60-and-up)  
-  * [Migrating To `6.0` And Up](../../migration/server/docker.mdx#migrating-to-60-and-up)  
+  * [Changes Made In RavenDB `6.0` And Up](../../migration/server/docker#changes-made-in-ravendb-6-0-and-up)  
+  * [Migrating To RavenDB `6.0` And Up](../../migration/server/docker#migrating-to-ravendb-6-0-and-up)  
+     * [Permit the `ravendb` user to access the mounted data directory](../../migration/server/docker#permit-the-ravendb-user-to-access-the-mounted-data-directory)  
+     * [Customize the UID/GID of the RavenDB data directory owner](../../migration/server/docker#customize-the-uidgid-of-the-ravendb-data-directory-owner)  
+     * [Migrate files and data](../../migration/server/docker#migrate-files-and-data)  
 
 </Admonition>
-## Changes Made In RavenDB 6.0 And Up  
 
-The **directory structure** used by RavenDB of version `6.0` 
-and above, and the **user** we use to run RavenDB, are different 
-from the directory structure and user used by older versions.  
+<Panel heading="Changes Made In RavenDB 6.0 And Up">
+
+The **directory structure** used by RavenDB of version `6.0` and above, and the **user** we use to run RavenDB, are different from the directory structure and user used by older versions.  
 
 * RavenDB Docker images up to `5.x`:  
    * Create a unique directory structure under Windows.  
@@ -42,54 +42,62 @@ from the directory structure and user used by older versions.
 * RavenDB Docker images from `6.0` up:  
    * Use a Debian archive file ([.deb package](../../start/installation/gnu-linux/deb.mdx)) 
      and create a similar directory structure under Windows and Ubuntu.  
-   * Are installed and accessed using a dedicated `ravendb` user 
-     instead of `root`, to improve security.  
-
-Learn below how to address these differences when migrating 
-from version `5.x` or lower to version `6.0` or higher.  
+   * Are installed and accessed using a dedicated `ravendb` user instead of `root`, to improve security.  
 
+Learn below how to address these differences when migrating from version `5.x` or lower to version `6.0` or higher.  
+</Panel>
 
+<Panel heading="Migrating To RavenDB `6.0` And Up">
 
-## Migrating To `6.0` And Up  
+<ContentFrame>
 
-## Permit `ravendb` user to access mounted data directory.  
+### Permit the `ravendb` user to access the mounted data directory
 
 The default **UID** (User ID) and **GID** (Group ID) 
 used by `ravendb` are **999**.  
-Change owner of the RavenDB data directory to `ravendb` (`999` UID by default) on the container host.
-E.g. `chown -R 999:999 $TARGET_DATA_DIR`
+Change the RavenDB data directory owner to `ravendb` (`999` UID by default) on the container host.  
+E.g.,
+```bash
+chown -R 999:999 $TARGET_DATA_DIR
+```
+</ContentFrame>
+
+<ContentFrame>
 
-## Customizing the RavenDB data directory owner user UID/GID 
+### Customize the UID/GID of the RavenDB data directory owner
 
 To customize the **UID** and **GID** of the `ravendb` user (e.g. to match your host user or for volume permissions), you can build your own image using the official `ravendb` base image. 
 
-<TabItem value="csharp" label="csharp">
-<CodeBlock language="csharp">
-{`FROM ravendb/ravendb:7.0-ubuntu-latest
+```dockerfile
+FROM ravendb/ravendb:7.2-ubuntu-latest
 
 ARG USER_ID=1000
 ARG GROUP_ID=1000
 
 USER root
 
-RUN groupmod -g "$\{GROUP_ID\}" "ravendb" && \\
-usermod  -u "$\{USER_ID\}" -g "$\{GROUP_ID\}" ravendb && \\
-chown root:$\{USER_ID\} /etc/ravendb/settings.json && \\
-find / -xdev -uid 0 -gid 999 -exec chown "root:$\{GROUP_ID\}" \{\} +
-
+RUN groupmod -g "${GROUP_ID}" "ravendb" && \
+usermod  -u "${USER_ID}" -g "${GROUP_ID}" ravendb && \
+chown root:"${USER_ID}" /etc/ravendb/settings.json && \
+find / -xdev -uid 0 -gid 999 -exec chown "root:${GROUP_ID}" {} +
 
 USER ravendb
-`}
-</CodeBlock>
-</TabItem>
-
-### Build Instructions 
+```
 
+<Admonition type="info" title="Build Instructions">
 1. Save the above as `dockerfile` 
 2. Open a terminal in that directory 
-3. Build the custom image with your desired UID and GID: `docker build --build-arg USER_ID=YourUserID --build-arg GROUP_ID=YourGroupID -t image-name -f dockerfile`
+3. Build the custom image with your UID and GID:
 
-## Migrate files and data  
+```bash
+docker build --build-arg USER_ID=YourUserID --build-arg GROUP_ID=YourGroupID -t image-name -f dockerfile
+```
+</Admonition>
+</ContentFrame>
+
+<ContentFrame>
+
+### Migrate files and data
 
 The setup process will create the directory structure detailed 
 [here](../../start/installation/gnu-linux/deb.mdx#file-system-locations).  
@@ -98,10 +106,9 @@ The script within the image will attempt to link the old version's
 data directory to the new version's data directory automatically upon start.  
 If this attempt fails, an error will be produced.  
 
-When mounting host directory make sure that **RavenDB data** is mounted under its new 
-location on the container: `/var/lib/ravendb/data`  
+When mounting a host directory, make sure that **RavenDB data** is mounted under its new location on the container: `/var/lib/ravendb/data`  
 
-Old data directory (default): `/opt/RavenDB/Server/RavenData`
+Old data directory (default): `/opt/RavenDB/Server/RavenData`  
 New data directory (default): `/var/lib/ravendb/data`
-
-
+</ContentFrame>
+</Panel>
diff --git a/docs/migration/server/legacy-versions-data-migration.mdx b/docs/migration/server/legacy-versions-data-migration.mdx
@@ -0,0 +1,74 @@
+---
+title: "Data Migration"
+sidebar_label: Legacy versions data migration
+sidebar_position: 1
+---
+
+import Admonition from '@theme/Admonition';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+import LanguageSwitcher from "@site/src/components/LanguageSwitcher";
+import LanguageContent from "@site/src/components/LanguageContent";
+import Panel from "@site/src/components/Panel";
+import ContentFrame from "@site/src/components/ContentFrame";
+
+# Legacy versions data Migration
+<Admonition type="note" title="">
+
+* Learn in this article how to upgrade RavenDB versions lower than `6.x`.
+
+* Find a migration guide for RavenDB `6.x` and above [here](../../migration/server/data-migration.mdx).
+
+* In this article:
+    * [Migration from RavenDB 5.x to a higher version](../../migration/server/legacy-versions-data-migration#migration-from-ravendb-5-x-to-a-higher-version)
+    * [Migration from RavenDB 4.x to a higher version](../../migration/server/legacy-versions-data-migration#migration-from-ravendb-4-x-to-a-higher-version)
+    * [Migration from RavenDB 3.x to a higher version](../../migration/server/legacy-versions-data-migration#migration-from-ravendb-3-x-to-a-higher-version)
+    * [Migrating data into a sharded database](../../migration/server/legacy-versions-data-migration#migrating-data-into-a-sharded-database)
+
+</Admonition>
+
+<Panel heading="Migration from RavenDB 5.x to a higher version">
+
+* Upgrading RavenDB `5.x` to a higher version supports in-place data migration: exporting and re-importing the data are not needed.  
+
+* RavenDB `5.x` licenses **do not apply** to RavenDB `6.x` and above.  
+  To upgrade a valid `5.x` license to a RavenDB `6.x` and above license, use the **License upgrade tool** [as explained here](../../start/licensing/replace-license.mdx#upgrade-a-license-key-for-ravendb-6x).
+
+<Admonition type="warning" title="">
+Note that once upgraded, RavenDB `6.x` and higher versions cannot be downgraded to version `5.x`, and the migrated data will no longer be accessible via RavenDB `5.x`.  
+Create a backup of your data before upgrading to keep the data safe and accessible.
+</Admonition>
+
+</Panel>
+
+<Panel heading="Migration from RavenDB 4.x to a higher version">
+
+* Upgrading RavenDB `4.x` to version `5.x` or higher supports in-place data migration: exporting and re-importing the data are not needed.  
+  <Admonition type="info" title="">
+  Upgrading directly from version `4.x` to `6.x` and above is possible, but it is recommended to upgrade RavenDB `4.x` to `5.x` first, and then proceed with an upgrade from version `5.x` to `6.x` or above.
+  </Admonition>
+
+* RavenDB `4.x` licenses **do not apply** to RavenDB `6.x` and above.  
+  To upgrade a valid `4.x` license to a RavenDB `6.x` and above license, use the **License upgrade tool** [as explained here](../../start/licensing/replace-license.mdx#upgrade-a-license-key-for-ravendb-6x).
+
+<Admonition type="warning" title="">
+Note that once upgraded, RavenDB `6.x` and higher versions cannot be downgraded to version `4.x`, and the migrated data will no longer be accessible via RavenDB `4.x`.  
+Create a backup of your data before upgrading to keep the data safe and accessible.
+</Admonition>
+
+</Panel>
+
+<Panel heading="Migration from RavenDB 3.x to a higher version">
+
+If you want to migrate your data from a RavenDB version earlier than `4.x`, please read the dedicated article [here](https://ravendb.net/docs/article-page/4.2/csharp/migration/server/data-migration).
+
+</Panel>
+
+<Panel heading="Migrating data into a sharded database">
+
+If you want to migrate your data to a [sharded](../../sharding/overview.mdx) database (supported by RavenDB `6.0` and above),  
+please read the related article [here](../../sharding/migration.mdx).
+
+</Panel>
+