[Fix] Nickel doc: fix missing newline in markdown output #1880
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
A recent commit fixed the `nickel doc` markdown output having spurious backslashes introduced. However, it also re-introduced a previous issue - which was why the problematic hard line breaks were introduced in the first place - which is that the list of types and contracts of a field and the custom documentation might be squashed together because the renderer wouldn't properly insert a newline after the generated list. After some investigation, it seems to be a bug in the comrak renderer. However, this bug doesn't show when the markdown is parsed from an actual source (instead of being programmatically generated). It turns out comrak correctly inserting this required newline relies on the unspoken assumption that every markdown list item content is wrapped as a paragraph. This commit thus fixes the issue by inserting the missing paragraph wrapper.
jneem
approved these changes
Apr 3, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
#1879 fixed
nickel docmarkdown output having spurious backslashes (#1706). However, #1879 also re-introduced a previous issue - which was why the removed hard line breaks was introduced in the first place - which is that the list of types and contracts of a field and the custom documentation might be squashed together because the renderer wouldn't properly insert a newline after the generated list (#1520).After some investigation, it seems to be a bug in the comrak renderer. However, this bug doesn't show when the markdown is parsed from an actual source (instead of being programmatically generated). It turns out comrak correctly inserting this required newline relies on the unspoken assumption that every markdown list item content is wrapped as a paragraph. This commit thus fixes the issue by inserting the missing paragraph wrapper.