Markdown documentation generation: do not insert line breaks #1879
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
The code generating markdown documentation from a Nickel configuration used to unconditionally insert hard line breaks between a field's signature and the rest of its documentation. However, one can't insert a hard line break immediately followed by a blocks in commonmark (or put differently: it's not representable as a source), and those line breaks were just rendered as spurious backslashes at best, or sometimes interpreted differently (see #1706 for more details). A bit of experimentation showed that what comes after this line break is always a block in the sense of commonmark (even when it's simple documentation text, it's wrapped as a Markdown paragraph). Thus this commit just removes the line break altogether, which is not useful and never legal anyway.
vkleen
approved these changes
Apr 3, 2024
thufschmitt
approved these changes
Apr 3, 2024
|
Doesn't this regress the example in #1520? |
|
Argh, that's a good point. That being said, I feel this time this is really a comrak issue: it should insert a newline between a list and the following block, but it doesn't. @jneem if you have a branch with the latest comrak, could you see if this has changed in the latest version? Otherwise another solution (which I actually implemented initially) is to check if the next element is a paragraph manually, and insert the hard line only in this case. It's not too hard, but just doesn't feel right after having read the commonmark spec. |
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.
Fixes #1706.
The code generating markdown documentation from a Nickel configuration used to unconditionally insert hard line breaks between a field's signature and the rest of its documentation. However, one can't insert a hard line break immediately followed by a blocks in commonmark (or put differently: it's not representable as a source), and those line breaks were just rendered as spurious backslashes at best, or sometimes interpreted differently (see #1706 for more details).
A bit of experimentation showed that what comes after this line break is always a block in the sense of commonmark (even when it's simple documentation text, it's wrapped as a Markdown paragraph). Thus this PR just removes the line break altogether, which is not useful and never legal anyway.