From d496b787a50e063d460f80d9c9fbc48cbc568b7b Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Mon, 15 Jul 2024 22:22:29 -0500
Subject: [PATCH 01/43] Replace keys with Object.keys

---
 bin/api-docs/gen-theme-reference.mjs | 34 ++++++++++------------------
 1 file changed, 12 insertions(+), 22 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index a447948d4593c..0373d6abfb4e1 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -65,20 +65,6 @@ const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );
 
 const themejson = await $RefParser.dereference( THEME_JSON_SCHEMA_FILE );
 
-/**
- * Convert object keys to an array.
- * Gracefully handles non-object values.
- *
- * @param {*} maybeObject
- * @return {Array} Object keys
- */
-const keys = ( maybeObject ) => {
-	if ( typeof maybeObject !== 'object' ) {
-		return [];
-	}
-	return Object.keys( maybeObject );
-};
-
 /**
  * Convert settings properties to markup.
  *
@@ -90,7 +76,7 @@ const getSettingsPropertiesMarkup = ( struct ) => {
 		return '';
 	}
 	const props = struct.properties;
-	const ks = keys( props );
+	const ks = Object.keys( props );
 	if ( ks.length < 1 ) {
 		return '';
 	}
@@ -102,7 +88,9 @@ const getSettingsPropertiesMarkup = ( struct ) => {
 		let type = props[ key ].type || '';
 		let ps =
 			props[ key ].type === 'array'
-				? keys( props[ key ].items.properties ).sort().join( ', ' )
+				? Object.keys( props[ key ].items?.properties ?? {} )
+						.sort()
+						.join( ', ' )
 				: '';
 
 		/*
@@ -121,7 +109,9 @@ const getSettingsPropertiesMarkup = ( struct ) => {
 					.map( ( item ) =>
 						item?.type === 'object' && item?.properties
 							? '_{' +
-							  keys( item.properties ).sort().join( ', ' ) +
+							  Object.keys( item.properties )
+									.sort()
+									.join( ', ' ) +
 							  '}_'
 							: ''
 					)
@@ -146,7 +136,7 @@ const getStylePropertiesMarkup = ( struct ) => {
 		return '';
 	}
 	const props = struct.properties;
-	const ks = keys( props );
+	const ks = Object.keys( props );
 	if ( ks.length < 1 ) {
 		return '';
 	}
@@ -156,7 +146,7 @@ const getStylePropertiesMarkup = ( struct ) => {
 	ks.forEach( ( key ) => {
 		const ps =
 			props[ key ].type === 'object'
-				? keys( props[ key ].properties ).sort().join( ', ' )
+				? Object.keys( props[ key ].properties ).sort().join( ', ' )
 				: '';
 		const type = formatType( props[ key ] );
 		markup += `| ${ key } | ${ type } | ${ ps } |\n`;
@@ -227,7 +217,7 @@ const settings = Object.entries( themejson.definitions )
 			Object.assign( settingsObj, properties ),
 		{}
 	);
-const settingSections = keys( settings );
+const settingSections = Object.keys( settings );
 autogen += '## Settings' + '\n\n';
 settingSections.forEach( ( section ) => {
 	autogen += getSectionMarkup( section, settings[ section ], 'settings' );
@@ -235,7 +225,7 @@ settingSections.forEach( ( section ) => {
 
 // Styles
 const styles = themejson.definitions.stylesProperties.properties;
-const styleSections = keys( styles );
+const styleSections = Object.keys( styles );
 autogen += '## Styles' + '\n\n';
 styleSections.forEach( ( section ) => {
 	autogen += getSectionMarkup( section, styles[ section ], 'styles' );
@@ -249,7 +239,7 @@ const templateTableGeneration = ( themeJson, context ) => {
 		'Type: `' + themeJson.properties[ context ].items.type + '`.\n\n';
 	content += '| Property | Description | Type |\n';
 	content += '| ---      | ---         | ---  |\n';
-	keys( themeJson.properties[ context ].items.properties ).forEach(
+	Object.keys( themeJson.properties[ context ].items.properties ).forEach(
 		( key ) => {
 			content += `| ${ key } | ${ themeJson.properties[ context ].items.properties[ key ].description } | ${ themeJson.properties[ context ].items.properties[ key ].type } |\n`;
 		}

From c7ebdd70ab899aa5e9c900cce4cd4c35c0a1fd40 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Mon, 15 Jul 2024 22:53:09 -0500
Subject: [PATCH 02/43] Update codegen to use entries

---
 bin/api-docs/gen-theme-reference.mjs | 26 ++++++++++----------------
 1 file changed, 10 insertions(+), 16 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 0373d6abfb4e1..fd558de734d63 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -208,27 +208,21 @@ const formatType = ( prop ) => {
 };
 
 // Settings
-const settings = Object.entries( themejson.definitions )
-	.filter( ( [ settingsKey ] ) =>
-		/^settings\w+Properties$/.test( settingsKey )
-	)
-	.reduce(
-		( settingsObj, [ , { properties } ] ) =>
-			Object.assign( settingsObj, properties ),
-		{}
-	);
-const settingSections = Object.keys( settings );
+const settings = themejson.definitions.settingsProperties.allOf.flatMap(
+	( settingsProperties ) => Object.entries( settingsProperties.properties )
+);
 autogen += '## Settings' + '\n\n';
-settingSections.forEach( ( section ) => {
-	autogen += getSectionMarkup( section, settings[ section ], 'settings' );
+settings.forEach( ( [ section, data ] ) => {
+	autogen += getSectionMarkup( section, data, 'settings' );
 } );
 
 // Styles
-const styles = themejson.definitions.stylesProperties.properties;
-const styleSections = Object.keys( styles );
+const styles = Object.entries(
+	themejson.definitions.stylesProperties.properties
+);
 autogen += '## Styles' + '\n\n';
-styleSections.forEach( ( section ) => {
-	autogen += getSectionMarkup( section, styles[ section ], 'styles' );
+styles.forEach( ( [ section, data ] ) => {
+	autogen += getSectionMarkup( section, data, 'styles' );
 } );
 
 const templateTableGeneration = ( themeJson, context ) => {

From 61bfde9387e6f7c431890f41fc68a7550c2d2b24 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Mon, 15 Jul 2024 23:27:04 -0500
Subject: [PATCH 03/43] Re-add useRootPaddingAwareAlignments to the docs

---
 bin/api-docs/gen-theme-reference.mjs                     | 6 ++++++
 .../theme-json-reference/theme-json-living.md            | 9 +++++++++
 2 files changed, 15 insertions(+)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index fd558de734d63..b654f22875a20 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -211,6 +211,12 @@ const formatType = ( prop ) => {
 const settings = themejson.definitions.settingsProperties.allOf.flatMap(
 	( settingsProperties ) => Object.entries( settingsProperties.properties )
 );
+// This property is only available at the root level, so it isn't included in the settingsProperties.
+settings.unshift( [
+	'useRootPaddingAwareAlignments',
+	themejson.properties.settings.allOf[ 1 ].properties
+		.useRootPaddingAwareAlignments,
+] );
 autogen += '## Settings' + '\n\n';
 settings.forEach( ( [ section, data ] ) => {
 	autogen += getSectionMarkup( section, data, 'settings' );
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index 0b9e3e9d18776..4f2482870a3ec 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -24,6 +24,15 @@ See [Developing with theme.json](/docs/how-to-guides/themes/global-settings-and-
 ## Settings
 
 
+### useRootPaddingAwareAlignments
+
+Enables root padding (the values from `styles.spacing.padding`) to be applied to the contents of full-width blocks instead of the root block.
+
+Please note that when using this setting, `styles.spacing.padding` should always be set as an object with `top`, `right`, `bottom`, `left` values declared separately.
+
+
+---
+
 ### appearanceTools
 
 Setting that enables the following UI tools:

From e73fddf7c31532cacae32b57d2281a54301642cf Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 10:02:18 -0500
Subject: [PATCH 04/43] Code readability for markup tables

---
 bin/api-docs/gen-theme-reference.mjs          | 10 ++--
 .../theme-json-reference/theme-json-living.md | 52 +++++++++----------
 2 files changed, 32 insertions(+), 30 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index b654f22875a20..0af086fed45d7 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -81,8 +81,9 @@ const getSettingsPropertiesMarkup = ( struct ) => {
 		return '';
 	}
 
-	let markup = '| Property  | Type   | Default | Props  |\n';
-	markup += '| ---    | ---    | ---    |---   |\n';
+	let markup = '';
+	markup += '| Property  | Type   | Default | Props  |\n';
+	markup += '| ---       | ---    | ---     | ---    |\n';
 	ks.forEach( ( key ) => {
 		const def = 'default' in props[ key ] ? props[ key ].default : '';
 		let type = props[ key ].type || '';
@@ -141,8 +142,9 @@ const getStylePropertiesMarkup = ( struct ) => {
 		return '';
 	}
 
-	let markup = '| Property  | Type   |  Props  |\n';
-	markup += '| ---       | ---    |---   |\n';
+	let markup = '';
+	markup += '| Property  | Type   | Props  |\n';
+	markup += '| ---       | ---    | ---    |\n';
 	ks.forEach( ( key ) => {
 		const ps =
 			props[ key ].type === 'object'
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index 4f2482870a3ec..9837faf82b679 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -53,7 +53,7 @@ Setting that enables the following UI tools:
 Settings related to background.
 
 | Property  | Type   | Default | Props  |
-| ---    | ---    | ---    |---   |
+| ---       | ---    | ---     | ---    |
 | backgroundImage | boolean | false |  |
 | backgroundSize | boolean | false |  |
 
@@ -64,7 +64,7 @@ Settings related to background.
 Settings related to borders.
 
 | Property  | Type   | Default | Props  |
-| ---    | ---    | ---    |---   |
+| ---       | ---    | ---     | ---    |
 | color | boolean | false |  |
 | radius | boolean | false |  |
 | style | boolean | false |  |
@@ -77,7 +77,7 @@ Settings related to borders.
 Settings related to colors.
 
 | Property  | Type   | Default | Props  |
-| ---    | ---    | ---    |---   |
+| ---       | ---    | ---     | ---    |
 | background | boolean | true |  |
 | custom | boolean | true |  |
 | customDuotone | boolean | true |  |
@@ -101,7 +101,7 @@ Settings related to colors.
 Settings related to dimensions.
 
 | Property  | Type   | Default | Props  |
-| ---    | ---    | ---    |---   |
+| ---       | ---    | ---     | ---    |
 | aspectRatio | boolean | false |  |
 | defaultAspectRatios | boolean | true |  |
 | aspectRatios | array |  | name, ratio, slug |
@@ -114,7 +114,7 @@ Settings related to dimensions.
 Settings related to layout.
 
 | Property  | Type   | Default | Props  |
-| ---    | ---    | ---    |---   |
+| ---       | ---    | ---     | ---    |
 | contentSize | string |  |  |
 | wideSize | string |  |  |
 | allowEditing | boolean | true |  |
@@ -127,7 +127,7 @@ Settings related to layout.
 Settings related to the lightbox.
 
 | Property  | Type   | Default | Props  |
-| ---    | ---    | ---    |---   |
+| ---       | ---    | ---     | ---    |
 | enabled | boolean |  |  |
 | allowEditing | boolean |  |  |
 
@@ -138,7 +138,7 @@ Settings related to the lightbox.
 Settings related to position.
 
 | Property  | Type   | Default | Props  |
-| ---    | ---    | ---    |---   |
+| ---       | ---    | ---     | ---    |
 | sticky | boolean | false |  |
 
 ---
@@ -148,7 +148,7 @@ Settings related to position.
 Settings related to shadows.
 
 | Property  | Type   | Default | Props  |
-| ---    | ---    | ---    |---   |
+| ---       | ---    | ---     | ---    |
 | defaultPresets | boolean | true |  |
 | presets | array |  | name, shadow, slug |
 
@@ -159,7 +159,7 @@ Settings related to shadows.
 Settings related to spacing.
 
 | Property  | Type   | Default | Props  |
-| ---    | ---    | ---    |---   |
+| ---       | ---    | ---     | ---    |
 | blockGap | boolean, null | null |   |
 | margin | boolean | false |  |
 | padding | boolean | false |  |
@@ -176,7 +176,7 @@ Settings related to spacing.
 Settings related to typography.
 
 | Property  | Type   | Default | Props  |
-| ---    | ---    | ---    |---   |
+| ---       | ---    | ---     | ---    |
 | defaultFontSizes | boolean | true |  |
 | customFontSize | boolean | true |  |
 | fontStyle | boolean | true |  |
@@ -208,8 +208,8 @@ Generate custom CSS custom properties of the form `--wp--custom--{key}--{nested-
 
 Background styles.
 
-| Property  | Type   |  Props  |
-| ---       | ---    |---   |
+| Property  | Type   | Props  |
+| ---       | ---    | ---    |
 | backgroundImage | string, object |  |
 | backgroundPosition | string, object |  |
 | backgroundRepeat | string, object |  |
@@ -222,8 +222,8 @@ Background styles.
 
 Border styles.
 
-| Property  | Type   |  Props  |
-| ---       | ---    |---   |
+| Property  | Type   | Props  |
+| ---       | ---    | ---    |
 | color | string, object |  |
 | radius | string, object |  |
 | style | string, object |  |
@@ -239,8 +239,8 @@ Border styles.
 
 Color styles.
 
-| Property  | Type   |  Props  |
-| ---       | ---    |---   |
+| Property  | Type   | Props  |
+| ---       | ---    | ---    |
 | background | string, object |  |
 | gradient | string, object |  |
 | text | string, object |  |
@@ -258,8 +258,8 @@ Sets custom CSS to apply styling not covered by other theme.json properties.
 
 Dimensions styles.
 
-| Property  | Type   |  Props  |
-| ---       | ---    |---   |
+| Property  | Type   | Props  |
+| ---       | ---    | ---    |
 | aspectRatio | string, object |  |
 | minHeight | string, object |  |
 
@@ -269,8 +269,8 @@ Dimensions styles.
 
 CSS and SVG filter styles.
 
-| Property  | Type   |  Props  |
-| ---       | ---    |---   |
+| Property  | Type   | Props  |
+| ---       | ---    | ---    |
 | duotone | string, object |  |
 
 ---
@@ -279,8 +279,8 @@ CSS and SVG filter styles.
 
 Outline styles.
 
-| Property  | Type   |  Props  |
-| ---       | ---    |---   |
+| Property  | Type   | Props  |
+| ---       | ---    | ---    |
 | color | string, object |  |
 | offset | string, object |  |
 | style | string, object |  |
@@ -299,8 +299,8 @@ Box shadow styles.
 
 Spacing styles.
 
-| Property  | Type   |  Props  |
-| ---       | ---    |---   |
+| Property  | Type   | Props  |
+| ---       | ---    | ---    |
 | blockGap | string, object |  |
 | margin | object | bottom, left, right, top |
 | padding | object | bottom, left, right, top |
@@ -311,8 +311,8 @@ Spacing styles.
 
 Typography styles.
 
-| Property  | Type   |  Props  |
-| ---       | ---    |---   |
+| Property  | Type   | Props  |
+| ---       | ---    | ---    |
 | fontFamily | string, object |  |
 | fontSize | string, object |  |
 | fontStyle | string, object |  |

From af38a4b1256e617c59f6f923d55d05e069e80a0e Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 12:51:34 -0500
Subject: [PATCH 05/43] Simplify file paths

---
 bin/api-docs/gen-theme-reference.mjs | 37 +++++++---------------------
 1 file changed, 9 insertions(+), 28 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 0af086fed45d7..a27e12aea669c 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -7,38 +7,17 @@
 /**
  * External dependencies
  */
-import path from 'path';
 import fs from 'fs';
-import url from 'url';
 import $RefParser from '@apidevtools/json-schema-ref-parser';
 
-const __dirname = path.dirname( url.fileURLToPath( import.meta.url ) );
-
-/**
- * Path to root project directory.
- *
- * @type {string}
- */
-const ROOT_DIR = path.resolve( __dirname, '../..' );
-
-/**
- * Path to theme json schema file.
- *
- * @type {string}
- */
-const THEME_JSON_SCHEMA_FILE = path.resolve(
-	ROOT_DIR,
-	path.join( 'schemas', 'json', 'theme.json' )
+const THEME_JSON_SCHEMA_FILE = new URL(
+	'../../schemas/json/theme.json',
+	import.meta.url
 );
 
-/**
- * Path to docs file.
- *
- * @type {string}
- */
-const THEME_JSON_REF_DOC = path.resolve(
-	ROOT_DIR,
-	'docs/reference-guides/theme-json-reference/theme-json-living.md'
+const THEME_JSON_REF_DOC = new URL(
+	'../../docs/reference-guides/theme-json-reference/theme-json-living.md',
+	import.meta.url
 );
 
 /**
@@ -63,7 +42,9 @@ const END_TOKEN = '<!-- END TOKEN Autogenerated - DO NOT EDIT -->';
  */
 const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );
 
-const themejson = await $RefParser.dereference( THEME_JSON_SCHEMA_FILE );
+const themejson = await $RefParser.dereference(
+	THEME_JSON_SCHEMA_FILE.pathname
+);
 
 /**
  * Convert settings properties to markup.

From fff1469bca56286c221ab47e6053b309decb18fa Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 12:52:44 -0500
Subject: [PATCH 06/43] Re-add doc comments

---
 bin/api-docs/gen-theme-reference.mjs | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index a27e12aea669c..05f7f152dca5b 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -10,11 +10,21 @@
 import fs from 'fs';
 import $RefParser from '@apidevtools/json-schema-ref-parser';
 
+/**
+ * Path to root project directory.
+ *
+ * @type {URL}
+ */
 const THEME_JSON_SCHEMA_FILE = new URL(
 	'../../schemas/json/theme.json',
 	import.meta.url
 );
 
+/**
+ * Path to theme json schema file.
+ *
+ * @type {URL}
+ */
 const THEME_JSON_REF_DOC = new URL(
 	'../../docs/reference-guides/theme-json-reference/theme-json-living.md',
 	import.meta.url

From dc89267066f2f641346b6d5bc5e540452915414a Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 12:57:27 -0500
Subject: [PATCH 07/43] Add dereference options

---
 bin/api-docs/gen-theme-reference.mjs | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 05f7f152dca5b..47158229eb722 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -53,7 +53,11 @@ const END_TOKEN = '<!-- END TOKEN Autogenerated - DO NOT EDIT -->';
 const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );
 
 const themejson = await $RefParser.dereference(
-	THEME_JSON_SCHEMA_FILE.pathname
+	THEME_JSON_SCHEMA_FILE.pathname,
+	{
+		parse: { binary: false, text: false, yaml: false },
+		resolve: { external: false },
+	}
 );
 
 /**

From 8be8599b9eecccd391608e06c605a4a9aeef4591 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 13:04:09 -0500
Subject: [PATCH 08/43] Fix doc comments

---
 bin/api-docs/gen-theme-reference.mjs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 47158229eb722..1ea01354be2d5 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -11,7 +11,7 @@ import fs from 'fs';
 import $RefParser from '@apidevtools/json-schema-ref-parser';
 
 /**
- * Path to root project directory.
+ * Path to theme json schema file.
  *
  * @type {URL}
  */
@@ -21,7 +21,7 @@ const THEME_JSON_SCHEMA_FILE = new URL(
 );
 
 /**
- * Path to theme json schema file.
+ * Path to docs file.
  *
  * @type {URL}
  */

From 8df7fa3830d9c664bce7b10b893543dce8182c46 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 15:52:34 -0500
Subject: [PATCH 09/43] Refactor properties markup functions

---
 bin/api-docs/gen-theme-reference.mjs          | 62 +++++++------------
 .../theme-json-reference/theme-json-living.md | 24 +++----
 2 files changed, 36 insertions(+), 50 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 1ea01354be2d5..ad13fc2ffe961 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -64,50 +64,41 @@ const themejson = await $RefParser.dereference(
  * Convert settings properties to markup.
  *
  * @param {Object} struct
+ * @param {Object} struct.properties
  * @return {string} markup
  */
-const getSettingsPropertiesMarkup = ( struct ) => {
-	if ( ! ( 'properties' in struct ) ) {
-		return '';
-	}
-	const props = struct.properties;
-	const ks = Object.keys( props );
-	if ( ks.length < 1 ) {
+const getSettingsPropertiesMarkup = ( { properties } ) => {
+	if ( ! properties || typeof properties !== 'object' ) {
 		return '';
 	}
 
 	let markup = '';
 	markup += '| Property  | Type   | Default | Props  |\n';
 	markup += '| ---       | ---    | ---     | ---    |\n';
-	ks.forEach( ( key ) => {
-		const def = 'default' in props[ key ] ? props[ key ].default : '';
-		let type = props[ key ].type || '';
-		let ps =
-			props[ key ].type === 'array'
-				? Object.keys( props[ key ].items?.properties ?? {} )
-						.sort()
-						.join( ', ' )
-				: '';
+	Object.entries( properties ).forEach( ( [ property, subschema ] ) => {
+		const defaultValue = subschema.default ?? '';
+		let type = subschema.type ?? '';
+		let props = subschema.items?.properties
+			? Object.keys( subschema.items.properties ).join( ', ' )
+			: '';
 
 		/*
 		 * Handle`oneOf` type definitions - extract the type and properties.
 		 * See: https://json-schema.org/understanding-json-schema/reference/combining#oneOf
 		 */
-		if ( props[ key ].oneOf && Array.isArray( props[ key ].oneOf ) ) {
+		if ( Array.isArray( subschema.oneOf ) ) {
 			if ( ! type ) {
-				type = props[ key ].oneOf
+				type = subschema.oneOf
 					.map( ( item ) => item.type )
 					.join( ', ' );
 			}
 
-			if ( ! ps ) {
-				ps = props[ key ].oneOf
+			if ( ! props ) {
+				props = subschema.oneOf
 					.map( ( item ) =>
 						item?.type === 'object' && item?.properties
 							? '_{' +
-							  Object.keys( item.properties )
-									.sort()
-									.join( ', ' ) +
+							  Object.keys( item.properties ).join( ', ' ) +
 							  '}_'
 							: ''
 					)
@@ -115,7 +106,7 @@ const getSettingsPropertiesMarkup = ( struct ) => {
 			}
 		}
 
-		markup += `| ${ key } | ${ type } | ${ def } | ${ ps } |\n`;
+		markup += `| ${ property } | ${ type } | ${ defaultValue } | ${ props } |\n`;
 	} );
 
 	return markup;
@@ -125,28 +116,23 @@ const getSettingsPropertiesMarkup = ( struct ) => {
  * Convert style properties to markup.
  *
  * @param {Object} struct
+ * @param {Object} struct.properties
  * @return {string} markup
  */
-const getStylePropertiesMarkup = ( struct ) => {
-	if ( ! ( 'properties' in struct ) ) {
-		return '';
-	}
-	const props = struct.properties;
-	const ks = Object.keys( props );
-	if ( ks.length < 1 ) {
+const getStylePropertiesMarkup = ( { properties } ) => {
+	if ( ! properties || typeof properties !== 'object' ) {
 		return '';
 	}
 
 	let markup = '';
 	markup += '| Property  | Type   | Props  |\n';
 	markup += '| ---       | ---    | ---    |\n';
-	ks.forEach( ( key ) => {
-		const ps =
-			props[ key ].type === 'object'
-				? Object.keys( props[ key ].properties ).sort().join( ', ' )
-				: '';
-		const type = formatType( props[ key ] );
-		markup += `| ${ key } | ${ type } | ${ ps } |\n`;
+	Object.entries( properties ).forEach( ( [ property, subschema ] ) => {
+		const props = subschema.properties
+			? Object.keys( subschema.properties ).join( ', ' )
+			: '';
+		const type = formatType( subschema );
+		markup += `| ${ property } | ${ type } | ${ props } |\n`;
 	} );
 
 	return markup;
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index 9837faf82b679..b96e9f1e02a0d 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -85,10 +85,10 @@ Settings related to colors.
 | defaultDuotone | boolean | true |  |
 | defaultGradients | boolean | true |  |
 | defaultPalette | boolean | true |  |
-| duotone | array |  | colors, name, slug |
-| gradients | array |  | gradient, name, slug |
+| duotone | array |  | name, slug, colors |
+| gradients | array |  | name, slug, gradient |
 | link | boolean | false |  |
-| palette | array |  | color, name, slug |
+| palette | array |  | name, slug, color |
 | text | boolean | true |  |
 | heading | boolean | true |  |
 | button | boolean | true |  |
@@ -104,7 +104,7 @@ Settings related to dimensions.
 | ---       | ---    | ---     | ---    |
 | aspectRatio | boolean | false |  |
 | defaultAspectRatios | boolean | true |  |
-| aspectRatios | array |  | name, ratio, slug |
+| aspectRatios | array |  | name, slug, ratio |
 | minHeight | boolean | false |  |
 
 ---
@@ -150,7 +150,7 @@ Settings related to shadows.
 | Property  | Type   | Default | Props  |
 | ---       | ---    | ---     | ---    |
 | defaultPresets | boolean | true |  |
-| presets | array |  | name, shadow, slug |
+| presets | array |  | name, slug, shadow |
 
 ---
 
@@ -160,13 +160,13 @@ Settings related to spacing.
 
 | Property  | Type   | Default | Props  |
 | ---       | ---    | ---     | ---    |
-| blockGap | boolean, null | null |   |
+| blockGap | boolean, null |  |   |
 | margin | boolean | false |  |
 | padding | boolean | false |  |
 | units | array | px,em,rem,vh,vw,% |  |
 | customSpacingSize | boolean | true |  |
 | defaultSpacingSizes | boolean | true |  |
-| spacingSizes | array |  | name, size, slug |
+| spacingSizes | array |  | name, slug, size |
 | spacingScale | object |  |  |
 
 ---
@@ -181,7 +181,7 @@ Settings related to typography.
 | customFontSize | boolean | true |  |
 | fontStyle | boolean | true |  |
 | fontWeight | boolean | true |  |
-| fluid | object, boolean | false | _{maxViewportWidth, minFontSize, minViewportWidth}_  |
+| fluid | object, boolean | false | _{minFontSize, maxViewportWidth, minViewportWidth}_  |
 | letterSpacing | boolean | true |  |
 | lineHeight | boolean | false |  |
 | textAlign | boolean | true |  |
@@ -190,8 +190,8 @@ Settings related to typography.
 | writingMode | boolean | false |  |
 | textTransform | boolean | true |  |
 | dropCap | boolean | true |  |
-| fontSizes | array |  | fluid, name, size, slug |
-| fontFamilies | array |  | fontFace, fontFamily, name, slug |
+| fontSizes | array |  | name, slug, size, fluid |
+| fontFamilies | array |  | name, slug, fontFamily, fontFace |
 
 ---
 
@@ -302,8 +302,8 @@ Spacing styles.
 | Property  | Type   | Props  |
 | ---       | ---    | ---    |
 | blockGap | string, object |  |
-| margin | object | bottom, left, right, top |
-| padding | object | bottom, left, right, top |
+| margin | object | top, right, bottom, left |
+| padding | object | top, right, bottom, left |
 
 ---
 

From d7214b4e92b4d1c4591579a1a9d3440eb19e8b50 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 15:59:34 -0500
Subject: [PATCH 10/43] Use import JSONSchema type

---
 bin/api-docs/gen-theme-reference.mjs | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index ad13fc2ffe961..e6726a1b70a0a 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -10,6 +10,10 @@
 import fs from 'fs';
 import $RefParser from '@apidevtools/json-schema-ref-parser';
 
+/**
+ * @typedef {import('@apidevtools/json-schema-ref-parser').JSONSchema} JSONSchema
+ */
+
 /**
  * Path to theme json schema file.
  *
@@ -52,6 +56,11 @@ const END_TOKEN = '<!-- END TOKEN Autogenerated - DO NOT EDIT -->';
  */
 const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );
 
+/**
+ * Dereferenced theme.json schema.
+ *
+ * @type {JSONSchema}
+ */
 const themejson = await $RefParser.dereference(
 	THEME_JSON_SCHEMA_FILE.pathname,
 	{
@@ -63,8 +72,7 @@ const themejson = await $RefParser.dereference(
 /**
  * Convert settings properties to markup.
  *
- * @param {Object} struct
- * @param {Object} struct.properties
+ * @param {JSONSchema} schema
  * @return {string} markup
  */
 const getSettingsPropertiesMarkup = ( { properties } ) => {
@@ -115,8 +123,7 @@ const getSettingsPropertiesMarkup = ( { properties } ) => {
 /**
  * Convert style properties to markup.
  *
- * @param {Object} struct
- * @param {Object} struct.properties
+ * @param {JSONSchema} schema
  * @return {string} markup
  */
 const getStylePropertiesMarkup = ( { properties } ) => {

From d002425b275a7660dd61ca2a026dbcc15a872cec Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 16:09:04 -0500
Subject: [PATCH 11/43] Simplify getSectionMarkup

---
 bin/api-docs/gen-theme-reference.mjs | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index e6726a1b70a0a..cf76ca1e5e27c 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -149,17 +149,12 @@ const getStylePropertiesMarkup = ( { properties } ) => {
  * Parses a section for description and properties and
  * returns a marked up version.
  *
- * @param {string} title
- * @param {Object} data
- * @param {string} type  settings|style
+ * @param {string}   title
+ * @param {Object}   data
+ * @param {Function} markupFn
  * @return {string} markup
  */
-const getSectionMarkup = ( title, data, type ) => {
-	const markupFn =
-		type === 'settings'
-			? getSettingsPropertiesMarkup
-			: getStylePropertiesMarkup;
-
+const getSectionMarkup = ( title, data, markupFn ) => {
 	return `
 ### ${ title }
 
@@ -209,7 +204,7 @@ settings.unshift( [
 ] );
 autogen += '## Settings' + '\n\n';
 settings.forEach( ( [ section, data ] ) => {
-	autogen += getSectionMarkup( section, data, 'settings' );
+	autogen += getSectionMarkup( section, data, getSettingsPropertiesMarkup );
 } );
 
 // Styles
@@ -218,7 +213,7 @@ const styles = Object.entries(
 );
 autogen += '## Styles' + '\n\n';
 styles.forEach( ( [ section, data ] ) => {
-	autogen += getSectionMarkup( section, data, 'styles' );
+	autogen += getSectionMarkup( section, data, getStylePropertiesMarkup );
 } );
 
 const templateTableGeneration = ( themeJson, context ) => {

From 1342fb6a583136c9dc9ffb49f5188eae6677e040 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 16:18:48 -0500
Subject: [PATCH 12/43] Fix spacing

---
 bin/api-docs/gen-theme-reference.mjs          | 42 +++++++------------
 .../theme-json-reference/theme-json-living.md |  9 +---
 2 files changed, 16 insertions(+), 35 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index cf76ca1e5e27c..9af4e47405a6d 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -117,7 +117,7 @@ const getSettingsPropertiesMarkup = ( { properties } ) => {
 		markup += `| ${ property } | ${ type } | ${ defaultValue } | ${ props } |\n`;
 	} );
 
-	return markup;
+	return markup + '\n';
 };
 
 /**
@@ -142,31 +142,9 @@ const getStylePropertiesMarkup = ( { properties } ) => {
 		markup += `| ${ property } | ${ type } | ${ props } |\n`;
 	} );
 
-	return markup;
+	return markup + '\n';
 };
 
-/**
- * Parses a section for description and properties and
- * returns a marked up version.
- *
- * @param {string}   title
- * @param {Object}   data
- * @param {Function} markupFn
- * @return {string} markup
- */
-const getSectionMarkup = ( title, data, markupFn ) => {
-	return `
-### ${ title }
-
-${ data.description }
-
-${ markupFn( data ) }
----
-`;
-};
-
-let autogen = '';
-
 /**
  * Format list of types.
  *
@@ -192,6 +170,8 @@ const formatType = ( prop ) => {
 	return type;
 };
 
+let autogen = '';
+
 // Settings
 const settings = themejson.definitions.settingsProperties.allOf.flatMap(
 	( settingsProperties ) => Object.entries( settingsProperties.properties )
@@ -202,18 +182,24 @@ settings.unshift( [
 	themejson.properties.settings.allOf[ 1 ].properties
 		.useRootPaddingAwareAlignments,
 ] );
-autogen += '## Settings' + '\n\n';
+autogen += '## Settings\n\n';
 settings.forEach( ( [ section, data ] ) => {
-	autogen += getSectionMarkup( section, data, getSettingsPropertiesMarkup );
+	autogen += `### ${ section }\n\n`;
+	autogen += `${ data.description }\n\n`;
+	autogen += getSettingsPropertiesMarkup( data );
+	autogen += `---\n\n`;
 } );
 
 // Styles
 const styles = Object.entries(
 	themejson.definitions.stylesProperties.properties
 );
-autogen += '## Styles' + '\n\n';
+autogen += '## Styles\n\n';
 styles.forEach( ( [ section, data ] ) => {
-	autogen += getSectionMarkup( section, data, getStylePropertiesMarkup );
+	autogen += `### ${ section }\n\n`;
+	autogen += `${ data.description }\n\n`;
+	autogen += getStylePropertiesMarkup( data );
+	autogen += `---\n\n`;
 } );
 
 const templateTableGeneration = ( themeJson, context ) => {
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index b96e9f1e02a0d..82fdcca2ef8b7 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -23,14 +23,12 @@ See [Developing with theme.json](/docs/how-to-guides/themes/global-settings-and-
 <!-- START TOKEN Autogenerated - DO NOT EDIT -->
 ## Settings
 
-
 ### useRootPaddingAwareAlignments
 
 Enables root padding (the values from `styles.spacing.padding`) to be applied to the contents of full-width blocks instead of the root block.
 
 Please note that when using this setting, `styles.spacing.padding` should always be set as an object with `top`, `right`, `bottom`, `left` values declared separately.
 
-
 ---
 
 ### appearanceTools
@@ -45,7 +43,6 @@ Setting that enables the following UI tools:
 - spacing: blockGap, margin, padding
 - typography: lineHeight
 
-
 ---
 
 ### background
@@ -199,10 +196,9 @@ Settings related to typography.
 
 Generate custom CSS custom properties of the form `--wp--custom--{key}--{nested-key}: {value};`. `camelCased` keys are transformed to `kebab-case` as to follow the CSS property naming schema. Keys at different depth levels are separated by `--`, so keys should not include `--` in the name.
 
-
 ---
-## Styles
 
+## Styles
 
 ### background
 
@@ -251,7 +247,6 @@ Color styles.
 
 Sets custom CSS to apply styling not covered by other theme.json properties.
 
-
 ---
 
 ### dimensions
@@ -292,7 +287,6 @@ Outline styles.
 
 Box shadow styles.
 
-
 ---
 
 ### spacing
@@ -326,6 +320,7 @@ Typography styles.
 | textTransform | string, object |  |
 
 ---
+
 ## customTemplates
 
 Additional metadata for custom templates defined in the templates folder.

From 83406e2eac3e625a61106947515b107b0921e580 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 16:20:20 -0500
Subject: [PATCH 13/43] Convert arrow functions to functions

---
 bin/api-docs/gen-theme-reference.mjs | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 9af4e47405a6d..fd543cf6ca9e6 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -75,7 +75,7 @@ const themejson = await $RefParser.dereference(
  * @param {JSONSchema} schema
  * @return {string} markup
  */
-const getSettingsPropertiesMarkup = ( { properties } ) => {
+function getSettingsPropertiesMarkup( { properties } ) {
 	if ( ! properties || typeof properties !== 'object' ) {
 		return '';
 	}
@@ -118,7 +118,7 @@ const getSettingsPropertiesMarkup = ( { properties } ) => {
 	} );
 
 	return markup + '\n';
-};
+}
 
 /**
  * Convert style properties to markup.
@@ -126,7 +126,7 @@ const getSettingsPropertiesMarkup = ( { properties } ) => {
  * @param {JSONSchema} schema
  * @return {string} markup
  */
-const getStylePropertiesMarkup = ( { properties } ) => {
+function getStylePropertiesMarkup( { properties } ) {
 	if ( ! properties || typeof properties !== 'object' ) {
 		return '';
 	}
@@ -143,7 +143,7 @@ const getStylePropertiesMarkup = ( { properties } ) => {
 	} );
 
 	return markup + '\n';
-};
+}
 
 /**
  * Format list of types.
@@ -151,7 +151,7 @@ const getStylePropertiesMarkup = ( { properties } ) => {
  * @param {Object} prop
  * @return {string} type
  */
-const formatType = ( prop ) => {
+function formatType( prop ) {
 	let type = prop.type || '';
 
 	if ( prop.hasOwnProperty( 'anyOf' ) || prop.hasOwnProperty( 'oneOf' ) ) {
@@ -168,7 +168,7 @@ const formatType = ( prop ) => {
 	}
 
 	return type;
-};
+}
 
 let autogen = '';
 
@@ -202,7 +202,7 @@ styles.forEach( ( [ section, data ] ) => {
 	autogen += `---\n\n`;
 } );
 
-const templateTableGeneration = ( themeJson, context ) => {
+function templateTableGeneration( themeJson, context ) {
 	let content = '';
 	content += '## ' + context + '\n\n';
 	content += themeJson.properties[ context ].description + '\n\n';
@@ -218,7 +218,7 @@ const templateTableGeneration = ( themeJson, context ) => {
 	content += '\n\n';
 
 	return content;
-};
+}
 
 // customTemplates
 autogen += templateTableGeneration( themejson, 'customTemplates' );

From 84dbcae381556c650e2b31616dbecf7b9dd21db1 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 16:33:34 -0500
Subject: [PATCH 14/43] Update template and template part autogen

---
 bin/api-docs/gen-theme-reference.mjs          | 53 ++++++++++++-------
 .../theme-json-reference/theme-json-living.md |  2 -
 2 files changed, 33 insertions(+), 22 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index fd543cf6ca9e6..b0b08f7f78d14 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -145,6 +145,27 @@ function getStylePropertiesMarkup( { properties } ) {
 	return markup + '\n';
 }
 
+/**
+ * Convert template properties to markup.
+ *
+ * @param {JSONSchema} schema
+ * @return {string} markup
+ */
+function getTemplatePropertiesMarkup( { properties } ) {
+	if ( ! properties || typeof properties !== 'object' ) {
+		return '';
+	}
+
+	let markup = '';
+	markup += '| Property | Description | Type |\n';
+	markup += '| ---      | ---         | ---  |\n';
+	Object.entries( properties ).forEach( ( [ property, subschema ] ) => {
+		const { description, type } = subschema;
+		markup += `| ${ property } | ${ description } | ${ type } |\n`;
+	} );
+	return markup + '\n';
+}
+
 /**
  * Format list of types.
  *
@@ -202,29 +223,21 @@ styles.forEach( ( [ section, data ] ) => {
 	autogen += `---\n\n`;
 } );
 
-function templateTableGeneration( themeJson, context ) {
-	let content = '';
-	content += '## ' + context + '\n\n';
-	content += themeJson.properties[ context ].description + '\n\n';
-	content +=
-		'Type: `' + themeJson.properties[ context ].items.type + '`.\n\n';
-	content += '| Property | Description | Type |\n';
-	content += '| ---      | ---         | ---  |\n';
-	Object.keys( themeJson.properties[ context ].items.properties ).forEach(
-		( key ) => {
-			content += `| ${ key } | ${ themeJson.properties[ context ].items.properties[ key ].description } | ${ themeJson.properties[ context ].items.properties[ key ].type } |\n`;
-		}
-	);
-	content += '\n\n';
-
-	return content;
-}
-
 // customTemplates
-autogen += templateTableGeneration( themejson, 'customTemplates' );
+autogen += '## customTemplates\n\n';
+autogen += `${ themejson.properties.customTemplates.description }\n\n`;
+autogen += `Type: \`${ themejson.properties.customTemplates.items.type }\`.\n\n`;
+autogen += getTemplatePropertiesMarkup(
+	themejson.properties.customTemplates.items
+);
 
 // templateParts
-autogen += templateTableGeneration( themejson, 'templateParts' );
+autogen += '## templateParts\n\n';
+autogen += `${ themejson.properties.templateParts.description }\n\n`;
+autogen += `Type: \`${ themejson.properties.templateParts.items.type }\`.\n\n`;
+autogen += getTemplatePropertiesMarkup(
+	themejson.properties.templateParts.items
+);
 
 // Patterns
 autogen += '## Patterns' + '\n\n';
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index 82fdcca2ef8b7..eb39394f210f5 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -333,7 +333,6 @@ Type: `object`.
 | title | Title of the template, translatable. | string |
 | postTypes | List of post types that can use this custom template. | array |
 
-
 ## templateParts
 
 Additional metadata for template parts defined in the parts folder.
@@ -346,7 +345,6 @@ Type: `object`.
 | title | Title of the template, translatable. | string |
 | area | The area the template part is used for. Block variations for `header` and `footer` values exist and will be used when the area is set to one of those. | string |
 
-
 ## Patterns
 
 An array of pattern slugs to be registered from the Pattern Directory.

From 5bc5f39839ef61567c6591e3933d3e2c9b12b832 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 16:34:10 -0500
Subject: [PATCH 15/43] Fix capitalization for patterns property

---
 bin/api-docs/gen-theme-reference.mjs                            | 2 +-
 docs/reference-guides/theme-json-reference/theme-json-living.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index b0b08f7f78d14..f25f3d52c0c11 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -240,7 +240,7 @@ autogen += getTemplatePropertiesMarkup(
 );
 
 // Patterns
-autogen += '## Patterns' + '\n\n';
+autogen += '## patterns' + '\n\n';
 autogen += themejson.properties.patterns.description + '\n';
 autogen += 'Type: `' + themejson.properties.patterns.type + '`.\n\n';
 
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index eb39394f210f5..a83f9047b87ae 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -345,7 +345,7 @@ Type: `object`.
 | title | Title of the template, translatable. | string |
 | area | The area the template part is used for. Block variations for `header` and `footer` values exist and will be used when the area is set to one of those. | string |
 
-## Patterns
+## patterns
 
 An array of pattern slugs to be registered from the Pattern Directory.
 Type: `array`.

From 649a37c711ebb30c2ef694c2c17478932bf31039 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 16:39:19 -0500
Subject: [PATCH 16/43] Wrap autogen in main function

---
 bin/api-docs/gen-theme-reference.mjs | 150 ++++++++++++++-------------
 1 file changed, 78 insertions(+), 72 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index f25f3d52c0c11..6666e6a1cf059 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -56,19 +56,6 @@ const END_TOKEN = '<!-- END TOKEN Autogenerated - DO NOT EDIT -->';
  */
 const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );
 
-/**
- * Dereferenced theme.json schema.
- *
- * @type {JSONSchema}
- */
-const themejson = await $RefParser.dereference(
-	THEME_JSON_SCHEMA_FILE.pathname,
-	{
-		parse: { binary: false, text: false, yaml: false },
-		resolve: { external: false },
-	}
-);
-
 /**
  * Convert settings properties to markup.
  *
@@ -191,68 +178,87 @@ function formatType( prop ) {
 	return type;
 }
 
-let autogen = '';
-
-// Settings
-const settings = themejson.definitions.settingsProperties.allOf.flatMap(
-	( settingsProperties ) => Object.entries( settingsProperties.properties )
-);
-// This property is only available at the root level, so it isn't included in the settingsProperties.
-settings.unshift( [
-	'useRootPaddingAwareAlignments',
-	themejson.properties.settings.allOf[ 1 ].properties
-		.useRootPaddingAwareAlignments,
-] );
-autogen += '## Settings\n\n';
-settings.forEach( ( [ section, data ] ) => {
-	autogen += `### ${ section }\n\n`;
-	autogen += `${ data.description }\n\n`;
-	autogen += getSettingsPropertiesMarkup( data );
-	autogen += `---\n\n`;
-} );
+/**
+ * Main function.
+ */
+async function main() {
+	const themejson = await $RefParser.dereference(
+		THEME_JSON_SCHEMA_FILE.pathname,
+		{
+			parse: { binary: false, text: false, yaml: false },
+			resolve: { external: false },
+		}
+	);
+
+	let autogen = '';
+
+	// Settings
+	const settings = themejson.definitions.settingsProperties.allOf.flatMap(
+		( settingsProperties ) =>
+			Object.entries( settingsProperties.properties )
+	);
+	// This property is only available at the root level, so it isn't included in the settingsProperties.
+	settings.unshift( [
+		'useRootPaddingAwareAlignments',
+		themejson.properties.settings.allOf[ 1 ].properties
+			.useRootPaddingAwareAlignments,
+	] );
+	autogen += '## Settings\n\n';
+	settings.forEach( ( [ section, data ] ) => {
+		autogen += `### ${ section }\n\n`;
+		autogen += `${ data.description }\n\n`;
+		autogen += getSettingsPropertiesMarkup( data );
+		autogen += `---\n\n`;
+	} );
 
-// Styles
-const styles = Object.entries(
-	themejson.definitions.stylesProperties.properties
-);
-autogen += '## Styles\n\n';
-styles.forEach( ( [ section, data ] ) => {
-	autogen += `### ${ section }\n\n`;
-	autogen += `${ data.description }\n\n`;
-	autogen += getStylePropertiesMarkup( data );
-	autogen += `---\n\n`;
-} );
+	// Styles
+	const styles = Object.entries(
+		themejson.definitions.stylesProperties.properties
+	);
+	autogen += '## Styles\n\n';
+	styles.forEach( ( [ section, data ] ) => {
+		autogen += `### ${ section }\n\n`;
+		autogen += `${ data.description }\n\n`;
+		autogen += getStylePropertiesMarkup( data );
+		autogen += `---\n\n`;
+	} );
 
-// customTemplates
-autogen += '## customTemplates\n\n';
-autogen += `${ themejson.properties.customTemplates.description }\n\n`;
-autogen += `Type: \`${ themejson.properties.customTemplates.items.type }\`.\n\n`;
-autogen += getTemplatePropertiesMarkup(
-	themejson.properties.customTemplates.items
-);
+	// customTemplates
+	autogen += '## customTemplates\n\n';
+	autogen += `${ themejson.properties.customTemplates.description }\n\n`;
+	autogen += `Type: \`${ themejson.properties.customTemplates.items.type }\`.\n\n`;
+	autogen += getTemplatePropertiesMarkup(
+		themejson.properties.customTemplates.items
+	);
+
+	// templateParts
+	autogen += '## templateParts\n\n';
+	autogen += `${ themejson.properties.templateParts.description }\n\n`;
+	autogen += `Type: \`${ themejson.properties.templateParts.items.type }\`.\n\n`;
+	autogen += getTemplatePropertiesMarkup(
+		themejson.properties.templateParts.items
+	);
+
+	// Patterns
+	autogen += '## patterns' + '\n\n';
+	autogen += themejson.properties.patterns.description + '\n';
+	autogen += 'Type: `' + themejson.properties.patterns.type + '`.\n\n';
+
+	// Read existing file to wrap auto generated content.
+	let docsContent = fs.readFileSync( THEME_JSON_REF_DOC, {
+		encoding: 'utf8',
+		flag: 'r',
+	} );
 
-// templateParts
-autogen += '## templateParts\n\n';
-autogen += `${ themejson.properties.templateParts.description }\n\n`;
-autogen += `Type: \`${ themejson.properties.templateParts.items.type }\`.\n\n`;
-autogen += getTemplatePropertiesMarkup(
-	themejson.properties.templateParts.items
-);
+	// Replace auto generated part with new generated docs.
+	autogen = START_TOKEN + '\n' + autogen + '\n' + END_TOKEN;
+	docsContent = docsContent.replace( TOKEN_PATTERN, autogen );
 
-// Patterns
-autogen += '## patterns' + '\n\n';
-autogen += themejson.properties.patterns.description + '\n';
-autogen += 'Type: `' + themejson.properties.patterns.type + '`.\n\n';
+	// Write back out.
+	fs.writeFileSync( THEME_JSON_REF_DOC, docsContent, { encoding: 'utf8' } );
+}
 
-// Read existing file to wrap auto generated content.
-let docsContent = fs.readFileSync( THEME_JSON_REF_DOC, {
-	encoding: 'utf8',
-	flag: 'r',
+main().catch( ( error ) => {
+	console.error( error );
+	process.exit( 1 );
 } );
-
-// Replace auto generated part with new generated docs.
-autogen = START_TOKEN + '\n' + autogen + '\n' + END_TOKEN;
-docsContent = docsContent.replace( TOKEN_PATTERN, autogen );
-
-// Write back out.
-fs.writeFileSync( THEME_JSON_REF_DOC, docsContent, { encoding: 'utf8' } );

From 6a1b4bbf59de345e06203cf76208bceb6916ca21 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 16:59:08 -0500
Subject: [PATCH 17/43] Use node:fs/promises

---
 bin/api-docs/gen-theme-reference.mjs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 6666e6a1cf059..ad45755e1243a 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -7,7 +7,7 @@
 /**
  * External dependencies
  */
-import fs from 'fs';
+import fs from 'node:fs/promises';
 import $RefParser from '@apidevtools/json-schema-ref-parser';
 
 /**
@@ -245,7 +245,7 @@ async function main() {
 	autogen += 'Type: `' + themejson.properties.patterns.type + '`.\n\n';
 
 	// Read existing file to wrap auto generated content.
-	let docsContent = fs.readFileSync( THEME_JSON_REF_DOC, {
+	let docsContent = await fs.readFile( THEME_JSON_REF_DOC, {
 		encoding: 'utf8',
 		flag: 'r',
 	} );
@@ -255,7 +255,7 @@ async function main() {
 	docsContent = docsContent.replace( TOKEN_PATTERN, autogen );
 
 	// Write back out.
-	fs.writeFileSync( THEME_JSON_REF_DOC, docsContent, { encoding: 'utf8' } );
+	await fs.writeFile( THEME_JSON_REF_DOC, docsContent, { encoding: 'utf8' } );
 }
 
 main().catch( ( error ) => {

From 60e8909ccb9b92cca19b3c040f917d11b8c316e7 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 16:59:24 -0500
Subject: [PATCH 18/43] Use for loops for imperative code

---
 bin/api-docs/gen-theme-reference.mjs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index ad45755e1243a..fb20a78990430 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -204,24 +204,24 @@ async function main() {
 			.useRootPaddingAwareAlignments,
 	] );
 	autogen += '## Settings\n\n';
-	settings.forEach( ( [ section, data ] ) => {
+	for ( const [ section, data ] of settings ) {
 		autogen += `### ${ section }\n\n`;
 		autogen += `${ data.description }\n\n`;
 		autogen += getSettingsPropertiesMarkup( data );
 		autogen += `---\n\n`;
-	} );
+	}
 
 	// Styles
 	const styles = Object.entries(
 		themejson.definitions.stylesProperties.properties
 	);
 	autogen += '## Styles\n\n';
-	styles.forEach( ( [ section, data ] ) => {
+	for ( const [ section, data ] of styles ) {
 		autogen += `### ${ section }\n\n`;
 		autogen += `${ data.description }\n\n`;
 		autogen += getStylePropertiesMarkup( data );
 		autogen += `---\n\n`;
-	} );
+	}
 
 	// customTemplates
 	autogen += '## customTemplates\n\n';

From bd4af6aac23160a4828e6d5b86eb7cc98ba29040 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 17:22:18 -0500
Subject: [PATCH 19/43] Simplify formatType

---
 bin/api-docs/gen-theme-reference.mjs | 25 ++++++++++---------------
 1 file changed, 10 insertions(+), 15 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index fb20a78990430..1f5dca1f2ee8a 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -156,26 +156,21 @@ function getTemplatePropertiesMarkup( { properties } ) {
 /**
  * Format list of types.
  *
- * @param {Object} prop
+ * @param {JSONSchema} schema
  * @return {string} type
  */
-function formatType( prop ) {
-	let type = prop.type || '';
-
-	if ( prop.hasOwnProperty( 'anyOf' ) || prop.hasOwnProperty( 'oneOf' ) ) {
-		const propTypes = prop.anyOf || prop.oneOf;
-		const types = [];
-
-		propTypes.forEach( ( item ) => {
-			if ( item.type ) {
-				types.push( item.type );
-			}
-		} );
+function formatType( schema ) {
+	if ( schema.type ) {
+		return schema.type;
+	}
 
-		type = [ ...new Set( types ) ].join( ', ' );
+	const subschemas = schema.anyOf || schema.oneOf;
+	if ( subschemas ) {
+		const types = subschemas.map( ( item ) => item.type ).filter( Boolean );
+		return [ ...new Set( types ) ].join( ', ' );
 	}
 
-	return type;
+	return '';
 }
 
 /**

From cc0b29eae94892f060eec549c499354ae32f1dbd Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 17:23:26 -0500
Subject: [PATCH 20/43] Simplify properties checks as we can assume a valid
 JSON schema

---
 bin/api-docs/gen-theme-reference.mjs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 1f5dca1f2ee8a..e578411e4889f 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -63,7 +63,7 @@ const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );
  * @return {string} markup
  */
 function getSettingsPropertiesMarkup( { properties } ) {
-	if ( ! properties || typeof properties !== 'object' ) {
+	if ( ! properties ) {
 		return '';
 	}
 
@@ -91,7 +91,7 @@ function getSettingsPropertiesMarkup( { properties } ) {
 			if ( ! props ) {
 				props = subschema.oneOf
 					.map( ( item ) =>
-						item?.type === 'object' && item?.properties
+						item.properties
 							? '_{' +
 							  Object.keys( item.properties ).join( ', ' ) +
 							  '}_'
@@ -114,7 +114,7 @@ function getSettingsPropertiesMarkup( { properties } ) {
  * @return {string} markup
  */
 function getStylePropertiesMarkup( { properties } ) {
-	if ( ! properties || typeof properties !== 'object' ) {
+	if ( ! properties ) {
 		return '';
 	}
 
@@ -139,7 +139,7 @@ function getStylePropertiesMarkup( { properties } ) {
  * @return {string} markup
  */
 function getTemplatePropertiesMarkup( { properties } ) {
-	if ( ! properties || typeof properties !== 'object' ) {
+	if ( ! properties ) {
 		return '';
 	}
 

From 1e0130572c34f2ffd2b542c319fd64b828406f1e Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 18:31:25 -0500
Subject: [PATCH 21/43] Simplify formatting of properties and types

---
 bin/api-docs/gen-theme-reference.mjs          | 115 ++++++++++--------
 .../theme-json-reference/theme-json-living.md |  96 +++++++--------
 2 files changed, 112 insertions(+), 99 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index e578411e4889f..eedfadf2c2ef5 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -56,6 +56,66 @@ const END_TOKEN = '<!-- END TOKEN Autogenerated - DO NOT EDIT -->';
  */
 const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );
 
+/**
+ * @typedef {(schema: JSONSchema) => boolean} PredicateFunction
+ */
+
+/**
+ * @typedef {(schema: JSONSchema) => string} SerializerFunction
+ */
+
+/**
+ * Serialize a schema that may use `anyOf` or `oneOf`.
+ *
+ * @see {@link https://json-schema.org/understanding-json-schema/reference/combining.html}
+ *
+ * @param {PredicateFunction}  predicate
+ * @param {SerializerFunction} serializer
+ * @param {JSONSchema}         schema
+ * @return {string} flattened schema
+ */
+function serialize( predicate, serializer, schema ) {
+	const schemas = predicate( schema )
+		? [ schema ]
+		: schema.anyOf || schema.oneOf || [];
+	const formatted = schemas.filter( predicate ).map( serializer );
+	return [ ...new Set( formatted ) ].join( ', ' );
+}
+
+/**
+ * Format list of types.
+ *
+ * @type {SerializerFunction}
+ */
+const formatType = serialize.bind(
+	null,
+	( schema ) => schema.type,
+	( schema ) => schema.type
+);
+
+/**
+ * Format list of properties.
+ *
+ * @type {SerializerFunction}
+ */
+const formatProperties = serialize.bind(
+	null,
+	( schema ) => schema.properties,
+	( schema ) => `_{ ${ Object.keys( schema.properties ).join( ', ' ) } }_`
+);
+
+/**
+ * Format list of array properties.
+ *
+ * @type {SerializerFunction}
+ */
+const formatArrayProperties = serialize.bind(
+	null,
+	( schema ) => schema.items && schema.items.properties,
+	( schema ) =>
+		`_[ { ${ Object.keys( schema.items.properties ).join( ', ' ) } } ]_`
+);
+
 /**
  * Convert settings properties to markup.
  *
@@ -72,34 +132,9 @@ function getSettingsPropertiesMarkup( { properties } ) {
 	markup += '| ---       | ---    | ---     | ---    |\n';
 	Object.entries( properties ).forEach( ( [ property, subschema ] ) => {
 		const defaultValue = subschema.default ?? '';
-		let type = subschema.type ?? '';
-		let props = subschema.items?.properties
-			? Object.keys( subschema.items.properties ).join( ', ' )
-			: '';
-
-		/*
-		 * Handle`oneOf` type definitions - extract the type and properties.
-		 * See: https://json-schema.org/understanding-json-schema/reference/combining#oneOf
-		 */
-		if ( Array.isArray( subschema.oneOf ) ) {
-			if ( ! type ) {
-				type = subschema.oneOf
-					.map( ( item ) => item.type )
-					.join( ', ' );
-			}
-
-			if ( ! props ) {
-				props = subschema.oneOf
-					.map( ( item ) =>
-						item.properties
-							? '_{' +
-							  Object.keys( item.properties ).join( ', ' ) +
-							  '}_'
-							: ''
-					)
-					.join( ' ' );
-			}
-		}
+		const type = formatType( subschema );
+		const props =
+			formatArrayProperties( subschema ) || formatProperties( subschema );
 
 		markup += `| ${ property } | ${ type } | ${ defaultValue } | ${ props } |\n`;
 	} );
@@ -122,9 +157,7 @@ function getStylePropertiesMarkup( { properties } ) {
 	markup += '| Property  | Type   | Props  |\n';
 	markup += '| ---       | ---    | ---    |\n';
 	Object.entries( properties ).forEach( ( [ property, subschema ] ) => {
-		const props = subschema.properties
-			? Object.keys( subschema.properties ).join( ', ' )
-			: '';
+		const props = formatProperties( subschema );
 		const type = formatType( subschema );
 		markup += `| ${ property } | ${ type } | ${ props } |\n`;
 	} );
@@ -153,26 +186,6 @@ function getTemplatePropertiesMarkup( { properties } ) {
 	return markup + '\n';
 }
 
-/**
- * Format list of types.
- *
- * @param {JSONSchema} schema
- * @return {string} type
- */
-function formatType( schema ) {
-	if ( schema.type ) {
-		return schema.type;
-	}
-
-	const subschemas = schema.anyOf || schema.oneOf;
-	if ( subschemas ) {
-		const types = subschemas.map( ( item ) => item.type ).filter( Boolean );
-		return [ ...new Set( types ) ].join( ', ' );
-	}
-
-	return '';
-}
-
 /**
  * Main function.
  */
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index a83f9047b87ae..b919f982b7eb6 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -82,10 +82,10 @@ Settings related to colors.
 | defaultDuotone | boolean | true |  |
 | defaultGradients | boolean | true |  |
 | defaultPalette | boolean | true |  |
-| duotone | array |  | name, slug, colors |
-| gradients | array |  | name, slug, gradient |
+| duotone | array |  | _[ { name, slug, colors } ]_ |
+| gradients | array |  | _[ { name, slug, gradient } ]_ |
 | link | boolean | false |  |
-| palette | array |  | name, slug, color |
+| palette | array |  | _[ { name, slug, color } ]_ |
 | text | boolean | true |  |
 | heading | boolean | true |  |
 | button | boolean | true |  |
@@ -101,7 +101,7 @@ Settings related to dimensions.
 | ---       | ---    | ---     | ---    |
 | aspectRatio | boolean | false |  |
 | defaultAspectRatios | boolean | true |  |
-| aspectRatios | array |  | name, slug, ratio |
+| aspectRatios | array |  | _[ { name, slug, ratio } ]_ |
 | minHeight | boolean | false |  |
 
 ---
@@ -147,7 +147,7 @@ Settings related to shadows.
 | Property  | Type   | Default | Props  |
 | ---       | ---    | ---     | ---    |
 | defaultPresets | boolean | true |  |
-| presets | array |  | name, slug, shadow |
+| presets | array |  | _[ { name, slug, shadow } ]_ |
 
 ---
 
@@ -157,14 +157,14 @@ Settings related to spacing.
 
 | Property  | Type   | Default | Props  |
 | ---       | ---    | ---     | ---    |
-| blockGap | boolean, null |  |   |
+| blockGap | boolean, null |  |  |
 | margin | boolean | false |  |
 | padding | boolean | false |  |
 | units | array | px,em,rem,vh,vw,% |  |
 | customSpacingSize | boolean | true |  |
 | defaultSpacingSizes | boolean | true |  |
-| spacingSizes | array |  | name, slug, size |
-| spacingScale | object |  |  |
+| spacingSizes | array |  | _[ { name, slug, size } ]_ |
+| spacingScale | object |  | _{ operator, increment, steps, mediumStep, unit }_ |
 
 ---
 
@@ -178,7 +178,7 @@ Settings related to typography.
 | customFontSize | boolean | true |  |
 | fontStyle | boolean | true |  |
 | fontWeight | boolean | true |  |
-| fluid | object, boolean | false | _{minFontSize, maxViewportWidth, minViewportWidth}_  |
+| fluid | object, boolean | false | _{ minFontSize, maxViewportWidth, minViewportWidth }_ |
 | letterSpacing | boolean | true |  |
 | lineHeight | boolean | false |  |
 | textAlign | boolean | true |  |
@@ -187,8 +187,8 @@ Settings related to typography.
 | writingMode | boolean | false |  |
 | textTransform | boolean | true |  |
 | dropCap | boolean | true |  |
-| fontSizes | array |  | name, slug, size, fluid |
-| fontFamilies | array |  | name, slug, fontFamily, fontFace |
+| fontSizes | array |  | _[ { name, slug, size, fluid } ]_ |
+| fontFamilies | array |  | _[ { name, slug, fontFamily, fontFace } ]_ |
 
 ---
 
@@ -206,11 +206,11 @@ Background styles.
 
 | Property  | Type   | Props  |
 | ---       | ---    | ---    |
-| backgroundImage | string, object |  |
-| backgroundPosition | string, object |  |
-| backgroundRepeat | string, object |  |
-| backgroundSize | string, object |  |
-| backgroundAttachment | string, object |  |
+| backgroundImage | string, object | _{ ref }_, _{ url }_ |
+| backgroundPosition | string, object | _{ ref }_ |
+| backgroundRepeat | string, object | _{ ref }_ |
+| backgroundSize | string, object | _{ ref }_ |
+| backgroundAttachment | string, object | _{ ref }_ |
 
 ---
 
@@ -220,14 +220,14 @@ Border styles.
 
 | Property  | Type   | Props  |
 | ---       | ---    | ---    |
-| color | string, object |  |
-| radius | string, object |  |
-| style | string, object |  |
-| width | string, object |  |
-| top | object | color, style, width |
-| right | object | color, style, width |
-| bottom | object | color, style, width |
-| left | object | color, style, width |
+| color | string, object | _{ ref }_ |
+| radius | string, object | _{ ref }_, _{ topLeft, topRight, bottomLeft, bottomRight }_ |
+| style | string, object | _{ ref }_ |
+| width | string, object | _{ ref }_ |
+| top | object | _{ color, style, width }_ |
+| right | object | _{ color, style, width }_ |
+| bottom | object | _{ color, style, width }_ |
+| left | object | _{ color, style, width }_ |
 
 ---
 
@@ -237,9 +237,9 @@ Color styles.
 
 | Property  | Type   | Props  |
 | ---       | ---    | ---    |
-| background | string, object |  |
-| gradient | string, object |  |
-| text | string, object |  |
+| background | string, object | _{ ref }_ |
+| gradient | string, object | _{ ref }_ |
+| text | string, object | _{ ref }_ |
 
 ---
 
@@ -255,8 +255,8 @@ Dimensions styles.
 
 | Property  | Type   | Props  |
 | ---       | ---    | ---    |
-| aspectRatio | string, object |  |
-| minHeight | string, object |  |
+| aspectRatio | string, object | _{ ref }_ |
+| minHeight | string, object | _{ ref }_ |
 
 ---
 
@@ -266,7 +266,7 @@ CSS and SVG filter styles.
 
 | Property  | Type   | Props  |
 | ---       | ---    | ---    |
-| duotone | string, object |  |
+| duotone | string, object | _{ ref }_ |
 
 ---
 
@@ -276,10 +276,10 @@ Outline styles.
 
 | Property  | Type   | Props  |
 | ---       | ---    | ---    |
-| color | string, object |  |
-| offset | string, object |  |
-| style | string, object |  |
-| width | string, object |  |
+| color | string, object | _{ ref }_ |
+| offset | string, object | _{ ref }_ |
+| style | string, object | _{ ref }_ |
+| width | string, object | _{ ref }_ |
 
 ---
 
@@ -295,9 +295,9 @@ Spacing styles.
 
 | Property  | Type   | Props  |
 | ---       | ---    | ---    |
-| blockGap | string, object |  |
-| margin | object | top, right, bottom, left |
-| padding | object | top, right, bottom, left |
+| blockGap | string, object | _{ ref }_ |
+| margin | object | _{ top, right, bottom, left }_ |
+| padding | object | _{ top, right, bottom, left }_ |
 
 ---
 
@@ -307,17 +307,17 @@ Typography styles.
 
 | Property  | Type   | Props  |
 | ---       | ---    | ---    |
-| fontFamily | string, object |  |
-| fontSize | string, object |  |
-| fontStyle | string, object |  |
-| fontWeight | string, object |  |
-| letterSpacing | string, object |  |
-| lineHeight | string, object |  |
-| textAlign | string, object |  |
-| textColumns | string, object |  |
-| textDecoration | string, object |  |
-| writingMode | string, object |  |
-| textTransform | string, object |  |
+| fontFamily | string, object | _{ ref }_ |
+| fontSize | string, object | _{ ref }_ |
+| fontStyle | string, object | _{ ref }_ |
+| fontWeight | string, object | _{ ref }_ |
+| letterSpacing | string, object | _{ ref }_ |
+| lineHeight | string, object | _{ ref }_ |
+| textAlign | string, object | _{ ref }_ |
+| textColumns | string, object | _{ ref }_ |
+| textDecoration | string, object | _{ ref }_ |
+| writingMode | string, object | _{ ref }_ |
+| textTransform | string, object | _{ ref }_ |
 
 ---
 

From fe14ed8878715988d7d148fd9a834ecfa616302f Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 18:46:44 -0500
Subject: [PATCH 22/43] Inline table generation

---
 bin/api-docs/gen-theme-reference.mjs | 119 ++++++++++-----------------
 1 file changed, 43 insertions(+), 76 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index eedfadf2c2ef5..d1f839148cab1 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -116,76 +116,6 @@ const formatArrayProperties = serialize.bind(
 		`_[ { ${ Object.keys( schema.items.properties ).join( ', ' ) } } ]_`
 );
 
-/**
- * Convert settings properties to markup.
- *
- * @param {JSONSchema} schema
- * @return {string} markup
- */
-function getSettingsPropertiesMarkup( { properties } ) {
-	if ( ! properties ) {
-		return '';
-	}
-
-	let markup = '';
-	markup += '| Property  | Type   | Default | Props  |\n';
-	markup += '| ---       | ---    | ---     | ---    |\n';
-	Object.entries( properties ).forEach( ( [ property, subschema ] ) => {
-		const defaultValue = subschema.default ?? '';
-		const type = formatType( subschema );
-		const props =
-			formatArrayProperties( subschema ) || formatProperties( subschema );
-
-		markup += `| ${ property } | ${ type } | ${ defaultValue } | ${ props } |\n`;
-	} );
-
-	return markup + '\n';
-}
-
-/**
- * Convert style properties to markup.
- *
- * @param {JSONSchema} schema
- * @return {string} markup
- */
-function getStylePropertiesMarkup( { properties } ) {
-	if ( ! properties ) {
-		return '';
-	}
-
-	let markup = '';
-	markup += '| Property  | Type   | Props  |\n';
-	markup += '| ---       | ---    | ---    |\n';
-	Object.entries( properties ).forEach( ( [ property, subschema ] ) => {
-		const props = formatProperties( subschema );
-		const type = formatType( subschema );
-		markup += `| ${ property } | ${ type } | ${ props } |\n`;
-	} );
-
-	return markup + '\n';
-}
-
-/**
- * Convert template properties to markup.
- *
- * @param {JSONSchema} schema
- * @return {string} markup
- */
-function getTemplatePropertiesMarkup( { properties } ) {
-	if ( ! properties ) {
-		return '';
-	}
-
-	let markup = '';
-	markup += '| Property | Description | Type |\n';
-	markup += '| ---      | ---         | ---  |\n';
-	Object.entries( properties ).forEach( ( [ property, subschema ] ) => {
-		const { description, type } = subschema;
-		markup += `| ${ property } | ${ description } | ${ type } |\n`;
-	} );
-	return markup + '\n';
-}
-
 /**
  * Main function.
  */
@@ -215,7 +145,20 @@ async function main() {
 	for ( const [ section, data ] of settings ) {
 		autogen += `### ${ section }\n\n`;
 		autogen += `${ data.description }\n\n`;
-		autogen += getSettingsPropertiesMarkup( data );
+		if ( data.properties ) {
+			autogen += '| Property  | Type   | Default | Props  |\n';
+			autogen += '| ---       | ---    | ---     | ---    |\n';
+			const properties = Object.entries( data.properties );
+			for ( const [ property, subschema ] of properties ) {
+				const type = formatType( subschema );
+				const defaultValue = subschema.default ?? '';
+				const props =
+					formatArrayProperties( subschema ) ||
+					formatProperties( subschema );
+				autogen += `| ${ property } | ${ type } | ${ defaultValue } | ${ props } |\n`;
+			}
+			autogen += '\n';
+		}
 		autogen += `---\n\n`;
 	}
 
@@ -227,7 +170,17 @@ async function main() {
 	for ( const [ section, data ] of styles ) {
 		autogen += `### ${ section }\n\n`;
 		autogen += `${ data.description }\n\n`;
-		autogen += getStylePropertiesMarkup( data );
+		if ( data.properties ) {
+			autogen += '| Property  | Type   | Props  |\n';
+			autogen += '| ---       | ---    | ---    |\n';
+			const properties = Object.entries( data.properties );
+			for ( const [ property, subschema ] of properties ) {
+				const props = formatProperties( subschema );
+				const type = formatType( subschema );
+				autogen += `| ${ property } | ${ type } | ${ props } |\n`;
+			}
+			autogen += '\n';
+		}
 		autogen += `---\n\n`;
 	}
 
@@ -235,17 +188,31 @@ async function main() {
 	autogen += '## customTemplates\n\n';
 	autogen += `${ themejson.properties.customTemplates.description }\n\n`;
 	autogen += `Type: \`${ themejson.properties.customTemplates.items.type }\`.\n\n`;
-	autogen += getTemplatePropertiesMarkup(
-		themejson.properties.customTemplates.items
+	autogen += '| Property | Description | Type |\n';
+	autogen += '| ---      | ---         | ---  |\n';
+	const customTemplatesProperties = Object.entries(
+		themejson.properties.customTemplates.items.properties
 	);
+	for ( const [ property, subschema ] of customTemplatesProperties ) {
+		const { description, type } = subschema;
+		autogen += `| ${ property } | ${ description } | ${ type } |\n`;
+	}
+	autogen += '\n';
 
 	// templateParts
 	autogen += '## templateParts\n\n';
 	autogen += `${ themejson.properties.templateParts.description }\n\n`;
 	autogen += `Type: \`${ themejson.properties.templateParts.items.type }\`.\n\n`;
-	autogen += getTemplatePropertiesMarkup(
-		themejson.properties.templateParts.items
+	autogen += '| Property | Description | Type |\n';
+	autogen += '| ---      | ---         | ---  |\n';
+	const templatePartsProperties = Object.entries(
+		themejson.properties.templateParts.items.properties
 	);
+	for ( const [ property, subschema ] of templatePartsProperties ) {
+		const { description, type } = subschema;
+		autogen += `| ${ property } | ${ description } | ${ type } |\n`;
+	}
+	autogen += '\n';
 
 	// Patterns
 	autogen += '## patterns' + '\n\n';

From d0109f8ec2e21125a5fce51f00cce128e6bffdcc Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 18:52:39 -0500
Subject: [PATCH 23/43] Create functino for document generation

---
 bin/api-docs/gen-theme-reference.mjs | 33 ++++++++++++++++++----------
 1 file changed, 21 insertions(+), 12 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index d1f839148cab1..793db085d1db0 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -117,17 +117,12 @@ const formatArrayProperties = serialize.bind(
 );
 
 /**
- * Main function.
+ * Generate documentation from theme.json schema.
+ *
+ * @param {JSONSchema} themejson
+ * @return {string} generated documentation
  */
-async function main() {
-	const themejson = await $RefParser.dereference(
-		THEME_JSON_SCHEMA_FILE.pathname,
-		{
-			parse: { binary: false, text: false, yaml: false },
-			resolve: { external: false },
-		}
-	);
-
+function generateDocs( themejson ) {
 	let autogen = '';
 
 	// Settings
@@ -219,14 +214,28 @@ async function main() {
 	autogen += themejson.properties.patterns.description + '\n';
 	autogen += 'Type: `' + themejson.properties.patterns.type + '`.\n\n';
 
-	// Read existing file to wrap auto generated content.
+	return `${ START_TOKEN }\n${ autogen }\n${ END_TOKEN }`;
+}
+
+/**
+ * Main function.
+ */
+async function main() {
+	const themejson = await $RefParser.dereference(
+		THEME_JSON_SCHEMA_FILE.pathname,
+		{
+			parse: { binary: false, text: false, yaml: false },
+			resolve: { external: false },
+		}
+	);
+
 	let docsContent = await fs.readFile( THEME_JSON_REF_DOC, {
 		encoding: 'utf8',
 		flag: 'r',
 	} );
 
 	// Replace auto generated part with new generated docs.
-	autogen = START_TOKEN + '\n' + autogen + '\n' + END_TOKEN;
+	const autogen = generateDocs( themejson );
 	docsContent = docsContent.replace( TOKEN_PATTERN, autogen );
 
 	// Write back out.

From c1f9a23cb5e53c739148c18bbf778fbafae06bf0 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 18:56:42 -0500
Subject: [PATCH 24/43] Rename and reorganize

---
 bin/api-docs/gen-theme-reference.mjs | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 793db085d1db0..2a04e74be3f73 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -126,6 +126,7 @@ function generateDocs( themejson ) {
 	let autogen = '';
 
 	// Settings
+	autogen += '## Settings\n\n';
 	const settings = themejson.definitions.settingsProperties.allOf.flatMap(
 		( settingsProperties ) =>
 			Object.entries( settingsProperties.properties )
@@ -136,14 +137,13 @@ function generateDocs( themejson ) {
 		themejson.properties.settings.allOf[ 1 ].properties
 			.useRootPaddingAwareAlignments,
 	] );
-	autogen += '## Settings\n\n';
-	for ( const [ section, data ] of settings ) {
+	for ( const [ section, schema ] of settings ) {
 		autogen += `### ${ section }\n\n`;
-		autogen += `${ data.description }\n\n`;
-		if ( data.properties ) {
+		autogen += `${ schema.description }\n\n`;
+		if ( schema.properties ) {
 			autogen += '| Property  | Type   | Default | Props  |\n';
 			autogen += '| ---       | ---    | ---     | ---    |\n';
-			const properties = Object.entries( data.properties );
+			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
 				const type = formatType( subschema );
 				const defaultValue = subschema.default ?? '';
@@ -158,17 +158,17 @@ function generateDocs( themejson ) {
 	}
 
 	// Styles
+	autogen += '## Styles\n\n';
 	const styles = Object.entries(
 		themejson.definitions.stylesProperties.properties
 	);
-	autogen += '## Styles\n\n';
-	for ( const [ section, data ] of styles ) {
+	for ( const [ section, schema ] of styles ) {
 		autogen += `### ${ section }\n\n`;
-		autogen += `${ data.description }\n\n`;
-		if ( data.properties ) {
+		autogen += `${ schema.description }\n\n`;
+		if ( schema.properties ) {
 			autogen += '| Property  | Type   | Props  |\n';
 			autogen += '| ---       | ---    | ---    |\n';
-			const properties = Object.entries( data.properties );
+			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
 				const props = formatProperties( subschema );
 				const type = formatType( subschema );

From 4d107eb70adc5f410097d8e000593816987a936b Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 18:59:02 -0500
Subject: [PATCH 25/43] Add settings and styles descriptions

---
 bin/api-docs/gen-theme-reference.mjs                      | 2 ++
 .../theme-json-reference/theme-json-living.md             | 8 ++++++++
 2 files changed, 10 insertions(+)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 2a04e74be3f73..1101348c9bef5 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -127,6 +127,7 @@ function generateDocs( themejson ) {
 
 	// Settings
 	autogen += '## Settings\n\n';
+	autogen += `${ themejson.properties.settings.description }\n\n`;
 	const settings = themejson.definitions.settingsProperties.allOf.flatMap(
 		( settingsProperties ) =>
 			Object.entries( settingsProperties.properties )
@@ -159,6 +160,7 @@ function generateDocs( themejson ) {
 
 	// Styles
 	autogen += '## Styles\n\n';
+	autogen += `${ themejson.properties.styles.description }\n\n`;
 	const styles = Object.entries(
 		themejson.definitions.stylesProperties.properties
 	);
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index b919f982b7eb6..9d8b37262c68f 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -23,6 +23,12 @@ See [Developing with theme.json](/docs/how-to-guides/themes/global-settings-and-
 <!-- START TOKEN Autogenerated - DO NOT EDIT -->
 ## Settings
 
+Settings for the block editor and individual blocks. These include things like:
+- Which customization options should be available to the user. 
+- The default colors, font sizes... available to the user. 
+- CSS custom properties and class names used in styles.
+- And the default layout of the editor (widths and available alignments).
+
 ### useRootPaddingAwareAlignments
 
 Enables root padding (the values from `styles.spacing.padding`) to be applied to the contents of full-width blocks instead of the root block.
@@ -200,6 +206,8 @@ Generate custom CSS custom properties of the form `--wp--custom--{key}--{nested-
 
 ## Styles
 
+Organized way to set CSS properties. Styles in the top-level will be added in the `body` selector.
+
 ### background
 
 Background styles.

From bc1d7c5f22bcf5dd8763a0cc529b31a308886e90 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 19:00:10 -0500
Subject: [PATCH 26/43] Remove template type because it should be obvious

---
 bin/api-docs/gen-theme-reference.mjs                          | 2 --
 .../theme-json-reference/theme-json-living.md                 | 4 ----
 2 files changed, 6 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 1101348c9bef5..d6b85e006a302 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -184,7 +184,6 @@ function generateDocs( themejson ) {
 	// customTemplates
 	autogen += '## customTemplates\n\n';
 	autogen += `${ themejson.properties.customTemplates.description }\n\n`;
-	autogen += `Type: \`${ themejson.properties.customTemplates.items.type }\`.\n\n`;
 	autogen += '| Property | Description | Type |\n';
 	autogen += '| ---      | ---         | ---  |\n';
 	const customTemplatesProperties = Object.entries(
@@ -199,7 +198,6 @@ function generateDocs( themejson ) {
 	// templateParts
 	autogen += '## templateParts\n\n';
 	autogen += `${ themejson.properties.templateParts.description }\n\n`;
-	autogen += `Type: \`${ themejson.properties.templateParts.items.type }\`.\n\n`;
 	autogen += '| Property | Description | Type |\n';
 	autogen += '| ---      | ---         | ---  |\n';
 	const templatePartsProperties = Object.entries(
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index 9d8b37262c68f..0dbe7fcc37312 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -333,8 +333,6 @@ Typography styles.
 
 Additional metadata for custom templates defined in the templates folder.
 
-Type: `object`.
-
 | Property | Description | Type |
 | ---      | ---         | ---  |
 | name | Filename, without extension, of the template in the templates folder. | string |
@@ -345,8 +343,6 @@ Type: `object`.
 
 Additional metadata for template parts defined in the parts folder.
 
-Type: `object`.
-
 | Property | Description | Type |
 | ---      | ---         | ---  |
 | name | Filename, without extension, of the template in the parts folder. | string |

From 7e8f9b6f2d654d5d716fa97cc6ba3cda596e9499 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 19:25:52 -0500
Subject: [PATCH 27/43] Revamp type gen

---
 bin/api-docs/gen-theme-reference.mjs          |  59 ++--
 .../theme-json-reference/theme-json-living.md | 260 +++++++++---------
 2 files changed, 173 insertions(+), 146 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index d6b85e006a302..999e516ae3944 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -89,8 +89,9 @@ function serialize( predicate, serializer, schema ) {
  */
 const formatType = serialize.bind(
 	null,
-	( schema ) => schema.type,
-	( schema ) => schema.type
+	( schema ) =>
+		schema.type && ! [ 'object', 'array' ].includes( schema.type ),
+	( schema ) => `\`${ schema.type }\``
 );
 
 /**
@@ -101,7 +102,7 @@ const formatType = serialize.bind(
 const formatProperties = serialize.bind(
 	null,
 	( schema ) => schema.properties,
-	( schema ) => `_{ ${ Object.keys( schema.properties ).join( ', ' ) } }_`
+	( schema ) => `\`{ ${ Object.keys( schema.properties ).join( ', ' ) } }\``
 );
 
 /**
@@ -113,9 +114,39 @@ const formatArrayProperties = serialize.bind(
 	null,
 	( schema ) => schema.items && schema.items.properties,
 	( schema ) =>
-		`_[ { ${ Object.keys( schema.items.properties ).join( ', ' ) } } ]_`
+		`\`[ { ${ Object.keys( schema.items.properties ).join( ', ' ) } } ]\``
+);
+
+/**
+ * Format list of array types.
+ *
+ * @type {SerializerFunction}
+ */
+const formatArrayTypes = serialize.bind(
+	null,
+	( schema ) =>
+		schema.items &&
+		schema.items.type &&
+		! [ 'object', 'array' ].includes( schema.items.type ),
+	( schema ) => `\`[ ${ schema.items.type } ]\``
 );
 
+/**
+ * Generate types from schema.
+ *
+ * @param {JSONSchema} schema
+ * @return {string} generated types
+ */
+function generateTypes( schema ) {
+	const primitiveTypes = formatType( schema );
+	const arrayTypes = formatArrayTypes( schema );
+	const objectTypes = formatProperties( schema );
+	const arrayObjectTypes = formatArrayProperties( schema );
+	return [ primitiveTypes, arrayTypes, arrayObjectTypes, objectTypes ]
+		.filter( Boolean )
+		.join( ', ' );
+}
+
 /**
  * Generate documentation from theme.json schema.
  *
@@ -142,16 +173,13 @@ function generateDocs( themejson ) {
 		autogen += `### ${ section }\n\n`;
 		autogen += `${ schema.description }\n\n`;
 		if ( schema.properties ) {
-			autogen += '| Property  | Type   | Default | Props  |\n';
-			autogen += '| ---       | ---    | ---     | ---    |\n';
+			autogen += '| Property  | Type   | Default |\n';
+			autogen += '| ---       | ---    | ---     |\n';
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
-				const type = formatType( subschema );
+				const types = generateTypes( subschema );
 				const defaultValue = subschema.default ?? '';
-				const props =
-					formatArrayProperties( subschema ) ||
-					formatProperties( subschema );
-				autogen += `| ${ property } | ${ type } | ${ defaultValue } | ${ props } |\n`;
+				autogen += `| ${ property } | ${ types } | ${ defaultValue } |\n`;
 			}
 			autogen += '\n';
 		}
@@ -168,13 +196,12 @@ function generateDocs( themejson ) {
 		autogen += `### ${ section }\n\n`;
 		autogen += `${ schema.description }\n\n`;
 		if ( schema.properties ) {
-			autogen += '| Property  | Type   | Props  |\n';
-			autogen += '| ---       | ---    | ---    |\n';
+			autogen += '| Property  | Type   |\n';
+			autogen += '| ---       | ---    |\n';
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
-				const props = formatProperties( subschema );
-				const type = formatType( subschema );
-				autogen += `| ${ property } | ${ type } | ${ props } |\n`;
+				const types = generateTypes( subschema );
+				autogen += `| ${ property } | ${ types } |\n`;
 			}
 			autogen += '\n';
 		}
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index 0dbe7fcc37312..26a08e37b7e2d 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -55,10 +55,10 @@ Setting that enables the following UI tools:
 
 Settings related to background.
 
-| Property  | Type   | Default | Props  |
-| ---       | ---    | ---     | ---    |
-| backgroundImage | boolean | false |  |
-| backgroundSize | boolean | false |  |
+| Property  | Type   | Default |
+| ---       | ---    | ---     |
+| backgroundImage | `boolean` | false |
+| backgroundSize | `boolean` | false |
 
 ---
 
@@ -66,12 +66,12 @@ Settings related to background.
 
 Settings related to borders.
 
-| Property  | Type   | Default | Props  |
-| ---       | ---    | ---     | ---    |
-| color | boolean | false |  |
-| radius | boolean | false |  |
-| style | boolean | false |  |
-| width | boolean | false |  |
+| Property  | Type   | Default |
+| ---       | ---    | ---     |
+| color | `boolean` | false |
+| radius | `boolean` | false |
+| style | `boolean` | false |
+| width | `boolean` | false |
 
 ---
 
@@ -79,23 +79,23 @@ Settings related to borders.
 
 Settings related to colors.
 
-| Property  | Type   | Default | Props  |
-| ---       | ---    | ---     | ---    |
-| background | boolean | true |  |
-| custom | boolean | true |  |
-| customDuotone | boolean | true |  |
-| customGradient | boolean | true |  |
-| defaultDuotone | boolean | true |  |
-| defaultGradients | boolean | true |  |
-| defaultPalette | boolean | true |  |
-| duotone | array |  | _[ { name, slug, colors } ]_ |
-| gradients | array |  | _[ { name, slug, gradient } ]_ |
-| link | boolean | false |  |
-| palette | array |  | _[ { name, slug, color } ]_ |
-| text | boolean | true |  |
-| heading | boolean | true |  |
-| button | boolean | true |  |
-| caption | boolean | true |  |
+| Property  | Type   | Default |
+| ---       | ---    | ---     |
+| background | `boolean` | true |
+| custom | `boolean` | true |
+| customDuotone | `boolean` | true |
+| customGradient | `boolean` | true |
+| defaultDuotone | `boolean` | true |
+| defaultGradients | `boolean` | true |
+| defaultPalette | `boolean` | true |
+| duotone | `[ { name, slug, colors } ]` |  |
+| gradients | `[ { name, slug, gradient } ]` |  |
+| link | `boolean` | false |
+| palette | `[ { name, slug, color } ]` |  |
+| text | `boolean` | true |
+| heading | `boolean` | true |
+| button | `boolean` | true |
+| caption | `boolean` | true |
 
 ---
 
@@ -103,12 +103,12 @@ Settings related to colors.
 
 Settings related to dimensions.
 
-| Property  | Type   | Default | Props  |
-| ---       | ---    | ---     | ---    |
-| aspectRatio | boolean | false |  |
-| defaultAspectRatios | boolean | true |  |
-| aspectRatios | array |  | _[ { name, slug, ratio } ]_ |
-| minHeight | boolean | false |  |
+| Property  | Type   | Default |
+| ---       | ---    | ---     |
+| aspectRatio | `boolean` | false |
+| defaultAspectRatios | `boolean` | true |
+| aspectRatios | `[ { name, slug, ratio } ]` |  |
+| minHeight | `boolean` | false |
 
 ---
 
@@ -116,12 +116,12 @@ Settings related to dimensions.
 
 Settings related to layout.
 
-| Property  | Type   | Default | Props  |
-| ---       | ---    | ---     | ---    |
-| contentSize | string |  |  |
-| wideSize | string |  |  |
-| allowEditing | boolean | true |  |
-| allowCustomContentAndWideSize | boolean | true |  |
+| Property  | Type   | Default |
+| ---       | ---    | ---     |
+| contentSize | `string` |  |
+| wideSize | `string` |  |
+| allowEditing | `boolean` | true |
+| allowCustomContentAndWideSize | `boolean` | true |
 
 ---
 
@@ -129,10 +129,10 @@ Settings related to layout.
 
 Settings related to the lightbox.
 
-| Property  | Type   | Default | Props  |
-| ---       | ---    | ---     | ---    |
-| enabled | boolean |  |  |
-| allowEditing | boolean |  |  |
+| Property  | Type   | Default |
+| ---       | ---    | ---     |
+| enabled | `boolean` |  |
+| allowEditing | `boolean` |  |
 
 ---
 
@@ -140,9 +140,9 @@ Settings related to the lightbox.
 
 Settings related to position.
 
-| Property  | Type   | Default | Props  |
-| ---       | ---    | ---     | ---    |
-| sticky | boolean | false |  |
+| Property  | Type   | Default |
+| ---       | ---    | ---     |
+| sticky | `boolean` | false |
 
 ---
 
@@ -150,10 +150,10 @@ Settings related to position.
 
 Settings related to shadows.
 
-| Property  | Type   | Default | Props  |
-| ---       | ---    | ---     | ---    |
-| defaultPresets | boolean | true |  |
-| presets | array |  | _[ { name, slug, shadow } ]_ |
+| Property  | Type   | Default |
+| ---       | ---    | ---     |
+| defaultPresets | `boolean` | true |
+| presets | `[ { name, slug, shadow } ]` |  |
 
 ---
 
@@ -161,16 +161,16 @@ Settings related to shadows.
 
 Settings related to spacing.
 
-| Property  | Type   | Default | Props  |
-| ---       | ---    | ---     | ---    |
-| blockGap | boolean, null |  |  |
-| margin | boolean | false |  |
-| padding | boolean | false |  |
-| units | array | px,em,rem,vh,vw,% |  |
-| customSpacingSize | boolean | true |  |
-| defaultSpacingSizes | boolean | true |  |
-| spacingSizes | array |  | _[ { name, slug, size } ]_ |
-| spacingScale | object |  | _{ operator, increment, steps, mediumStep, unit }_ |
+| Property  | Type   | Default |
+| ---       | ---    | ---     |
+| blockGap | `boolean`, `null` |  |
+| margin | `boolean` | false |
+| padding | `boolean` | false |
+| units | `[ string ]` | px,em,rem,vh,vw,% |
+| customSpacingSize | `boolean` | true |
+| defaultSpacingSizes | `boolean` | true |
+| spacingSizes | `[ { name, slug, size } ]` |  |
+| spacingScale | `{ operator, increment, steps, mediumStep, unit }` |  |
 
 ---
 
@@ -178,23 +178,23 @@ Settings related to spacing.
 
 Settings related to typography.
 
-| Property  | Type   | Default | Props  |
-| ---       | ---    | ---     | ---    |
-| defaultFontSizes | boolean | true |  |
-| customFontSize | boolean | true |  |
-| fontStyle | boolean | true |  |
-| fontWeight | boolean | true |  |
-| fluid | object, boolean | false | _{ minFontSize, maxViewportWidth, minViewportWidth }_ |
-| letterSpacing | boolean | true |  |
-| lineHeight | boolean | false |  |
-| textAlign | boolean | true |  |
-| textColumns | boolean | false |  |
-| textDecoration | boolean | true |  |
-| writingMode | boolean | false |  |
-| textTransform | boolean | true |  |
-| dropCap | boolean | true |  |
-| fontSizes | array |  | _[ { name, slug, size, fluid } ]_ |
-| fontFamilies | array |  | _[ { name, slug, fontFamily, fontFace } ]_ |
+| Property  | Type   | Default |
+| ---       | ---    | ---     |
+| defaultFontSizes | `boolean` | true |
+| customFontSize | `boolean` | true |
+| fontStyle | `boolean` | true |
+| fontWeight | `boolean` | true |
+| fluid | `boolean`, `{ minFontSize, maxViewportWidth, minViewportWidth }` | false |
+| letterSpacing | `boolean` | true |
+| lineHeight | `boolean` | false |
+| textAlign | `boolean` | true |
+| textColumns | `boolean` | false |
+| textDecoration | `boolean` | true |
+| writingMode | `boolean` | false |
+| textTransform | `boolean` | true |
+| dropCap | `boolean` | true |
+| fontSizes | `[ { name, slug, size, fluid } ]` |  |
+| fontFamilies | `[ { name, slug, fontFamily, fontFace } ]` |  |
 
 ---
 
@@ -212,13 +212,13 @@ Organized way to set CSS properties. Styles in the top-level will be added in th
 
 Background styles.
 
-| Property  | Type   | Props  |
-| ---       | ---    | ---    |
-| backgroundImage | string, object | _{ ref }_, _{ url }_ |
-| backgroundPosition | string, object | _{ ref }_ |
-| backgroundRepeat | string, object | _{ ref }_ |
-| backgroundSize | string, object | _{ ref }_ |
-| backgroundAttachment | string, object | _{ ref }_ |
+| Property  | Type   |
+| ---       | ---    |
+| backgroundImage | `string`, `{ ref }`, `{ url }` |
+| backgroundPosition | `string`, `{ ref }` |
+| backgroundRepeat | `string`, `{ ref }` |
+| backgroundSize | `string`, `{ ref }` |
+| backgroundAttachment | `string`, `{ ref }` |
 
 ---
 
@@ -226,16 +226,16 @@ Background styles.
 
 Border styles.
 
-| Property  | Type   | Props  |
-| ---       | ---    | ---    |
-| color | string, object | _{ ref }_ |
-| radius | string, object | _{ ref }_, _{ topLeft, topRight, bottomLeft, bottomRight }_ |
-| style | string, object | _{ ref }_ |
-| width | string, object | _{ ref }_ |
-| top | object | _{ color, style, width }_ |
-| right | object | _{ color, style, width }_ |
-| bottom | object | _{ color, style, width }_ |
-| left | object | _{ color, style, width }_ |
+| Property  | Type   |
+| ---       | ---    |
+| color | `string`, `{ ref }` |
+| radius | `string`, `{ ref }`, `{ topLeft, topRight, bottomLeft, bottomRight }` |
+| style | `string`, `{ ref }` |
+| width | `string`, `{ ref }` |
+| top | `{ color, style, width }` |
+| right | `{ color, style, width }` |
+| bottom | `{ color, style, width }` |
+| left | `{ color, style, width }` |
 
 ---
 
@@ -243,11 +243,11 @@ Border styles.
 
 Color styles.
 
-| Property  | Type   | Props  |
-| ---       | ---    | ---    |
-| background | string, object | _{ ref }_ |
-| gradient | string, object | _{ ref }_ |
-| text | string, object | _{ ref }_ |
+| Property  | Type   |
+| ---       | ---    |
+| background | `string`, `{ ref }` |
+| gradient | `string`, `{ ref }` |
+| text | `string`, `{ ref }` |
 
 ---
 
@@ -261,10 +261,10 @@ Sets custom CSS to apply styling not covered by other theme.json properties.
 
 Dimensions styles.
 
-| Property  | Type   | Props  |
-| ---       | ---    | ---    |
-| aspectRatio | string, object | _{ ref }_ |
-| minHeight | string, object | _{ ref }_ |
+| Property  | Type   |
+| ---       | ---    |
+| aspectRatio | `string`, `{ ref }` |
+| minHeight | `string`, `{ ref }` |
 
 ---
 
@@ -272,9 +272,9 @@ Dimensions styles.
 
 CSS and SVG filter styles.
 
-| Property  | Type   | Props  |
-| ---       | ---    | ---    |
-| duotone | string, object | _{ ref }_ |
+| Property  | Type   |
+| ---       | ---    |
+| duotone | `string`, `{ ref }` |
 
 ---
 
@@ -282,12 +282,12 @@ CSS and SVG filter styles.
 
 Outline styles.
 
-| Property  | Type   | Props  |
-| ---       | ---    | ---    |
-| color | string, object | _{ ref }_ |
-| offset | string, object | _{ ref }_ |
-| style | string, object | _{ ref }_ |
-| width | string, object | _{ ref }_ |
+| Property  | Type   |
+| ---       | ---    |
+| color | `string`, `{ ref }` |
+| offset | `string`, `{ ref }` |
+| style | `string`, `{ ref }` |
+| width | `string`, `{ ref }` |
 
 ---
 
@@ -301,11 +301,11 @@ Box shadow styles.
 
 Spacing styles.
 
-| Property  | Type   | Props  |
-| ---       | ---    | ---    |
-| blockGap | string, object | _{ ref }_ |
-| margin | object | _{ top, right, bottom, left }_ |
-| padding | object | _{ top, right, bottom, left }_ |
+| Property  | Type   |
+| ---       | ---    |
+| blockGap | `string`, `{ ref }` |
+| margin | `{ top, right, bottom, left }` |
+| padding | `{ top, right, bottom, left }` |
 
 ---
 
@@ -313,19 +313,19 @@ Spacing styles.
 
 Typography styles.
 
-| Property  | Type   | Props  |
-| ---       | ---    | ---    |
-| fontFamily | string, object | _{ ref }_ |
-| fontSize | string, object | _{ ref }_ |
-| fontStyle | string, object | _{ ref }_ |
-| fontWeight | string, object | _{ ref }_ |
-| letterSpacing | string, object | _{ ref }_ |
-| lineHeight | string, object | _{ ref }_ |
-| textAlign | string, object | _{ ref }_ |
-| textColumns | string, object | _{ ref }_ |
-| textDecoration | string, object | _{ ref }_ |
-| writingMode | string, object | _{ ref }_ |
-| textTransform | string, object | _{ ref }_ |
+| Property  | Type   |
+| ---       | ---    |
+| fontFamily | `string`, `{ ref }` |
+| fontSize | `string`, `{ ref }` |
+| fontStyle | `string`, `{ ref }` |
+| fontWeight | `string`, `{ ref }` |
+| letterSpacing | `string`, `{ ref }` |
+| lineHeight | `string`, `{ ref }` |
+| textAlign | `string`, `{ ref }` |
+| textColumns | `string`, `{ ref }` |
+| textDecoration | `string`, `{ ref }` |
+| writingMode | `string`, `{ ref }` |
+| textTransform | `string`, `{ ref }` |
 
 ---
 

From 3d683611aa0d8d19816c658ef59b8a62ca52df2a Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 19:38:01 -0500
Subject: [PATCH 28/43] Update type generation

---
 bin/api-docs/gen-theme-reference.mjs          | 51 +++++++++----------
 .../theme-json-reference/theme-json-living.md | 16 +++---
 2 files changed, 32 insertions(+), 35 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 999e516ae3944..54a246596d3d0 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -71,15 +71,16 @@ const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );
  *
  * @param {PredicateFunction}  predicate
  * @param {SerializerFunction} serializer
- * @param {JSONSchema}         schema
- * @return {string} flattened schema
+ * @return {SerializerFunction} flattened schema
  */
-function serialize( predicate, serializer, schema ) {
-	const schemas = predicate( schema )
-		? [ schema ]
-		: schema.anyOf || schema.oneOf || [];
-	const formatted = schemas.filter( predicate ).map( serializer );
-	return [ ...new Set( formatted ) ].join( ', ' );
+function createSerializer( predicate, serializer ) {
+	return ( schema ) => {
+		const schemas = predicate( schema )
+			? [ schema ]
+			: schema.anyOf || schema.oneOf || [];
+		const formatted = schemas.filter( predicate ).map( serializer );
+		return [ ...new Set( formatted ) ].join( ', ' );
+	};
 }
 
 /**
@@ -87,8 +88,7 @@ function serialize( predicate, serializer, schema ) {
  *
  * @type {SerializerFunction}
  */
-const formatType = serialize.bind(
-	null,
+const serializePrimitives = createSerializer(
 	( schema ) =>
 		schema.type && ! [ 'object', 'array' ].includes( schema.type ),
 	( schema ) => `\`${ schema.type }\``
@@ -96,11 +96,8 @@ const formatType = serialize.bind(
 
 /**
  * Format list of properties.
- *
- * @type {SerializerFunction}
  */
-const formatProperties = serialize.bind(
-	null,
+const serializeObjects = createSerializer(
 	( schema ) => schema.properties,
 	( schema ) => `\`{ ${ Object.keys( schema.properties ).join( ', ' ) } }\``
 );
@@ -110,8 +107,7 @@ const formatProperties = serialize.bind(
  *
  * @type {SerializerFunction}
  */
-const formatArrayProperties = serialize.bind(
-	null,
+const serializeObjectArrays = createSerializer(
 	( schema ) => schema.items && schema.items.properties,
 	( schema ) =>
 		`\`[ { ${ Object.keys( schema.items.properties ).join( ', ' ) } } ]\``
@@ -122,8 +118,7 @@ const formatArrayProperties = serialize.bind(
  *
  * @type {SerializerFunction}
  */
-const formatArrayTypes = serialize.bind(
-	null,
+const serializePrimitiveArrays = createSerializer(
 	( schema ) =>
 		schema.items &&
 		schema.items.type &&
@@ -138,10 +133,10 @@ const formatArrayTypes = serialize.bind(
  * @return {string} generated types
  */
 function generateTypes( schema ) {
-	const primitiveTypes = formatType( schema );
-	const arrayTypes = formatArrayTypes( schema );
-	const objectTypes = formatProperties( schema );
-	const arrayObjectTypes = formatArrayProperties( schema );
+	const primitiveTypes = serializePrimitives( schema );
+	const arrayTypes = serializePrimitiveArrays( schema );
+	const objectTypes = serializeObjects( schema );
+	const arrayObjectTypes = serializeObjectArrays( schema );
 	return [ primitiveTypes, arrayTypes, arrayObjectTypes, objectTypes ]
 		.filter( Boolean )
 		.join( ', ' );
@@ -217,8 +212,9 @@ function generateDocs( themejson ) {
 		themejson.properties.customTemplates.items.properties
 	);
 	for ( const [ property, subschema ] of customTemplatesProperties ) {
-		const { description, type } = subschema;
-		autogen += `| ${ property } | ${ description } | ${ type } |\n`;
+		const { description } = subschema;
+		const types = generateTypes( subschema );
+		autogen += `| ${ property } | ${ description } | ${ types } |\n`;
 	}
 	autogen += '\n';
 
@@ -231,15 +227,16 @@ function generateDocs( themejson ) {
 		themejson.properties.templateParts.items.properties
 	);
 	for ( const [ property, subschema ] of templatePartsProperties ) {
-		const { description, type } = subschema;
-		autogen += `| ${ property } | ${ description } | ${ type } |\n`;
+		const { description } = subschema;
+		const types = generateTypes( subschema );
+		autogen += `| ${ property } | ${ description } | ${ types } |\n`;
 	}
 	autogen += '\n';
 
 	// Patterns
 	autogen += '## patterns' + '\n\n';
+	autogen += `Type: ${ generateTypes( themejson.properties.patterns ) }.\n\n`;
 	autogen += themejson.properties.patterns.description + '\n';
-	autogen += 'Type: `' + themejson.properties.patterns.type + '`.\n\n';
 
 	return `${ START_TOKEN }\n${ autogen }\n${ END_TOKEN }`;
 }
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index 26a08e37b7e2d..e0a9741c4a8fc 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -335,9 +335,9 @@ Additional metadata for custom templates defined in the templates folder.
 
 | Property | Description | Type |
 | ---      | ---         | ---  |
-| name | Filename, without extension, of the template in the templates folder. | string |
-| title | Title of the template, translatable. | string |
-| postTypes | List of post types that can use this custom template. | array |
+| name | Filename, without extension, of the template in the templates folder. | `string` |
+| title | Title of the template, translatable. | `string` |
+| postTypes | List of post types that can use this custom template. | `[ string ]` |
 
 ## templateParts
 
@@ -345,14 +345,14 @@ Additional metadata for template parts defined in the parts folder.
 
 | Property | Description | Type |
 | ---      | ---         | ---  |
-| name | Filename, without extension, of the template in the parts folder. | string |
-| title | Title of the template, translatable. | string |
-| area | The area the template part is used for. Block variations for `header` and `footer` values exist and will be used when the area is set to one of those. | string |
+| name | Filename, without extension, of the template in the parts folder. | `string` |
+| title | Title of the template, translatable. | `string` |
+| area | The area the template part is used for. Block variations for `header` and `footer` values exist and will be used when the area is set to one of those. | `string` |
 
 ## patterns
 
-An array of pattern slugs to be registered from the Pattern Directory.
-Type: `array`.
+Type: `[ string ]`.
 
+An array of pattern slugs to be registered from the Pattern Directory.
 
 <!-- END TOKEN Autogenerated - DO NOT EDIT -->

From 962bcfa705bea867e22e47b2893d01e5e608bcdd Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 19:42:01 -0500
Subject: [PATCH 29/43] Rename and refactor functions

---
 bin/api-docs/gen-theme-reference.mjs | 33 +++++++++++++++-------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 54a246596d3d0..3235dc04a7f91 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -88,7 +88,7 @@ function createSerializer( predicate, serializer ) {
  *
  * @type {SerializerFunction}
  */
-const serializePrimitives = createSerializer(
+const serializePrimitiveTypes = createSerializer(
 	( schema ) =>
 		schema.type && ! [ 'object', 'array' ].includes( schema.type ),
 	( schema ) => `\`${ schema.type }\``
@@ -97,7 +97,7 @@ const serializePrimitives = createSerializer(
 /**
  * Format list of properties.
  */
-const serializeObjects = createSerializer(
+const serializeObjectTypes = createSerializer(
 	( schema ) => schema.properties,
 	( schema ) => `\`{ ${ Object.keys( schema.properties ).join( ', ' ) } }\``
 );
@@ -107,7 +107,7 @@ const serializeObjects = createSerializer(
  *
  * @type {SerializerFunction}
  */
-const serializeObjectArrays = createSerializer(
+const serializeObjectArrayTypes = createSerializer(
 	( schema ) => schema.items && schema.items.properties,
 	( schema ) =>
 		`\`[ { ${ Object.keys( schema.items.properties ).join( ', ' ) } } ]\``
@@ -118,7 +118,7 @@ const serializeObjectArrays = createSerializer(
  *
  * @type {SerializerFunction}
  */
-const serializePrimitiveArrays = createSerializer(
+const serializePrimitiveArrayTypes = createSerializer(
 	( schema ) =>
 		schema.items &&
 		schema.items.type &&
@@ -132,12 +132,13 @@ const serializePrimitiveArrays = createSerializer(
  * @param {JSONSchema} schema
  * @return {string} generated types
  */
-function generateTypes( schema ) {
-	const primitiveTypes = serializePrimitives( schema );
-	const arrayTypes = serializePrimitiveArrays( schema );
-	const objectTypes = serializeObjects( schema );
-	const arrayObjectTypes = serializeObjectArrays( schema );
-	return [ primitiveTypes, arrayTypes, arrayObjectTypes, objectTypes ]
+function serializeTypes( schema ) {
+	return [
+		serializePrimitiveTypes( schema ),
+		serializeObjectTypes( schema ),
+		serializePrimitiveArrayTypes( schema ),
+		serializeObjectArrayTypes( schema ),
+	]
 		.filter( Boolean )
 		.join( ', ' );
 }
@@ -172,7 +173,7 @@ function generateDocs( themejson ) {
 			autogen += '| ---       | ---    | ---     |\n';
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
-				const types = generateTypes( subschema );
+				const types = serializeTypes( subschema );
 				const defaultValue = subschema.default ?? '';
 				autogen += `| ${ property } | ${ types } | ${ defaultValue } |\n`;
 			}
@@ -195,7 +196,7 @@ function generateDocs( themejson ) {
 			autogen += '| ---       | ---    |\n';
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
-				const types = generateTypes( subschema );
+				const types = serializeTypes( subschema );
 				autogen += `| ${ property } | ${ types } |\n`;
 			}
 			autogen += '\n';
@@ -213,7 +214,7 @@ function generateDocs( themejson ) {
 	);
 	for ( const [ property, subschema ] of customTemplatesProperties ) {
 		const { description } = subschema;
-		const types = generateTypes( subschema );
+		const types = serializeTypes( subschema );
 		autogen += `| ${ property } | ${ description } | ${ types } |\n`;
 	}
 	autogen += '\n';
@@ -228,14 +229,16 @@ function generateDocs( themejson ) {
 	);
 	for ( const [ property, subschema ] of templatePartsProperties ) {
 		const { description } = subschema;
-		const types = generateTypes( subschema );
+		const types = serializeTypes( subschema );
 		autogen += `| ${ property } | ${ description } | ${ types } |\n`;
 	}
 	autogen += '\n';
 
 	// Patterns
 	autogen += '## patterns' + '\n\n';
-	autogen += `Type: ${ generateTypes( themejson.properties.patterns ) }.\n\n`;
+	autogen += `Type: ${ serializeTypes(
+		themejson.properties.patterns
+	) }.\n\n`;
 	autogen += themejson.properties.patterns.description + '\n';
 
 	return `${ START_TOKEN }\n${ autogen }\n${ END_TOKEN }`;

From 339738387213910a3289d8bfb178dff4ccf3e400 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 19:46:08 -0500
Subject: [PATCH 30/43] Update JSDoc

---
 bin/api-docs/gen-theme-reference.mjs | 22 ++++++++++------------
 1 file changed, 10 insertions(+), 12 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 3235dc04a7f91..03b3c3cec6af7 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -65,13 +65,13 @@ const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );
  */
 
 /**
- * Serialize a schema that may use `anyOf` or `oneOf`.
+ * Create a serializer function for a type. Supports merging anyOf and oneOf subschemas.
  *
  * @see {@link https://json-schema.org/understanding-json-schema/reference/combining.html}
  *
- * @param {PredicateFunction}  predicate
- * @param {SerializerFunction} serializer
- * @return {SerializerFunction} flattened schema
+ * @param {PredicateFunction}  predicate  Type predicate function to match a type.
+ * @param {SerializerFunction} serializer Serializer function to format a type.
+ * @return {SerializerFunction} Serializer function for the give type.
  */
 function createSerializer( predicate, serializer ) {
 	return ( schema ) => {
@@ -132,7 +132,7 @@ const serializePrimitiveArrayTypes = createSerializer(
  * @param {JSONSchema} schema
  * @return {string} generated types
  */
-function serializeTypes( schema ) {
+function generateTypes( schema ) {
 	return [
 		serializePrimitiveTypes( schema ),
 		serializeObjectTypes( schema ),
@@ -173,7 +173,7 @@ function generateDocs( themejson ) {
 			autogen += '| ---       | ---    | ---     |\n';
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
-				const types = serializeTypes( subschema );
+				const types = generateTypes( subschema );
 				const defaultValue = subschema.default ?? '';
 				autogen += `| ${ property } | ${ types } | ${ defaultValue } |\n`;
 			}
@@ -196,7 +196,7 @@ function generateDocs( themejson ) {
 			autogen += '| ---       | ---    |\n';
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
-				const types = serializeTypes( subschema );
+				const types = generateTypes( subschema );
 				autogen += `| ${ property } | ${ types } |\n`;
 			}
 			autogen += '\n';
@@ -214,7 +214,7 @@ function generateDocs( themejson ) {
 	);
 	for ( const [ property, subschema ] of customTemplatesProperties ) {
 		const { description } = subschema;
-		const types = serializeTypes( subschema );
+		const types = generateTypes( subschema );
 		autogen += `| ${ property } | ${ description } | ${ types } |\n`;
 	}
 	autogen += '\n';
@@ -229,16 +229,14 @@ function generateDocs( themejson ) {
 	);
 	for ( const [ property, subschema ] of templatePartsProperties ) {
 		const { description } = subschema;
-		const types = serializeTypes( subschema );
+		const types = generateTypes( subschema );
 		autogen += `| ${ property } | ${ description } | ${ types } |\n`;
 	}
 	autogen += '\n';
 
 	// Patterns
 	autogen += '## patterns' + '\n\n';
-	autogen += `Type: ${ serializeTypes(
-		themejson.properties.patterns
-	) }.\n\n`;
+	autogen += `Type: ${ generateTypes( themejson.properties.patterns ) }.\n\n`;
 	autogen += themejson.properties.patterns.description + '\n';
 
 	return `${ START_TOKEN }\n${ autogen }\n${ END_TOKEN }`;

From ed95c0c39d77c2b64c25c6894564cbb734337600 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 20:05:36 -0500
Subject: [PATCH 31/43] Update comments

---
 bin/api-docs/gen-theme-reference.mjs | 36 ++++++++++++++++++----------
 1 file changed, 24 insertions(+), 12 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 03b3c3cec6af7..5435a5506502a 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -84,7 +84,7 @@ function createSerializer( predicate, serializer ) {
 }
 
 /**
- * Format list of types.
+ * Serialize primitive types.
  *
  * @type {SerializerFunction}
  */
@@ -95,7 +95,9 @@ const serializePrimitiveTypes = createSerializer(
 );
 
 /**
- * Format list of properties.
+ * Serialize object types.
+ *
+ * @type {SerializerFunction}
  */
 const serializeObjectTypes = createSerializer(
 	( schema ) => schema.properties,
@@ -103,7 +105,7 @@ const serializeObjectTypes = createSerializer(
 );
 
 /**
- * Format list of array properties.
+ * Serialize object array types.
  *
  * @type {SerializerFunction}
  */
@@ -114,7 +116,7 @@ const serializeObjectArrayTypes = createSerializer(
 );
 
 /**
- * Format list of array types.
+ * Serialize primitive array types.
  *
  * @type {SerializerFunction}
  */
@@ -129,8 +131,8 @@ const serializePrimitiveArrayTypes = createSerializer(
 /**
  * Generate types from schema.
  *
- * @param {JSONSchema} schema
- * @return {string} generated types
+ * @param {JSONSchema} schema JSON schema
+ * @return {string} serialized types
  */
 function generateTypes( schema ) {
 	return [
@@ -146,13 +148,15 @@ function generateTypes( schema ) {
 /**
  * Generate documentation from theme.json schema.
  *
- * @param {JSONSchema} themejson
+ * @param {JSONSchema} themejson JSON schema
  * @return {string} generated documentation
  */
 function generateDocs( themejson ) {
 	let autogen = '';
 
-	// Settings
+	/* --------------- *
+	 * Settings        *
+	 * --------------- */
 	autogen += '## Settings\n\n';
 	autogen += `${ themejson.properties.settings.description }\n\n`;
 	const settings = themejson.definitions.settingsProperties.allOf.flatMap(
@@ -182,7 +186,9 @@ function generateDocs( themejson ) {
 		autogen += `---\n\n`;
 	}
 
-	// Styles
+	/* --------------- *
+	 * Styles          *
+	 * --------------- */
 	autogen += '## Styles\n\n';
 	autogen += `${ themejson.properties.styles.description }\n\n`;
 	const styles = Object.entries(
@@ -204,7 +210,9 @@ function generateDocs( themejson ) {
 		autogen += `---\n\n`;
 	}
 
-	// customTemplates
+	/* --------------- *
+	 * customTemplates *
+	 * --------------- */
 	autogen += '## customTemplates\n\n';
 	autogen += `${ themejson.properties.customTemplates.description }\n\n`;
 	autogen += '| Property | Description | Type |\n';
@@ -219,7 +227,9 @@ function generateDocs( themejson ) {
 	}
 	autogen += '\n';
 
-	// templateParts
+	/* --------------- *
+	 * templateParts   *
+	 * --------------- */
 	autogen += '## templateParts\n\n';
 	autogen += `${ themejson.properties.templateParts.description }\n\n`;
 	autogen += '| Property | Description | Type |\n';
@@ -234,7 +244,9 @@ function generateDocs( themejson ) {
 	}
 	autogen += '\n';
 
-	// Patterns
+	/* --------------- *
+	 * patterns        *
+	 * --------------- */
 	autogen += '## patterns' + '\n\n';
 	autogen += `Type: ${ generateTypes( themejson.properties.patterns ) }.\n\n`;
 	autogen += themejson.properties.patterns.description + '\n';

From 85ee58f2bce1c94cb538aec08fdff2480d48fdc9 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 20:15:13 -0500
Subject: [PATCH 32/43] Stringify default value

---
 bin/api-docs/gen-theme-reference.mjs          |  4 +-
 .../theme-json-reference/theme-json-living.md | 86 +++++++++----------
 2 files changed, 46 insertions(+), 44 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 5435a5506502a..a401937fe75ac 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -178,7 +178,9 @@ function generateDocs( themejson ) {
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
 				const types = generateTypes( subschema );
-				const defaultValue = subschema.default ?? '';
+				const defaultValue = subschema.default
+					? `\`${ JSON.stringify( subschema.default ) }\``
+					: '';
 				autogen += `| ${ property } | ${ types } | ${ defaultValue } |\n`;
 			}
 			autogen += '\n';
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index e0a9741c4a8fc..ada6e2e70ea9b 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -57,8 +57,8 @@ Settings related to background.
 
 | Property  | Type   | Default |
 | ---       | ---    | ---     |
-| backgroundImage | `boolean` | false |
-| backgroundSize | `boolean` | false |
+| backgroundImage | `boolean` |  |
+| backgroundSize | `boolean` |  |
 
 ---
 
@@ -68,10 +68,10 @@ Settings related to borders.
 
 | Property  | Type   | Default |
 | ---       | ---    | ---     |
-| color | `boolean` | false |
-| radius | `boolean` | false |
-| style | `boolean` | false |
-| width | `boolean` | false |
+| color | `boolean` |  |
+| radius | `boolean` |  |
+| style | `boolean` |  |
+| width | `boolean` |  |
 
 ---
 
@@ -81,21 +81,21 @@ Settings related to colors.
 
 | Property  | Type   | Default |
 | ---       | ---    | ---     |
-| background | `boolean` | true |
-| custom | `boolean` | true |
-| customDuotone | `boolean` | true |
-| customGradient | `boolean` | true |
-| defaultDuotone | `boolean` | true |
-| defaultGradients | `boolean` | true |
-| defaultPalette | `boolean` | true |
+| background | `boolean` | `true` |
+| custom | `boolean` | `true` |
+| customDuotone | `boolean` | `true` |
+| customGradient | `boolean` | `true` |
+| defaultDuotone | `boolean` | `true` |
+| defaultGradients | `boolean` | `true` |
+| defaultPalette | `boolean` | `true` |
 | duotone | `[ { name, slug, colors } ]` |  |
 | gradients | `[ { name, slug, gradient } ]` |  |
-| link | `boolean` | false |
+| link | `boolean` |  |
 | palette | `[ { name, slug, color } ]` |  |
-| text | `boolean` | true |
-| heading | `boolean` | true |
-| button | `boolean` | true |
-| caption | `boolean` | true |
+| text | `boolean` | `true` |
+| heading | `boolean` | `true` |
+| button | `boolean` | `true` |
+| caption | `boolean` | `true` |
 
 ---
 
@@ -105,10 +105,10 @@ Settings related to dimensions.
 
 | Property  | Type   | Default |
 | ---       | ---    | ---     |
-| aspectRatio | `boolean` | false |
-| defaultAspectRatios | `boolean` | true |
+| aspectRatio | `boolean` |  |
+| defaultAspectRatios | `boolean` | `true` |
 | aspectRatios | `[ { name, slug, ratio } ]` |  |
-| minHeight | `boolean` | false |
+| minHeight | `boolean` |  |
 
 ---
 
@@ -120,8 +120,8 @@ Settings related to layout.
 | ---       | ---    | ---     |
 | contentSize | `string` |  |
 | wideSize | `string` |  |
-| allowEditing | `boolean` | true |
-| allowCustomContentAndWideSize | `boolean` | true |
+| allowEditing | `boolean` | `true` |
+| allowCustomContentAndWideSize | `boolean` | `true` |
 
 ---
 
@@ -142,7 +142,7 @@ Settings related to position.
 
 | Property  | Type   | Default |
 | ---       | ---    | ---     |
-| sticky | `boolean` | false |
+| sticky | `boolean` |  |
 
 ---
 
@@ -152,7 +152,7 @@ Settings related to shadows.
 
 | Property  | Type   | Default |
 | ---       | ---    | ---     |
-| defaultPresets | `boolean` | true |
+| defaultPresets | `boolean` | `true` |
 | presets | `[ { name, slug, shadow } ]` |  |
 
 ---
@@ -164,11 +164,11 @@ Settings related to spacing.
 | Property  | Type   | Default |
 | ---       | ---    | ---     |
 | blockGap | `boolean`, `null` |  |
-| margin | `boolean` | false |
-| padding | `boolean` | false |
-| units | `[ string ]` | px,em,rem,vh,vw,% |
-| customSpacingSize | `boolean` | true |
-| defaultSpacingSizes | `boolean` | true |
+| margin | `boolean` |  |
+| padding | `boolean` |  |
+| units | `[ string ]` | `["px","em","rem","vh","vw","%"]` |
+| customSpacingSize | `boolean` | `true` |
+| defaultSpacingSizes | `boolean` | `true` |
 | spacingSizes | `[ { name, slug, size } ]` |  |
 | spacingScale | `{ operator, increment, steps, mediumStep, unit }` |  |
 
@@ -180,19 +180,19 @@ Settings related to typography.
 
 | Property  | Type   | Default |
 | ---       | ---    | ---     |
-| defaultFontSizes | `boolean` | true |
-| customFontSize | `boolean` | true |
-| fontStyle | `boolean` | true |
-| fontWeight | `boolean` | true |
-| fluid | `boolean`, `{ minFontSize, maxViewportWidth, minViewportWidth }` | false |
-| letterSpacing | `boolean` | true |
-| lineHeight | `boolean` | false |
-| textAlign | `boolean` | true |
-| textColumns | `boolean` | false |
-| textDecoration | `boolean` | true |
-| writingMode | `boolean` | false |
-| textTransform | `boolean` | true |
-| dropCap | `boolean` | true |
+| defaultFontSizes | `boolean` | `true` |
+| customFontSize | `boolean` | `true` |
+| fontStyle | `boolean` | `true` |
+| fontWeight | `boolean` | `true` |
+| fluid | `boolean`, `{ minFontSize, maxViewportWidth, minViewportWidth }` |  |
+| letterSpacing | `boolean` | `true` |
+| lineHeight | `boolean` |  |
+| textAlign | `boolean` | `true` |
+| textColumns | `boolean` |  |
+| textDecoration | `boolean` | `true` |
+| writingMode | `boolean` |  |
+| textTransform | `boolean` | `true` |
+| dropCap | `boolean` | `true` |
 | fontSizes | `[ { name, slug, size, fluid } ]` |  |
 | fontFamilies | `[ { name, slug, fontFamily, fontFace } ]` |  |
 

From 8ec5a665e5360c6d930d5a26883925f8fee050be Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 20:15:25 -0500
Subject: [PATCH 33/43] Add descriptions for styles and settings

---
 bin/api-docs/gen-theme-reference.mjs          |  16 +-
 .../theme-json-reference/theme-json-living.md | 260 +++++++++---------
 2 files changed, 140 insertions(+), 136 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index a401937fe75ac..c246123bb3bbf 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -173,15 +173,17 @@ function generateDocs( themejson ) {
 		autogen += `### ${ section }\n\n`;
 		autogen += `${ schema.description }\n\n`;
 		if ( schema.properties ) {
-			autogen += '| Property  | Type   | Default |\n';
-			autogen += '| ---       | ---    | ---     |\n';
+			autogen += '| Property | Description | Type | Default |\n';
+			autogen += '| -------- | ----------- | ---- | ------- |\n';
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
+				const description =
+					subschema.description?.split( '\n', 1 )[ 0 ] ?? '';
 				const types = generateTypes( subschema );
 				const defaultValue = subschema.default
 					? `\`${ JSON.stringify( subschema.default ) }\``
 					: '';
-				autogen += `| ${ property } | ${ types } | ${ defaultValue } |\n`;
+				autogen += `| ${ property } | ${ description } | ${ types } | ${ defaultValue } |\n`;
 			}
 			autogen += '\n';
 		}
@@ -200,12 +202,14 @@ function generateDocs( themejson ) {
 		autogen += `### ${ section }\n\n`;
 		autogen += `${ schema.description }\n\n`;
 		if ( schema.properties ) {
-			autogen += '| Property  | Type   |\n';
-			autogen += '| ---       | ---    |\n';
+			autogen += '| Property | Description | Type |\n';
+			autogen += '| -------- | ----------- | ---- |\n';
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
+				const description =
+					subschema.description?.split( '\n', 1 )[ 0 ] ?? '';
 				const types = generateTypes( subschema );
-				autogen += `| ${ property } | ${ types } |\n`;
+				autogen += `| ${ property } | ${ description } | ${ types } |\n`;
 			}
 			autogen += '\n';
 		}
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index ada6e2e70ea9b..d86601d15d3e7 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -55,10 +55,10 @@ Setting that enables the following UI tools:
 
 Settings related to background.
 
-| Property  | Type   | Default |
-| ---       | ---    | ---     |
-| backgroundImage | `boolean` |  |
-| backgroundSize | `boolean` |  |
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| backgroundImage | Allow users to set a background image. | `boolean` |  |
+| backgroundSize | Allow users to set values related to the size of a background image, including size, position, and repeat controls. | `boolean` |  |
 
 ---
 
@@ -66,12 +66,12 @@ Settings related to background.
 
 Settings related to borders.
 
-| Property  | Type   | Default |
-| ---       | ---    | ---     |
-| color | `boolean` |  |
-| radius | `boolean` |  |
-| style | `boolean` |  |
-| width | `boolean` |  |
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| color | Allow users to set custom border colors. | `boolean` |  |
+| radius | Allow users to set custom border radius. | `boolean` |  |
+| style | Allow users to set custom border styles. | `boolean` |  |
+| width | Allow users to set custom border widths. | `boolean` |  |
 
 ---
 
@@ -79,23 +79,23 @@ Settings related to borders.
 
 Settings related to colors.
 
-| Property  | Type   | Default |
-| ---       | ---    | ---     |
-| background | `boolean` | `true` |
-| custom | `boolean` | `true` |
-| customDuotone | `boolean` | `true` |
-| customGradient | `boolean` | `true` |
-| defaultDuotone | `boolean` | `true` |
-| defaultGradients | `boolean` | `true` |
-| defaultPalette | `boolean` | `true` |
-| duotone | `[ { name, slug, colors } ]` |  |
-| gradients | `[ { name, slug, gradient } ]` |  |
-| link | `boolean` |  |
-| palette | `[ { name, slug, color } ]` |  |
-| text | `boolean` | `true` |
-| heading | `boolean` | `true` |
-| button | `boolean` | `true` |
-| caption | `boolean` | `true` |
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| background | Allow users to set background colors. | `boolean` | `true` |
+| custom | Allow users to select custom colors. | `boolean` | `true` |
+| customDuotone | Allow users to create custom duotone filters. | `boolean` | `true` |
+| customGradient | Allow users to create custom gradients. | `boolean` | `true` |
+| defaultDuotone | Allow users to choose filters from the default duotone filter presets. | `boolean` | `true` |
+| defaultGradients | Allow users to choose colors from the default gradients. | `boolean` | `true` |
+| defaultPalette | Allow users to choose colors from the default palette. | `boolean` | `true` |
+| duotone | Duotone presets for the duotone picker. | `[ { name, slug, colors } ]` |  |
+| gradients | Gradient presets for the gradient picker. | `[ { name, slug, gradient } ]` |  |
+| link | Allow users to set link colors in a block. | `boolean` |  |
+| palette | Color palette presets for the color picker. | `[ { name, slug, color } ]` |  |
+| text | Allow users to set text colors in a block. | `boolean` | `true` |
+| heading | Allow users to set heading colors in a block. | `boolean` | `true` |
+| button | Allow users to set button colors in a block. | `boolean` | `true` |
+| caption | Allow users to set caption colors in a block. | `boolean` | `true` |
 
 ---
 
@@ -103,12 +103,12 @@ Settings related to colors.
 
 Settings related to dimensions.
 
-| Property  | Type   | Default |
-| ---       | ---    | ---     |
-| aspectRatio | `boolean` |  |
-| defaultAspectRatios | `boolean` | `true` |
-| aspectRatios | `[ { name, slug, ratio } ]` |  |
-| minHeight | `boolean` |  |
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| aspectRatio | Allow users to set an aspect ratio. | `boolean` |  |
+| defaultAspectRatios | Allow users to choose aspect ratios from the default set of aspect ratios. | `boolean` | `true` |
+| aspectRatios | Allow users to define aspect ratios for some blocks. | `[ { name, slug, ratio } ]` |  |
+| minHeight | Allow users to set custom minimum height. | `boolean` |  |
 
 ---
 
@@ -116,12 +116,12 @@ Settings related to dimensions.
 
 Settings related to layout.
 
-| Property  | Type   | Default |
-| ---       | ---    | ---     |
-| contentSize | `string` |  |
-| wideSize | `string` |  |
-| allowEditing | `boolean` | `true` |
-| allowCustomContentAndWideSize | `boolean` | `true` |
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| contentSize | Sets the max-width of the content. | `string` |  |
+| wideSize | Sets the max-width of wide (`.alignwide`) content. Also used as the maximum viewport when calculating fluid font sizes | `string` |  |
+| allowEditing | Disable the layout UI controls. | `boolean` | `true` |
+| allowCustomContentAndWideSize | Enable or disable the custom content and wide size controls. | `boolean` | `true` |
 
 ---
 
@@ -129,10 +129,10 @@ Settings related to layout.
 
 Settings related to the lightbox.
 
-| Property  | Type   | Default |
-| ---       | ---    | ---     |
-| enabled | `boolean` |  |
-| allowEditing | `boolean` |  |
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| enabled | Defines whether the lightbox is enabled or not. | `boolean` |  |
+| allowEditing | Defines whether to show the Lightbox UI in the block editor. If set to `false`, the user won't be able to change the lightbox settings in the block editor. | `boolean` |  |
 
 ---
 
@@ -140,9 +140,9 @@ Settings related to the lightbox.
 
 Settings related to position.
 
-| Property  | Type   | Default |
-| ---       | ---    | ---     |
-| sticky | `boolean` |  |
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| sticky | Allow users to set sticky position. | `boolean` |  |
 
 ---
 
@@ -150,10 +150,10 @@ Settings related to position.
 
 Settings related to shadows.
 
-| Property  | Type   | Default |
-| ---       | ---    | ---     |
-| defaultPresets | `boolean` | `true` |
-| presets | `[ { name, slug, shadow } ]` |  |
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| defaultPresets | Allow users to choose shadows from the default shadow presets. | `boolean` | `true` |
+| presets | Shadow presets for the shadow picker. | `[ { name, slug, shadow } ]` |  |
 
 ---
 
@@ -161,16 +161,16 @@ Settings related to shadows.
 
 Settings related to spacing.
 
-| Property  | Type   | Default |
-| ---       | ---    | ---     |
-| blockGap | `boolean`, `null` |  |
-| margin | `boolean` |  |
-| padding | `boolean` |  |
-| units | `[ string ]` | `["px","em","rem","vh","vw","%"]` |
-| customSpacingSize | `boolean` | `true` |
-| defaultSpacingSizes | `boolean` | `true` |
-| spacingSizes | `[ { name, slug, size } ]` |  |
-| spacingScale | `{ operator, increment, steps, mediumStep, unit }` |  |
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| blockGap | Enables `--wp--style--block-gap` to be generated from styles.spacing.blockGap. | `boolean`, `null` |  |
+| margin | Allow users to set a custom margin. | `boolean` |  |
+| padding | Allow users to set a custom padding. | `boolean` |  |
+| units | List of units the user can use for spacing values. | `[ string ]` | `["px","em","rem","vh","vw","%"]` |
+| customSpacingSize | Allow users to set custom space sizes. | `boolean` | `true` |
+| defaultSpacingSizes | Allow users to choose space sizes from the default space size presets. | `boolean` | `true` |
+| spacingSizes | Space size presets for the space size selector. | `[ { name, slug, size } ]` |  |
+| spacingScale | Settings to auto-generate space size presets for the space size selector. | `{ operator, increment, steps, mediumStep, unit }` |  |
 
 ---
 
@@ -178,23 +178,23 @@ Settings related to spacing.
 
 Settings related to typography.
 
-| Property  | Type   | Default |
-| ---       | ---    | ---     |
-| defaultFontSizes | `boolean` | `true` |
-| customFontSize | `boolean` | `true` |
-| fontStyle | `boolean` | `true` |
-| fontWeight | `boolean` | `true` |
-| fluid | `boolean`, `{ minFontSize, maxViewportWidth, minViewportWidth }` |  |
-| letterSpacing | `boolean` | `true` |
-| lineHeight | `boolean` |  |
-| textAlign | `boolean` | `true` |
-| textColumns | `boolean` |  |
-| textDecoration | `boolean` | `true` |
-| writingMode | `boolean` |  |
-| textTransform | `boolean` | `true` |
-| dropCap | `boolean` | `true` |
-| fontSizes | `[ { name, slug, size, fluid } ]` |  |
-| fontFamilies | `[ { name, slug, fontFamily, fontFace } ]` |  |
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| defaultFontSizes | Allow users to choose font sizes from the default font size presets. | `boolean` | `true` |
+| customFontSize | Allow users to set custom font sizes. | `boolean` | `true` |
+| fontStyle | Allow users to set custom font styles. | `boolean` | `true` |
+| fontWeight | Allow users to set custom font weights. | `boolean` | `true` |
+| fluid | Enables fluid typography and allows users to set global fluid typography parameters. | `boolean`, `{ minFontSize, maxViewportWidth, minViewportWidth }` |  |
+| letterSpacing | Allow users to set custom letter spacing. | `boolean` | `true` |
+| lineHeight | Allow users to set custom line height. | `boolean` |  |
+| textAlign | Allow users to set the text align. | `boolean` | `true` |
+| textColumns | Allow users to set the number of text columns. | `boolean` |  |
+| textDecoration | Allow users to set custom text decorations. | `boolean` | `true` |
+| writingMode | Allow users to set the writing mode. | `boolean` |  |
+| textTransform | Allow users to set custom text transforms. | `boolean` | `true` |
+| dropCap | Enable drop cap. | `boolean` | `true` |
+| fontSizes | Font size presets for the font size selector. | `[ { name, slug, size, fluid } ]` |  |
+| fontFamilies | Font family presets for the font family selector. | `[ { name, slug, fontFamily, fontFace } ]` |  |
 
 ---
 
@@ -212,13 +212,13 @@ Organized way to set CSS properties. Styles in the top-level will be added in th
 
 Background styles.
 
-| Property  | Type   |
-| ---       | ---    |
-| backgroundImage | `string`, `{ ref }`, `{ url }` |
-| backgroundPosition | `string`, `{ ref }` |
-| backgroundRepeat | `string`, `{ ref }` |
-| backgroundSize | `string`, `{ ref }` |
-| backgroundAttachment | `string`, `{ ref }` |
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| backgroundImage | Sets the `background-image` CSS property. | `string`, `{ ref }`, `{ url }` |
+| backgroundPosition | Sets the `background-position` CSS property. | `string`, `{ ref }` |
+| backgroundRepeat | Sets the `background-repeat` CSS property. | `string`, `{ ref }` |
+| backgroundSize | Sets the `background-size` CSS property. | `string`, `{ ref }` |
+| backgroundAttachment | Sets the `background-attachment` CSS property. | `string`, `{ ref }` |
 
 ---
 
@@ -226,16 +226,16 @@ Background styles.
 
 Border styles.
 
-| Property  | Type   |
-| ---       | ---    |
-| color | `string`, `{ ref }` |
-| radius | `string`, `{ ref }`, `{ topLeft, topRight, bottomLeft, bottomRight }` |
-| style | `string`, `{ ref }` |
-| width | `string`, `{ ref }` |
-| top | `{ color, style, width }` |
-| right | `{ color, style, width }` |
-| bottom | `{ color, style, width }` |
-| left | `{ color, style, width }` |
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| color | Sets the `border-color` CSS property. | `string`, `{ ref }` |
+| radius | Sets the `border-radius` CSS property. | `string`, `{ ref }`, `{ topLeft, topRight, bottomLeft, bottomRight }` |
+| style | Sets the `border-style` CSS property. | `string`, `{ ref }` |
+| width | Sets the `border-width` CSS property. | `string`, `{ ref }` |
+| top |  | `{ color, style, width }` |
+| right |  | `{ color, style, width }` |
+| bottom |  | `{ color, style, width }` |
+| left |  | `{ color, style, width }` |
 
 ---
 
@@ -243,11 +243,11 @@ Border styles.
 
 Color styles.
 
-| Property  | Type   |
-| ---       | ---    |
-| background | `string`, `{ ref }` |
-| gradient | `string`, `{ ref }` |
-| text | `string`, `{ ref }` |
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| background | Sets the `background-color` CSS property. | `string`, `{ ref }` |
+| gradient | Sets the `background` CSS property. | `string`, `{ ref }` |
+| text | Sets the `color` CSS property. | `string`, `{ ref }` |
 
 ---
 
@@ -261,10 +261,10 @@ Sets custom CSS to apply styling not covered by other theme.json properties.
 
 Dimensions styles.
 
-| Property  | Type   |
-| ---       | ---    |
-| aspectRatio | `string`, `{ ref }` |
-| minHeight | `string`, `{ ref }` |
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| aspectRatio | Sets the `aspect-ratio` CSS property. | `string`, `{ ref }` |
+| minHeight | Sets the `min-height` CSS property. | `string`, `{ ref }` |
 
 ---
 
@@ -272,9 +272,9 @@ Dimensions styles.
 
 CSS and SVG filter styles.
 
-| Property  | Type   |
-| ---       | ---    |
-| duotone | `string`, `{ ref }` |
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| duotone | Sets the duotone filter. | `string`, `{ ref }` |
 
 ---
 
@@ -282,12 +282,12 @@ CSS and SVG filter styles.
 
 Outline styles.
 
-| Property  | Type   |
-| ---       | ---    |
-| color | `string`, `{ ref }` |
-| offset | `string`, `{ ref }` |
-| style | `string`, `{ ref }` |
-| width | `string`, `{ ref }` |
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| color | Sets the `outline-color` CSS property. | `string`, `{ ref }` |
+| offset | Sets the `outline-offset` CSS property. | `string`, `{ ref }` |
+| style | Sets the `outline-style` CSS property. | `string`, `{ ref }` |
+| width | Sets the `outline-width` CSS property. | `string`, `{ ref }` |
 
 ---
 
@@ -301,11 +301,11 @@ Box shadow styles.
 
 Spacing styles.
 
-| Property  | Type   |
-| ---       | ---    |
-| blockGap | `string`, `{ ref }` |
-| margin | `{ top, right, bottom, left }` |
-| padding | `{ top, right, bottom, left }` |
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| blockGap | Sets the `--wp--style--block-gap` CSS custom property when settings.spacing.blockGap is true. | `string`, `{ ref }` |
+| margin | Margin styles. | `{ top, right, bottom, left }` |
+| padding | Padding styles. | `{ top, right, bottom, left }` |
 
 ---
 
@@ -313,19 +313,19 @@ Spacing styles.
 
 Typography styles.
 
-| Property  | Type   |
-| ---       | ---    |
-| fontFamily | `string`, `{ ref }` |
-| fontSize | `string`, `{ ref }` |
-| fontStyle | `string`, `{ ref }` |
-| fontWeight | `string`, `{ ref }` |
-| letterSpacing | `string`, `{ ref }` |
-| lineHeight | `string`, `{ ref }` |
-| textAlign | `string`, `{ ref }` |
-| textColumns | `string`, `{ ref }` |
-| textDecoration | `string`, `{ ref }` |
-| writingMode | `string`, `{ ref }` |
-| textTransform | `string`, `{ ref }` |
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| fontFamily | Sets the `font-family` CSS property. | `string`, `{ ref }` |
+| fontSize | Sets the `font-size` CSS property. | `string`, `{ ref }` |
+| fontStyle | Sets the `font-style` CSS property. | `string`, `{ ref }` |
+| fontWeight | Sets the `font-weight` CSS property. | `string`, `{ ref }` |
+| letterSpacing | Sets the `letter-spacing` CSS property. | `string`, `{ ref }` |
+| lineHeight | Sets the `line-height` CSS property. | `string`, `{ ref }` |
+| textAlign | Sets the `text-align` CSS property. | `string`, `{ ref }` |
+| textColumns | Sets the `column-count` CSS property. | `string`, `{ ref }` |
+| textDecoration | Sets the `text-decoration` CSS property. | `string`, `{ ref }` |
+| writingMode | Sets the `writing-mode` CSS property. | `string`, `{ ref }` |
+| textTransform | Sets the `text-transform` CSS property. | `string`, `{ ref }` |
 
 ---
 

From 11f0a98d3e14282d2b45c72dedd596b1f04f2ce8 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 20:22:31 -0500
Subject: [PATCH 34/43] Fix falsy default values

---
 bin/api-docs/gen-theme-reference.mjs          |  7 ++--
 .../theme-json-reference/theme-json-living.md | 34 +++++++++----------
 2 files changed, 21 insertions(+), 20 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index c246123bb3bbf..c332ce68f221d 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -180,9 +180,10 @@ function generateDocs( themejson ) {
 				const description =
 					subschema.description?.split( '\n', 1 )[ 0 ] ?? '';
 				const types = generateTypes( subschema );
-				const defaultValue = subschema.default
-					? `\`${ JSON.stringify( subschema.default ) }\``
-					: '';
+				const defaultValue =
+					'default' in subschema
+						? `\`${ JSON.stringify( subschema.default ) }\``
+						: '';
 				autogen += `| ${ property } | ${ description } | ${ types } | ${ defaultValue } |\n`;
 			}
 			autogen += '\n';
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index d86601d15d3e7..00e12d75684d4 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -57,8 +57,8 @@ Settings related to background.
 
 | Property | Description | Type | Default |
 | -------- | ----------- | ---- | ------- |
-| backgroundImage | Allow users to set a background image. | `boolean` |  |
-| backgroundSize | Allow users to set values related to the size of a background image, including size, position, and repeat controls. | `boolean` |  |
+| backgroundImage | Allow users to set a background image. | `boolean` | `false` |
+| backgroundSize | Allow users to set values related to the size of a background image, including size, position, and repeat controls. | `boolean` | `false` |
 
 ---
 
@@ -68,10 +68,10 @@ Settings related to borders.
 
 | Property | Description | Type | Default |
 | -------- | ----------- | ---- | ------- |
-| color | Allow users to set custom border colors. | `boolean` |  |
-| radius | Allow users to set custom border radius. | `boolean` |  |
-| style | Allow users to set custom border styles. | `boolean` |  |
-| width | Allow users to set custom border widths. | `boolean` |  |
+| color | Allow users to set custom border colors. | `boolean` | `false` |
+| radius | Allow users to set custom border radius. | `boolean` | `false` |
+| style | Allow users to set custom border styles. | `boolean` | `false` |
+| width | Allow users to set custom border widths. | `boolean` | `false` |
 
 ---
 
@@ -90,7 +90,7 @@ Settings related to colors.
 | defaultPalette | Allow users to choose colors from the default palette. | `boolean` | `true` |
 | duotone | Duotone presets for the duotone picker. | `[ { name, slug, colors } ]` |  |
 | gradients | Gradient presets for the gradient picker. | `[ { name, slug, gradient } ]` |  |
-| link | Allow users to set link colors in a block. | `boolean` |  |
+| link | Allow users to set link colors in a block. | `boolean` | `false` |
 | palette | Color palette presets for the color picker. | `[ { name, slug, color } ]` |  |
 | text | Allow users to set text colors in a block. | `boolean` | `true` |
 | heading | Allow users to set heading colors in a block. | `boolean` | `true` |
@@ -105,10 +105,10 @@ Settings related to dimensions.
 
 | Property | Description | Type | Default |
 | -------- | ----------- | ---- | ------- |
-| aspectRatio | Allow users to set an aspect ratio. | `boolean` |  |
+| aspectRatio | Allow users to set an aspect ratio. | `boolean` | `false` |
 | defaultAspectRatios | Allow users to choose aspect ratios from the default set of aspect ratios. | `boolean` | `true` |
 | aspectRatios | Allow users to define aspect ratios for some blocks. | `[ { name, slug, ratio } ]` |  |
-| minHeight | Allow users to set custom minimum height. | `boolean` |  |
+| minHeight | Allow users to set custom minimum height. | `boolean` | `false` |
 
 ---
 
@@ -142,7 +142,7 @@ Settings related to position.
 
 | Property | Description | Type | Default |
 | -------- | ----------- | ---- | ------- |
-| sticky | Allow users to set sticky position. | `boolean` |  |
+| sticky | Allow users to set sticky position. | `boolean` | `false` |
 
 ---
 
@@ -163,9 +163,9 @@ Settings related to spacing.
 
 | Property | Description | Type | Default |
 | -------- | ----------- | ---- | ------- |
-| blockGap | Enables `--wp--style--block-gap` to be generated from styles.spacing.blockGap. | `boolean`, `null` |  |
-| margin | Allow users to set a custom margin. | `boolean` |  |
-| padding | Allow users to set a custom padding. | `boolean` |  |
+| blockGap | Enables `--wp--style--block-gap` to be generated from styles.spacing.blockGap. | `boolean`, `null` | `null` |
+| margin | Allow users to set a custom margin. | `boolean` | `false` |
+| padding | Allow users to set a custom padding. | `boolean` | `false` |
 | units | List of units the user can use for spacing values. | `[ string ]` | `["px","em","rem","vh","vw","%"]` |
 | customSpacingSize | Allow users to set custom space sizes. | `boolean` | `true` |
 | defaultSpacingSizes | Allow users to choose space sizes from the default space size presets. | `boolean` | `true` |
@@ -184,13 +184,13 @@ Settings related to typography.
 | customFontSize | Allow users to set custom font sizes. | `boolean` | `true` |
 | fontStyle | Allow users to set custom font styles. | `boolean` | `true` |
 | fontWeight | Allow users to set custom font weights. | `boolean` | `true` |
-| fluid | Enables fluid typography and allows users to set global fluid typography parameters. | `boolean`, `{ minFontSize, maxViewportWidth, minViewportWidth }` |  |
+| fluid | Enables fluid typography and allows users to set global fluid typography parameters. | `boolean`, `{ minFontSize, maxViewportWidth, minViewportWidth }` | `false` |
 | letterSpacing | Allow users to set custom letter spacing. | `boolean` | `true` |
-| lineHeight | Allow users to set custom line height. | `boolean` |  |
+| lineHeight | Allow users to set custom line height. | `boolean` | `false` |
 | textAlign | Allow users to set the text align. | `boolean` | `true` |
-| textColumns | Allow users to set the number of text columns. | `boolean` |  |
+| textColumns | Allow users to set the number of text columns. | `boolean` | `false` |
 | textDecoration | Allow users to set custom text decorations. | `boolean` | `true` |
-| writingMode | Allow users to set the writing mode. | `boolean` |  |
+| writingMode | Allow users to set the writing mode. | `boolean` | `false` |
 | textTransform | Allow users to set custom text transforms. | `boolean` | `true` |
 | dropCap | Enable drop cap. | `boolean` | `true` |
 | fontSizes | Font size presets for the font size selector. | `[ { name, slug, size, fluid } ]` |  |

From cac9d5666f42f41fe416cae460ba2a8e39f4e1f5 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 20:25:35 -0500
Subject: [PATCH 35/43] Lowercase settings and styles

---
 bin/api-docs/gen-theme-reference.mjs                          | 4 ++--
 .../theme-json-reference/theme-json-living.md                 | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index c332ce68f221d..15e93b0b7bf2c 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -157,7 +157,7 @@ function generateDocs( themejson ) {
 	/* --------------- *
 	 * Settings        *
 	 * --------------- */
-	autogen += '## Settings\n\n';
+	autogen += '## settings\n\n';
 	autogen += `${ themejson.properties.settings.description }\n\n`;
 	const settings = themejson.definitions.settingsProperties.allOf.flatMap(
 		( settingsProperties ) =>
@@ -194,7 +194,7 @@ function generateDocs( themejson ) {
 	/* --------------- *
 	 * Styles          *
 	 * --------------- */
-	autogen += '## Styles\n\n';
+	autogen += '## styles\n\n';
 	autogen += `${ themejson.properties.styles.description }\n\n`;
 	const styles = Object.entries(
 		themejson.definitions.stylesProperties.properties
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index 00e12d75684d4..ef5367e579673 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -21,7 +21,7 @@ For example, a schema for WordPress 5.8 is available at <code>https://schemas.wp
 See [Developing with theme.json](/docs/how-to-guides/themes/global-settings-and-styles.md#developing-with-themejson) for how to use the JSON schema in your editor.
 
 <!-- START TOKEN Autogenerated - DO NOT EDIT -->
-## Settings
+## settings
 
 Settings for the block editor and individual blocks. These include things like:
 - Which customization options should be available to the user. 
@@ -204,7 +204,7 @@ Generate custom CSS custom properties of the form `--wp--custom--{key}--{nested-
 
 ---
 
-## Styles
+## styles
 
 Organized way to set CSS properties. Styles in the top-level will be added in the `body` selector.
 

From 708cb8292e9219c398c085a3f39202be167f4ad5 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Tue, 16 Jul 2024 20:27:29 -0500
Subject: [PATCH 36/43] Update strings

---
 bin/api-docs/gen-theme-reference.mjs                        | 6 +++---
 .../theme-json-reference/theme-json-living.md               | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 15e93b0b7bf2c..a24ba154615b8 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -223,7 +223,7 @@ function generateDocs( themejson ) {
 	autogen += '## customTemplates\n\n';
 	autogen += `${ themejson.properties.customTemplates.description }\n\n`;
 	autogen += '| Property | Description | Type |\n';
-	autogen += '| ---      | ---         | ---  |\n';
+	autogen += '| -------- | ----------- | ---- |\n';
 	const customTemplatesProperties = Object.entries(
 		themejson.properties.customTemplates.items.properties
 	);
@@ -240,7 +240,7 @@ function generateDocs( themejson ) {
 	autogen += '## templateParts\n\n';
 	autogen += `${ themejson.properties.templateParts.description }\n\n`;
 	autogen += '| Property | Description | Type |\n';
-	autogen += '| ---      | ---         | ---  |\n';
+	autogen += '| -------- | ----------- | ---- |\n';
 	const templatePartsProperties = Object.entries(
 		themejson.properties.templateParts.items.properties
 	);
@@ -254,7 +254,7 @@ function generateDocs( themejson ) {
 	/* --------------- *
 	 * patterns        *
 	 * --------------- */
-	autogen += '## patterns' + '\n\n';
+	autogen += '## patterns\n\n';
 	autogen += `Type: ${ generateTypes( themejson.properties.patterns ) }.\n\n`;
 	autogen += themejson.properties.patterns.description + '\n';
 
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index ef5367e579673..7e24986b69567 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -334,7 +334,7 @@ Typography styles.
 Additional metadata for custom templates defined in the templates folder.
 
 | Property | Description | Type |
-| ---      | ---         | ---  |
+| -------- | ----------- | ---- |
 | name | Filename, without extension, of the template in the templates folder. | `string` |
 | title | Title of the template, translatable. | `string` |
 | postTypes | List of post types that can use this custom template. | `[ string ]` |
@@ -344,7 +344,7 @@ Additional metadata for custom templates defined in the templates folder.
 Additional metadata for template parts defined in the parts folder.
 
 | Property | Description | Type |
-| ---      | ---         | ---  |
+| -------- | ----------- | ---- |
 | name | Filename, without extension, of the template in the parts folder. | `string` |
 | title | Title of the template, translatable. | `string` |
 | area | The area the template part is used for. Block variations for `header` and `footer` values exist and will be used when the area is set to one of those. | `string` |

From 9e16589e095e92de4ac15001f6d2b4bf4c2d39da Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Wed, 17 Jul 2024 08:08:36 -0500
Subject: [PATCH 37/43] Refactor main

---
 bin/api-docs/gen-theme-reference.mjs | 22 ++++++++--------------
 1 file changed, 8 insertions(+), 14 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index a24ba154615b8..8d5317c4df3be 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -48,14 +48,6 @@ const START_TOKEN = '<!-- START TOKEN Autogenerated - DO NOT EDIT -->';
  */
 const END_TOKEN = '<!-- END TOKEN Autogenerated - DO NOT EDIT -->';
 
-/**
- * Regular expression using tokens for matching in doc file.
- * Note: `.` does not match new lines, so [^] is used.
- *
- * @type {RegExp}
- */
-const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );
-
 /**
  * @typedef {(schema: JSONSchema) => boolean} PredicateFunction
  */
@@ -258,7 +250,7 @@ function generateDocs( themejson ) {
 	autogen += `Type: ${ generateTypes( themejson.properties.patterns ) }.\n\n`;
 	autogen += themejson.properties.patterns.description + '\n';
 
-	return `${ START_TOKEN }\n${ autogen }\n${ END_TOKEN }`;
+	return autogen;
 }
 
 /**
@@ -273,17 +265,19 @@ async function main() {
 		}
 	);
 
-	let docsContent = await fs.readFile( THEME_JSON_REF_DOC, {
+	const content = await fs.readFile( THEME_JSON_REF_DOC, {
 		encoding: 'utf8',
 		flag: 'r',
 	} );
 
-	// Replace auto generated part with new generated docs.
 	const autogen = generateDocs( themejson );
-	docsContent = docsContent.replace( TOKEN_PATTERN, autogen );
+	const newContent = content.replace(
+		// `.` does not match new lines, but `[^]` will.
+		new RegExp( `${ START_TOKEN }[^]*${ END_TOKEN }` ),
+		`${ START_TOKEN }\n${ autogen }\n${ END_TOKEN }`
+	);
 
-	// Write back out.
-	await fs.writeFile( THEME_JSON_REF_DOC, docsContent, { encoding: 'utf8' } );
+	await fs.writeFile( THEME_JSON_REF_DOC, newContent, { encoding: 'utf8' } );
 }
 
 main().catch( ( error ) => {

From f16d36287d077bfef36524c730f7ceec525a0900 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Wed, 17 Jul 2024 08:09:46 -0500
Subject: [PATCH 38/43] Clarify doc comment

---
 bin/api-docs/gen-theme-reference.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 8d5317c4df3be..73666592deea8 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -57,7 +57,7 @@ const END_TOKEN = '<!-- END TOKEN Autogenerated - DO NOT EDIT -->';
  */
 
 /**
- * Create a serializer function for a type. Supports merging anyOf and oneOf subschemas.
+ * Create a serializer function for a type. Supports merging one level of anyOf and oneOf subschemas.
  *
  * @see {@link https://json-schema.org/understanding-json-schema/reference/combining.html}
  *

From 1b91fef3499ba8bc9fddc349648bf1c2a59de30b Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Wed, 17 Jul 2024 08:19:53 -0500
Subject: [PATCH 39/43] Add comment for why one line of description

---
 bin/api-docs/gen-theme-reference.mjs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 73666592deea8..40a808e338e7d 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -199,6 +199,7 @@ function generateDocs( themejson ) {
 			autogen += '| -------- | ----------- | ---- |\n';
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
+				// Assuming that the first line of a description is a summary.
 				const description =
 					subschema.description?.split( '\n', 1 )[ 0 ] ?? '';
 				const types = generateTypes( subschema );

From 99bb337e1f762fd6c3fdc457fa66f36042da3536 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Wed, 17 Jul 2024 08:50:00 -0500
Subject: [PATCH 40/43] Update how top-level only settings are selected and
 rendered

---
 bin/api-docs/gen-theme-reference.mjs          | 26 ++++++++++++-------
 .../theme-json-reference/theme-json-living.md |  2 ++
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 40a808e338e7d..1429aaa0639f6 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -151,16 +151,22 @@ function generateDocs( themejson ) {
 	 * --------------- */
 	autogen += '## settings\n\n';
 	autogen += `${ themejson.properties.settings.description }\n\n`;
-	const settings = themejson.definitions.settingsProperties.allOf.flatMap(
-		( settingsProperties ) =>
-			Object.entries( settingsProperties.properties )
-	);
-	// This property is only available at the root level, so it isn't included in the settingsProperties.
-	settings.unshift( [
-		'useRootPaddingAwareAlignments',
-		themejson.properties.settings.allOf[ 1 ].properties
-			.useRootPaddingAwareAlignments,
-	] );
+	const settings = [
+		// Top-level only properties.
+		...Object.entries( themejson.properties.settings.allOf[ 1 ].properties )
+			.filter( ( [ property ] ) => property !== 'blocks' )
+			.map( ( [ property, subschema ] ) => [
+				property,
+				{
+					...subschema,
+					description: `${ subschema.description }\n\n**Note:** Top-level only property. Not available in blocks.`,
+				},
+			] ),
+		// Top-level and blocks properties.
+		...themejson.properties.settings.allOf[ 0 ].allOf.flatMap(
+			( subschema ) => Object.entries( subschema.properties )
+		),
+	];
 	for ( const [ section, schema ] of settings ) {
 		autogen += `### ${ section }\n\n`;
 		autogen += `${ schema.description }\n\n`;
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index 7e24986b69567..a5285b28f23ca 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -35,6 +35,8 @@ Enables root padding (the values from `styles.spacing.padding`) to be applied to
 
 Please note that when using this setting, `styles.spacing.padding` should always be set as an object with `top`, `right`, `bottom`, `left` values declared separately.
 
+**Note:** Top-level only property. Not available in blocks.
+
 ---
 
 ### appearanceTools

From 292647605bb77b96056c9e684886ea34a4334a86 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Wed, 17 Jul 2024 08:52:00 -0500
Subject: [PATCH 41/43] Select styles directly instead of through definitions

---
 bin/api-docs/gen-theme-reference.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 1429aaa0639f6..4b85bbcc991b3 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -195,7 +195,7 @@ function generateDocs( themejson ) {
 	autogen += '## styles\n\n';
 	autogen += `${ themejson.properties.styles.description }\n\n`;
 	const styles = Object.entries(
-		themejson.definitions.stylesProperties.properties
+		themejson.properties.styles.allOf[ 0 ].properties
 	);
 	for ( const [ section, schema ] of styles ) {
 		autogen += `### ${ section }\n\n`;

From 743cddf13d2a74d5c8954a66aa2d2ec3da20bbe6 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Wed, 17 Jul 2024 09:05:11 -0500
Subject: [PATCH 42/43] Update variable names

---
 bin/api-docs/gen-theme-reference.mjs | 105 ++++++++++++++-------------
 1 file changed, 54 insertions(+), 51 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 4b85bbcc991b3..78dcdc25d0d58 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -19,7 +19,7 @@ import $RefParser from '@apidevtools/json-schema-ref-parser';
  *
  * @type {URL}
  */
-const THEME_JSON_SCHEMA_FILE = new URL(
+const THEME_JSON_SCHEMA_URL = new URL(
 	'../../schemas/json/theme.json',
 	import.meta.url
 );
@@ -29,7 +29,7 @@ const THEME_JSON_SCHEMA_FILE = new URL(
  *
  * @type {URL}
  */
-const THEME_JSON_REF_DOC = new URL(
+const REFERENCE_DOC_URL = new URL(
 	'../../docs/reference-guides/theme-json-reference/theme-json-living.md',
 	import.meta.url
 );
@@ -140,20 +140,21 @@ function generateTypes( schema ) {
 /**
  * Generate documentation from theme.json schema.
  *
- * @param {JSONSchema} themejson JSON schema
+ * @param {JSONSchema} themeJson theme.json JSON schema
  * @return {string} generated documentation
  */
-function generateDocs( themejson ) {
-	let autogen = '';
+function generateDocs( themeJson ) {
+	/** Markdown content. */
+	let md = '';
 
 	/* --------------- *
 	 * Settings        *
 	 * --------------- */
-	autogen += '## settings\n\n';
-	autogen += `${ themejson.properties.settings.description }\n\n`;
+	md += '## settings\n\n';
+	md += `${ themeJson.properties.settings.description }\n\n`;
 	const settings = [
 		// Top-level only properties.
-		...Object.entries( themejson.properties.settings.allOf[ 1 ].properties )
+		...Object.entries( themeJson.properties.settings.allOf[ 1 ].properties )
 			.filter( ( [ property ] ) => property !== 'blocks' )
 			.map( ( [ property, subschema ] ) => [
 				property,
@@ -163,16 +164,16 @@ function generateDocs( themejson ) {
 				},
 			] ),
 		// Top-level and blocks properties.
-		...themejson.properties.settings.allOf[ 0 ].allOf.flatMap(
+		...themeJson.properties.settings.allOf[ 0 ].allOf.flatMap(
 			( subschema ) => Object.entries( subschema.properties )
 		),
 	];
 	for ( const [ section, schema ] of settings ) {
-		autogen += `### ${ section }\n\n`;
-		autogen += `${ schema.description }\n\n`;
+		md += `### ${ section }\n\n`;
+		md += `${ schema.description }\n\n`;
 		if ( schema.properties ) {
-			autogen += '| Property | Description | Type | Default |\n';
-			autogen += '| -------- | ----------- | ---- | ------- |\n';
+			md += '| Property | Description | Type | Default |\n';
+			md += '| -------- | ----------- | ---- | ------- |\n';
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
 				const description =
@@ -182,109 +183,111 @@ function generateDocs( themejson ) {
 					'default' in subschema
 						? `\`${ JSON.stringify( subschema.default ) }\``
 						: '';
-				autogen += `| ${ property } | ${ description } | ${ types } | ${ defaultValue } |\n`;
+				md += `| ${ property } | ${ description } | ${ types } | ${ defaultValue } |\n`;
 			}
-			autogen += '\n';
+			md += '\n';
 		}
-		autogen += `---\n\n`;
+		md += `---\n\n`;
 	}
 
 	/* --------------- *
 	 * Styles          *
 	 * --------------- */
-	autogen += '## styles\n\n';
-	autogen += `${ themejson.properties.styles.description }\n\n`;
+	md += '## styles\n\n';
+	md += `${ themeJson.properties.styles.description }\n\n`;
 	const styles = Object.entries(
-		themejson.properties.styles.allOf[ 0 ].properties
+		themeJson.properties.styles.allOf[ 0 ].properties
 	);
 	for ( const [ section, schema ] of styles ) {
-		autogen += `### ${ section }\n\n`;
-		autogen += `${ schema.description }\n\n`;
+		md += `### ${ section }\n\n`;
+		md += `${ schema.description }\n\n`;
 		if ( schema.properties ) {
-			autogen += '| Property | Description | Type |\n';
-			autogen += '| -------- | ----------- | ---- |\n';
+			md += '| Property | Description | Type |\n';
+			md += '| -------- | ----------- | ---- |\n';
 			const properties = Object.entries( schema.properties );
 			for ( const [ property, subschema ] of properties ) {
 				// Assuming that the first line of a description is a summary.
 				const description =
 					subschema.description?.split( '\n', 1 )[ 0 ] ?? '';
 				const types = generateTypes( subschema );
-				autogen += `| ${ property } | ${ description } | ${ types } |\n`;
+				md += `| ${ property } | ${ description } | ${ types } |\n`;
 			}
-			autogen += '\n';
+			md += '\n';
 		}
-		autogen += `---\n\n`;
+		md += `---\n\n`;
 	}
 
 	/* --------------- *
 	 * customTemplates *
 	 * --------------- */
-	autogen += '## customTemplates\n\n';
-	autogen += `${ themejson.properties.customTemplates.description }\n\n`;
-	autogen += '| Property | Description | Type |\n';
-	autogen += '| -------- | ----------- | ---- |\n';
+	md += '## customTemplates\n\n';
+	md += `${ themeJson.properties.customTemplates.description }\n\n`;
+	md += '| Property | Description | Type |\n';
+	md += '| -------- | ----------- | ---- |\n';
 	const customTemplatesProperties = Object.entries(
-		themejson.properties.customTemplates.items.properties
+		themeJson.properties.customTemplates.items.properties
 	);
 	for ( const [ property, subschema ] of customTemplatesProperties ) {
 		const { description } = subschema;
 		const types = generateTypes( subschema );
-		autogen += `| ${ property } | ${ description } | ${ types } |\n`;
+		md += `| ${ property } | ${ description } | ${ types } |\n`;
 	}
-	autogen += '\n';
+	md += '\n';
 
 	/* --------------- *
 	 * templateParts   *
 	 * --------------- */
-	autogen += '## templateParts\n\n';
-	autogen += `${ themejson.properties.templateParts.description }\n\n`;
-	autogen += '| Property | Description | Type |\n';
-	autogen += '| -------- | ----------- | ---- |\n';
+	md += '## templateParts\n\n';
+	md += `${ themeJson.properties.templateParts.description }\n\n`;
+	md += '| Property | Description | Type |\n';
+	md += '| -------- | ----------- | ---- |\n';
 	const templatePartsProperties = Object.entries(
-		themejson.properties.templateParts.items.properties
+		themeJson.properties.templateParts.items.properties
 	);
 	for ( const [ property, subschema ] of templatePartsProperties ) {
 		const { description } = subschema;
 		const types = generateTypes( subschema );
-		autogen += `| ${ property } | ${ description } | ${ types } |\n`;
+		md += `| ${ property } | ${ description } | ${ types } |\n`;
 	}
-	autogen += '\n';
+	md += '\n';
 
 	/* --------------- *
 	 * patterns        *
 	 * --------------- */
-	autogen += '## patterns\n\n';
-	autogen += `Type: ${ generateTypes( themejson.properties.patterns ) }.\n\n`;
-	autogen += themejson.properties.patterns.description + '\n';
+	md += '## patterns\n\n';
+	md += `Type: ${ generateTypes( themeJson.properties.patterns ) }.\n\n`;
+	md += themeJson.properties.patterns.description + '\n';
 
-	return autogen;
+	return md;
 }
 
 /**
  * Main function.
  */
 async function main() {
-	const themejson = await $RefParser.dereference(
-		THEME_JSON_SCHEMA_FILE.pathname,
+	const themeJson = await $RefParser.dereference(
+		THEME_JSON_SCHEMA_URL.pathname,
 		{
 			parse: { binary: false, text: false, yaml: false },
 			resolve: { external: false },
 		}
 	);
 
-	const content = await fs.readFile( THEME_JSON_REF_DOC, {
+	const themeJsonReference = await fs.readFile( REFERENCE_DOC_URL, {
 		encoding: 'utf8',
 		flag: 'r',
 	} );
 
-	const autogen = generateDocs( themejson );
-	const newContent = content.replace(
+	const generatedDocs = generateDocs( themeJson );
+	const updatedThemeJsonReference = themeJsonReference.replace(
 		// `.` does not match new lines, but `[^]` will.
 		new RegExp( `${ START_TOKEN }[^]*${ END_TOKEN }` ),
-		`${ START_TOKEN }\n${ autogen }\n${ END_TOKEN }`
+		`${ START_TOKEN }\n${ generatedDocs }\n${ END_TOKEN }`
 	);
 
-	await fs.writeFile( THEME_JSON_REF_DOC, newContent, { encoding: 'utf8' } );
+	await fs.writeFile( REFERENCE_DOC_URL, updatedThemeJsonReference, {
+		encoding: 'utf8',
+	} );
 }
 
 main().catch( ( error ) => {

From 8c2c1019924be79eac0244add51bfc27b352fb70 Mon Sep 17 00:00:00 2001
From: Alex Lende <alex+github.com@lende.xyz>
Date: Wed, 17 Jul 2024 10:49:02 -0500
Subject: [PATCH 43/43] Reorder patterns type in docs

---
 bin/api-docs/gen-theme-reference.mjs                          | 4 ++--
 .../theme-json-reference/theme-json-living.md                 | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs
index 78dcdc25d0d58..6dc7791e288b9 100644
--- a/bin/api-docs/gen-theme-reference.mjs
+++ b/bin/api-docs/gen-theme-reference.mjs
@@ -255,8 +255,8 @@ function generateDocs( themeJson ) {
 	 * patterns        *
 	 * --------------- */
 	md += '## patterns\n\n';
-	md += `Type: ${ generateTypes( themeJson.properties.patterns ) }.\n\n`;
-	md += themeJson.properties.patterns.description + '\n';
+	md += themeJson.properties.patterns.description + '\n\n';
+	md += `Type: ${ generateTypes( themeJson.properties.patterns ) }.\n`;
 
 	return md;
 }
diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md
index a5285b28f23ca..95f2e047dd0e3 100644
--- a/docs/reference-guides/theme-json-reference/theme-json-living.md
+++ b/docs/reference-guides/theme-json-reference/theme-json-living.md
@@ -353,8 +353,8 @@ Additional metadata for template parts defined in the parts folder.
 
 ## patterns
 
-Type: `[ string ]`.
-
 An array of pattern slugs to be registered from the Pattern Directory.
 
+Type: `[ string ]`.
+
 <!-- END TOKEN Autogenerated - DO NOT EDIT -->