From 869d26bebdb7d39f2cba51b13a7187e8f5f15814 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Sat, 21 Dec 2024 02:29:36 +0900
Subject: [PATCH 1/2] Components: Normalize newlines

---
 bin/api-docs/gen-components-docs/markdown/index.mjs       | 8 ++++++--
 .../components/src/alignment-matrix-control/README.md     | 1 +
 packages/components/src/angle-picker-control/README.md    | 1 +
 packages/components/src/base-control/README.md            | 2 ++
 packages/components/src/box-control/README.md             | 1 +
 packages/components/src/button/README.md                  | 1 +
 packages/components/src/form-file-upload/README.md        | 1 +
 packages/components/src/gradient-picker/README.md         | 1 +
 packages/components/src/icon/README.md                    | 1 +
 packages/components/src/tree-select/README.md             | 1 +
 10 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/bin/api-docs/gen-components-docs/markdown/index.mjs b/bin/api-docs/gen-components-docs/markdown/index.mjs
index 126fdf0057b6e..8fd61a25fcace 100644
--- a/bin/api-docs/gen-components-docs/markdown/index.mjs
+++ b/bin/api-docs/gen-components-docs/markdown/index.mjs
@@ -8,6 +8,10 @@ import json2md from 'json2md';
  */
 import { generateMarkdownPropsJson } from './props.mjs';
 
+function normalizeTrailingNewline( str ) {
+	return str?.length ? str.replace( /\n*$/, '\n' ) : undefined;
+}
+
 export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 	const mainDocsJson = [
 		{ h1: typeDocs.displayName },
@@ -15,7 +19,7 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 		{
 			p: `<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-${ typeDocs.displayName.toLowerCase() }--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>`,
 		},
-		typeDocs.description,
+		normalizeTrailingNewline( typeDocs.description ),
 		...generateMarkdownPropsJson( typeDocs.props ),
 	];
 
@@ -26,7 +30,7 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 					{
 						h3: subcomponentTypeDoc.displayName,
 					},
-					subcomponentTypeDoc.description,
+					normalizeTrailingNewline( subcomponentTypeDoc.description ),
 					...generateMarkdownPropsJson( subcomponentTypeDoc.props, {
 						headingLevel: 4,
 					} ),
diff --git a/packages/components/src/alignment-matrix-control/README.md b/packages/components/src/alignment-matrix-control/README.md
index af97e3ae0607c..267b368454c49 100644
--- a/packages/components/src/alignment-matrix-control/README.md
+++ b/packages/components/src/alignment-matrix-control/README.md
@@ -21,6 +21,7 @@ const Example = () => {
 	);
 };
 ```
+
 ## Props
 
 ### `defaultValue`
diff --git a/packages/components/src/angle-picker-control/README.md b/packages/components/src/angle-picker-control/README.md
index d9389c6564338..8b98ba813adde 100644
--- a/packages/components/src/angle-picker-control/README.md
+++ b/packages/components/src/angle-picker-control/README.md
@@ -23,6 +23,7 @@ function Example() {
   );
 }
 ```
+
 ## Props
 
 ### `as`
diff --git a/packages/components/src/base-control/README.md b/packages/components/src/base-control/README.md
index 839464b41260b..9c8920fbc0689 100644
--- a/packages/components/src/base-control/README.md
+++ b/packages/components/src/base-control/README.md
@@ -25,6 +25,7 @@ const MyCustomTextareaControl = ({ children, ...baseProps }) => (
 	);
 );
 ```
+
 ## Props
 
 ### `__nextHasNoMarginBottom`
@@ -113,6 +114,7 @@ const MyBaseControl = () => (
 	</BaseControl>
 );
 ```
+
 #### Props
 
 ##### `as`
diff --git a/packages/components/src/box-control/README.md b/packages/components/src/box-control/README.md
index da08cafceee42..6192cfa47367b 100644
--- a/packages/components/src/box-control/README.md
+++ b/packages/components/src/box-control/README.md
@@ -28,6 +28,7 @@ function Example() {
   );
 };
 ```
+
 ## Props
 
 ### `__next40pxDefaultSize`
diff --git a/packages/components/src/button/README.md b/packages/components/src/button/README.md
index 99a6d0f9c24cf..d63dee9007c2f 100644
--- a/packages/components/src/button/README.md
+++ b/packages/components/src/button/README.md
@@ -17,6 +17,7 @@ const Mybutton = () => (
   </Button>
 );
 ```
+
 ## Props
 
 ### `__next40pxDefaultSize`
diff --git a/packages/components/src/form-file-upload/README.md b/packages/components/src/form-file-upload/README.md
index c6a7205815de5..d281b1ca63927 100644
--- a/packages/components/src/form-file-upload/README.md
+++ b/packages/components/src/form-file-upload/README.md
@@ -19,6 +19,7 @@ const MyFormFileUpload = () => (
   </FormFileUpload>
 );
 ```
+
 ## Props
 
 ### `__next40pxDefaultSize`
diff --git a/packages/components/src/gradient-picker/README.md b/packages/components/src/gradient-picker/README.md
index ec0210d03c0a4..652fcbf30ae13 100644
--- a/packages/components/src/gradient-picker/README.md
+++ b/packages/components/src/gradient-picker/README.md
@@ -43,6 +43,7 @@ const MyGradientPicker = () => {
   );
 };
 ```
+
 ## Props
 
 ### `__experimentalIsRenderedInSidebar`
diff --git a/packages/components/src/icon/README.md b/packages/components/src/icon/README.md
index 63d52c1fd20b1..29e621f80c1fd 100644
--- a/packages/components/src/icon/README.md
+++ b/packages/components/src/icon/README.md
@@ -11,6 +11,7 @@ import { wordpress } from '@wordpress/icons';
 
 <Icon icon={ wordpress } />
 ```
+
 ## Props
 
 ### `icon`
diff --git a/packages/components/src/tree-select/README.md b/packages/components/src/tree-select/README.md
index 493c83bf993b0..5f3247bdb3322 100644
--- a/packages/components/src/tree-select/README.md
+++ b/packages/components/src/tree-select/README.md
@@ -51,6 +51,7 @@ const MyTreeSelect = () => {
 	);
 }
 ```
+
 ## Props
 
 ### `__next40pxDefaultSize`

From e5e4a65fcd86234150a29a365187d6ed9cfaa908 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Sat, 21 Dec 2024 03:24:18 +0900
Subject: [PATCH 2/2] Clarify helper function

---
 bin/api-docs/gen-components-docs/markdown/index.mjs | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/bin/api-docs/gen-components-docs/markdown/index.mjs b/bin/api-docs/gen-components-docs/markdown/index.mjs
index 8fd61a25fcace..5978e7e80fe26 100644
--- a/bin/api-docs/gen-components-docs/markdown/index.mjs
+++ b/bin/api-docs/gen-components-docs/markdown/index.mjs
@@ -8,8 +8,17 @@ import json2md from 'json2md';
  */
 import { generateMarkdownPropsJson } from './props.mjs';
 
+/**
+ * If the string is contentful, ensure that it ends with a single newline.
+ * Otherwise normalize to `undefined`.
+ *
+ * @param {string} [str]
+ */
 function normalizeTrailingNewline( str ) {
-	return str?.length ? str.replace( /\n*$/, '\n' ) : undefined;
+	if ( ! str?.trim() ) {
+		return undefined;
+	}
+	return str.replace( /\n*$/, '\n' );
 }
 
 export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {