Theme JSON Docs: Clarify null, true, and false values for blockGap se…

…tting (#42447) * Theme JSON Documentation: Clarify null, true, and false values for blockGap setting * Clarify which blockGap value is ouput to the CSS variable * Improve clarity of boolean vs null Co-authored-by: Aaron Robertshaw <[email protected]> * Change in to to into Co-authored-by: Aaron Robertshaw <[email protected]> * Remove redundant words Co-authored-by: Aaron Robertshaw <[email protected]> * Add `the` to null description Co-authored-by: Aaron Robertshaw <[email protected]> Co-authored-by: Aaron Robertshaw <[email protected]>
WordPress · Jul 18, 2022 · a9e8a85 · a9e8a85
1 parent 8dc70b4
commit a9e8a85
Showing 1 changed file with 10 additions and 7 deletions.
diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md
@@ -1147,7 +1147,7 @@ body {
 
 /* CSS classes for the preset values */
 .has-<PRESET_SLUG>-<PRESET_TYPE> { ... }
-.has-pale-pink-color { color: var(--wp--preset--color--pale-pink) !important; } 
+.has-pale-pink-color { color: var(--wp--preset--color--pale-pink) !important; }
 .has-large-font-size { font-size: var(--wp--preset--font-size--large) !important; }
 ```
 
@@ -1179,12 +1179,7 @@ As a result of this change, it’s now the block author and theme author’s res
 
 ### What is blockGap and how can I use it?
 
-blockGap adjusts the vertical margin, or gap, between blocks.
-It is also used for margins between inner blocks in columns, buttons, and social icons.
-In the editor, the control for the blockGap is called Block spacing, located in the Dimensions panel.
-
-The value you define for the blockGap style uses a CSS property, a preset, named `--wp--style--block-gap`.
-The default value is 2em.
+For blocks that contain inner blocks, such as Group, Columns, Buttons, and Social Icons, `blockGap` controls the spacing between inner blocks. Depending on the layout of the block, the `blockGap` value will be output as either a vertical margin or a `gap` value. In the editor, the control for the `blockGap` value is called _Block spacing_, located in the Dimensions panel.
 
 ```json
 {
@@ -1202,6 +1197,14 @@ The default value is 2em.
 }
 ```
 
+The setting for `blockGap` is either a boolean or `null` value and is `null` by default. This allows an extra level of control over style output. The `settings.spacing.blockGap` setting in a `theme.json` file accepts the following values:
+
+- `true`: Opt into displaying _Block spacing_ controls in the editor UI and output `blockGap` styles.
+- `false`: Opt out of displaying _Block spacing_ controls in the editor UI, with `blockGap` styles stored in `theme.json` still being rendered. This allows themes to use `blockGap` values without allowing users to make changes within the editor.
+- `null` (default): Opt out of displaying _Block spacing_ controls, _and_ prevent the output of `blockGap` styles.
+
+The value defined for the root `styles.spacing.blockGap` style is also output as a CSS property, named `--wp--style--block-gap`.
+
 ### Why does it take so long to update the styles in the browser?
 
 When you are actively developing with theme.json you may notice it takes 30+ seconds for your changes to show up in the browser, this is because `theme.json` is cached. To remove this caching issue, set either [`WP_DEBUG`](https://wordpress.org/support/article/debugging-in-wordpress/#wp_debug) or [`SCRIPT_DEBUG`](https://wordpress.org/support/article/debugging-in-wordpress/#script_debug) to 'true' in your [`wp-config.php`](https://wordpress.org/support/article/editing-wp-config-php/). This tells WordPress to skip the cache and always use fresh data.