Components: Prevent broken lists in auto-generated readmes (#68301)

* Components: Prevent broken lists in auto-generated readmes * Re-generate readmes * Simplify and document md converter Co-authored-by: mirka <[email protected]> Co-authored-by: tyxla <[email protected]>
WordPress · Dec 26, 2024 · 5af740f · 5af740f · github-actions · Dec 26, 2024
1 parent d1c9d76
commit 5af740f
Show file tree

Hide file tree

Showing 12 changed files with 240 additions and 244 deletions.
diff --git a/bin/api-docs/gen-components-docs/markdown/index.mjs b/bin/api-docs/gen-components-docs/markdown/index.mjs
@@ -9,17 +9,14 @@ 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`.
+ * Converter for strings that are already formatted as Markdown.
  *
- * @param {string} [str]
+ * @param {string} [input]
+ * @return {string} The trimmed input if it is contentful, otherwise an empty string.
  */
-function normalizeTrailingNewline( str ) {
-	if ( ! str?.trim() ) {
-		return undefined;
-	}
-	return str.replace( /\n*$/, '\n' );
-}
+json2md.converters.md = ( input ) => {
+	return input?.trim() || '';
+};
 
 export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 	const mainDocsJson = [
@@ -28,7 +25,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 +36,7 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 					{
 						h3: subcomponentTypeDoc.displayName,
 					},
-					normalizeTrailingNewline( subcomponentTypeDoc.description ),
+					{ md: subcomponentTypeDoc.description },
 					...generateMarkdownPropsJson( subcomponentTypeDoc.props, {
 						headingLevel: 4,
 					} ),
@@ -49,5 +46,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 );

diff --git a/packages/components/src/alignment-matrix-control/README.md b/packages/components/src/alignment-matrix-control/README.md
@@ -26,43 +26,43 @@ const Example = () => {
 
 ### `defaultValue`
 
-If provided, sets the default alignment value.
-
  - Type: `"center" | "top left" | "top center" | "top right" | "center left" | "center center" | "center right" | "bottom left" | "bottom center" | "bottom right"`
  - Required: No
  - Default: `'center center'`
 
-### `label`
+If provided, sets the default alignment value.
 
-Accessible label. If provided, sets the `aria-label` attribute of the
-underlying `grid` widget.
+### `label`
 
  - Type: `string`
  - Required: No
  - Default: `'Alignment Matrix Control'`
 
-### `onChange`
+Accessible label. If provided, sets the `aria-label` attribute of the
+underlying `grid` widget.
 
-A function that receives the updated alignment value.
+### `onChange`
 
  - Type: `(newValue: AlignmentMatrixControlValue) => void`
  - Required: No
 
-### `value`
+A function that receives the updated alignment value.
 
-The current alignment value.
+### `value`
 
  - Type: `"center" | "top left" | "top center" | "top right" | "center left" | "center center" | "center right" | "bottom left" | "bottom center" | "bottom right"`
  - Required: No
 
-### `width`
+The current alignment value.
 
-If provided, sets the width of the control.
+### `width`
 
  - Type: `number`
  - Required: No
  - Default: `92`
 
+If provided, sets the width of the control.
+
 ## Subcomponents
 
 ### AlignmentMatrixControl.Icon
@@ -71,16 +71,16 @@ If provided, sets the width of the control.
 
 ##### `disablePointerEvents`
 
-If `true`, disables pointer events on the icon.
-
  - Type: `boolean`
  - Required: No
  - Default: `true`
 
-##### `value`
+If `true`, disables pointer events on the icon.
 
-The current alignment value.
+##### `value`
 
  - Type: `"center" | "top left" | "top center" | "top right" | "center left" | "center center" | "center right" | "bottom left" | "bottom center" | "bottom right"`
  - Required: No
  - Default: `center`
+
+The current alignment value.
diff --git a/packages/components/src/angle-picker-control/README.md b/packages/components/src/angle-picker-control/README.md
@@ -28,30 +28,30 @@ function Example() {
 
 ### `as`
 
-The HTML element or React component to render the component as.
-
  - Type: `"symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | ...`
  - Required: No
 
-### `label`
+The HTML element or React component to render the component as.
 
-Label to use for the angle picker.
+### `label`
 
  - Type: `string`
  - Required: No
  - Default: `__( 'Angle' )`
 
-### `onChange`
+Label to use for the angle picker.
 
-A function that receives the new value of the input.
+### `onChange`
 
  - Type: `(value: number) => void`
  - Required: Yes
 
-### `value`
+A function that receives the new value of the input.
 
-The current value of the input. The value represents an angle in degrees
-and should be a value between 0 and 360.
+### `value`
 
  - Type: `string | number`
  - Required: Yes
+
+The current value of the input. The value represents an angle in degrees
+and should be a value between 0 and 360.
diff --git a/packages/components/src/badge/README.md b/packages/components/src/badge/README.md
@@ -8,15 +8,15 @@
 
 ### `children`
 
-Text to display inside the badge.
-
  - Type: `string`
  - Required: Yes
 
-### `intent`
+Text to display inside the badge.
 
-Badge variant.
+### `intent`
 
  - Type: `"default" | "info" | "success" | "warning" | "error"`
  - Required: No
  - Default: `default`
+
+Badge variant.
diff --git a/packages/components/src/base-control/README.md b/packages/components/src/base-control/README.md
@@ -30,67 +30,66 @@ const MyCustomTextareaControl = ({ children, ...baseProps }) => (
 
 ### `__nextHasNoMarginBottom`
 
-Start opting into the new margin-free styles that will become the default in a future version.
-
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
-### `as`
+Start opting into the new margin-free styles that will become the default in a future version.
 
-The HTML element or React component to render the component as.
+### `as`
 
  - Type: `"symbol" | "object" | "label" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 516 more ... | ("view" & FunctionComponent<...>)`
  - Required: No
 
-### `className`
+The HTML element or React component to render the component as.
 
+### `className`
 
  - Type: `string`
  - Required: No
 
 ### `children`
 
-The content to be displayed within the `BaseControl`.
-
  - Type: `ReactNode`
  - Required: Yes
 
+The content to be displayed within the `BaseControl`.
+
 ### `help`
 
+ - Type: `ReactNode`
+ - Required: No
+
 Additional description for the control.
 
 Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an `aria-describedby` attribute.
 
- - Type: `ReactNode`
- - Required: No
-
 ### `hideLabelFromVision`
 
-If true, the label will only be visible to screen readers.
-
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
+If true, the label will only be visible to screen readers.
+
 ### `id`
 
+ - Type: `string`
+ - Required: No
+
 The HTML `id` of the control element (passed in as a child to `BaseControl`) to which labels and help text are being generated.
 This is necessary to accessibly associate the label with that element.
 
 The recommended way is to use the `useBaseControlProps` hook, which takes care of generating a unique `id` for you.
 Otherwise, if you choose to pass an explicit `id` to this prop, you are responsible for ensuring the uniqueness of the `id`.
 
- - Type: `string`
- - Required: No
-
 ### `label`
 
-If this property is added, a label will be generated using label property as the content.
-
  - Type: `ReactNode`
  - Required: No
 
+If this property is added, a label will be generated using label property as the content.
+
 ## Subcomponents
 
 ### BaseControl.VisualLabel
@@ -119,14 +118,14 @@ const MyBaseControl = () => (
 
 ##### `as`
 
-The HTML element or React component to render the component as.
-
  - Type: `"symbol" | "object" | "label" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | ...`
  - Required: No
 
-##### `children`
+The HTML element or React component to render the component as.
 
-The content to be displayed within the `BaseControl.VisualLabel`.
+##### `children`
 
  - Type: `ReactNode`
  - Required: Yes
+
+The content to be displayed within the `BaseControl.VisualLabel`.