Components: Prevent broken lists in auto-generated readmes #68301
Conversation
mirka
added
[Type] Developer Documentation
|
Flaky tests detected in 4690b1d. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/12503550187
|
| json2md.converters.md = ( input ) => { | ||
| return input?.trim() || ''; | ||
| }; |
There was a problem hiding this comment.
I realized you can add custom converters like this, which makes things more simpler and readable overall. When you use a converter, json2md adds a trailing newline automatically.
The removal of redundant newlines is moved to the end of this file, which will clean the entire output.
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
| json2md.converters.md = ( input ) => { | ||
| return input?.trim() || ''; | ||
| }; |
| @@ -49,5 +46,5 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) { | |||
|
|
|||
| return json2md( | |||
| [ ...mainDocsJson, ...subcomponentDocsJson ].filter( Boolean ) | |||
| ); | |||
| ).replace( /\n+$/gm, '\n' ); // clean unnecessary consecutive newlines | |||
There was a problem hiding this comment.
Noting that this cleans up only trailing ones, maybe we want to update the comment to reflect that?
There was a problem hiding this comment.
This is a global + multiline regex, intended to remove all excessive newlines within in the entire readme output.
What?
Prevents broken lists (
ul) in the auto-generated component READMEs, by inverting the order of the "prop data"uland the prop description.Why?
Because we can assume that a prop description will always start with a paragraph (not
ul), flipping the order here should solve the "ambiguous run-on list" problem when the prop description ends with a list.Before
The ambiguously separated Markdown lists will render unreliably, depending on the HTML converter implementation.
After
Now the lists are clearly separated.
Testing Instructions
The READMEs re-generated by
npm run docs:componentsdo not include ambiguous lists, even when a prop description ends with a list.