diff --git a/docs/migration-v5-to-v6.md b/docs/migration-v5-to-v6.md
index e4f441382..210d343bb 100644
--- a/docs/migration-v5-to-v6.md
+++ b/docs/migration-v5-to-v6.md
@@ -1,14 +1,14 @@
-# Migration guide from Verdaccio 5 to Verdaccio 6
+# Migration Guide from Verdaccio 5 to Verdaccio 6
 
 Notes regarding breaking changes for next major release.
 
-> This list might growth over the development.
+> This list might growth over the course of development.
 
-## Breaking changes
+## Breaking Changes
 
 ### New node-api interface [#2165](https://github.com/verdaccio/verdaccio/pull/2165)
 
-If you are using the node-api, the new structure is Promise based and less arguments.
+If you are using the `node-api`, the new structure is Promise based and less arguments.
 
 ```js
 import { runServer } from '@verdaccio/node-api';
@@ -22,7 +22,7 @@ app.listen(4000, (event) => {
 });
 ```
 
-### allow other password hashing algorithms [#1917](https://github.com/verdaccio/verdaccio/pull/1917)
+### Allow other password hashing algorithms [#1917](https://github.com/verdaccio/verdaccio/pull/1917)
 
 The current implementation of the `htpasswd` module supports multiple hash formats on verify, but only `crypt` on sign in.
 `crypt` is an insecure old format, so to improve the security of the new `verdaccio` release we introduce the support of multiple hash algorithms on sign in step.
@@ -53,21 +53,28 @@ htpasswd:
 
 - The `experiments` configuration is renamed to `flags`. The functionality is exactly the same.
 
-```js
-flags: token: false;
-search: false;
+```yaml
+flags:
+  token: false;
+  search: false;
 ```
 
 - The `self_path` property from the config file is being removed in favor of `config_file` full path.
 - Refactor `config` module, better types and utilities
 
-### legacy token signature by removing crypto.createDecipher is deprecated [#1953](https://github.com/verdaccio/verdaccio/pull/1953)
+### Legacy token signature by removing crypto.createDecipher is deprecated [#1953](https://github.com/verdaccio/verdaccio/pull/1953)
 
 - Replace signature handler for legacy tokens by removing deprecated crypto.createDecipher by createCipheriv
 - **The new signature invalidates all previous tokens generated by Verdaccio 5 or previous versions**.
 - The secret key must have 32 characters long
   > Remediation, update `.verdaccio-db.json` secret field with a secret key with 32 characters.
 
+### Legacy token secret length
+
+If the migration to v6 include an update to node 22 or higher, be aware that token secrets with a length other than 32 are not
+supported anymore. A new secret will be generated. See [docs](https://verdaccio.org/docs/6.x/configuration#legacy-token-signature)
+for more details.
+
 #### New environment variables
 
 Introduce environment variables for legacy tokens.