Components: Prevent broken lists in auto-generated readmes

WordPress · Dec 25, 2024 · cce06a5 · cce06a5
1 parent 887243c
commit cce06a5
Show file tree

Hide file tree

Showing 2 changed files with 7 additions and 16 deletions.
diff --git a/bin/api-docs/gen-components-docs/markdown/index.mjs b/bin/api-docs/gen-components-docs/markdown/index.mjs
@@ -8,18 +8,9 @@ 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 ) {
-	if ( ! str?.trim() ) {
-		return undefined;
-	}
-	return str.replace( /\n*$/, '\n' );
-}
+json2md.converters.md = ( input ) => {
+	return input?.trim() ? input : '';
+};
 
 export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 	const mainDocsJson = [
@@ -28,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>`,
 		},
-		normalizeTrailingNewline( typeDocs.description ),
+		{ md: typeDocs.description },
 		...generateMarkdownPropsJson( typeDocs.props ),
 	];
 
@@ -39,7 +30,7 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 					{
 						h3: subcomponentTypeDoc.displayName,
 					},
-					normalizeTrailingNewline( subcomponentTypeDoc.description ),
+					{ md: subcomponentTypeDoc.description },
 					...generateMarkdownPropsJson( subcomponentTypeDoc.props, {
 						headingLevel: 4,
 					} ),
@@ -49,5 +40,5 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 
 	return json2md(
 		[ ...mainDocsJson, ...subcomponentDocsJson ].filter( Boolean )
-	);
+	).replace( /\n+$/gm, '\n' ); // clean unnecessary consecutive newlines
 }
diff --git a/bin/api-docs/gen-components-docs/markdown/props.mjs b/bin/api-docs/gen-components-docs/markdown/props.mjs
@@ -33,7 +33,6 @@ export function generateMarkdownPropsJson( props, { headingLevel = 2 } = {} ) {
 
 			return [
 				{ [ `h${ headingLevel + 1 }` ]: `\`${ key }\`` },
-				prop.description,
 				{
 					ul: [
 						`Type: \`${ renderPropType( prop.type ) }\``,
@@ -42,6 +41,7 @@ export function generateMarkdownPropsJson( props, { headingLevel = 2 } = {} ) {
 							`Default: \`${ prop.defaultValue.value }\``,
 					].filter( Boolean ),
 				},
+				{ md: prop.description },
 			];
 		} )
 		.filter( Boolean );