Add upgrade docs for users of @kitconcept/volto-blocks-grid addon (#…

…5333)

Co-authored-by: Steve Piercy <[email protected]>

docs/source/blocks/core/grid.md

@@ -12,6 +12,7 @@ myst:
 # Grid block
 
 ```{versionadded} Volto 17.0.0-alpha.16
+See {ref}`grid-block-migration-from-kitconcept-volto-blocks-grid-label`.
 ```
 
 Volto comes with a grid block.
@@ -156,16 +157,3 @@ export const GridBlockDataAdapter = ({
   onChangeBlock(block, dataSaved);
 };
 ```
-
-
-## Migration from `@kitconcept/volto-blocks-grid`
-
-The grid block was added to Volto in version 17.0.0-alpha.16.
-It is based on the `@kitconcept/volto-blocks-grid` add-on version 7.x.x.
-
-The Volto core grid uses the Volto internals default blocks-in-block architecture.
-This differs from the grid block data structure in the add-on `@kitconcept/volto-blocks-grid`.
-Because of this difference, they are not compatible, and a data migration is necessary from the add-on to the Volto grid block.
-
-However, the Volto core grid block uses a different internal name, `gridBlock`, so both blocks can coexist at the same time.
-Nonetheless, it is recommended to enable only one grid block type for your users, and eventually use a single version to avoid unexpected behaviors and bugs.

docs/source/upgrade-guide/index.md

@@ -265,6 +265,37 @@ It requires the latest version of `plone.restapi` (>=8.42.0) installed in the ba
 The `utils.js` file of the Teaser block was removed because it is no longer used.
 You can consider removing it if you were shadowing it in your project.
 
+(grid-block-migration-from-kitconcept-volto-blocks-grid-label)=
+
+### Grid block migration from `@kitconcept/volto-blocks-grid`
+
+The grid block was added to Volto in version 17.0.0-alpha.16.
+It is based on the `@kitconcept/volto-blocks-grid` add-on version 7.x.x.
+
+If you previously used `@kitconcept/volto-blocks-grid` in your project based on a Volto version before 17.0.0-alpha.16, then your site will show two available block types both named `Grid`.
+You need to disable one of them based on the following information.
+
+The Volto core grid block uses the Volto default internal blocks-in-block architecture.
+This differs from the grid block data structure in the add-on `@kitconcept/volto-blocks-grid`.
+Because of this difference, they are not compatible, and a data migration is necessary from the add-on to the Volto grid block.
+This migration is not yet available.
+
+However, the Volto core grid block uses a different internal name, `gridBlock`, so both block types can coexist.
+Nonetheless, it is recommended to enable only one grid block type for your users, and eventually use a single version to avoid unexpected behaviors and bugs.
+
+You can disable the one you won't use with one of the following configuration settings.
+
+```js
+// This disables the `@kitconcept/volto-blocks-grid` grid block
+config.blocks.blocksConfig.__grid.restricted = true;
+
+// This disables the Volto core grid block
+config.blocks.blocksConfig.gridBlock.restricted = true;
+```
+
+As long as you keep the add-on in place, your existing blocks will work as expected, even if you restrict the block.
+We recommend that you disable the `@kitconcept/volto-blocks-grid` block and use the new Volto core grid block for new content.
+
 
 (volto-upgrade-guide-16.x.x)=
 

news/5333.documentation

@@ -0,0 +1 @@
+Add upgrade docs for users of `@kitconcept/volto-blocks-grid` addon @sneridagh