Escape raw rule documentation text for HTML #326
Merged
Conversation
This file contains hidden or 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
Some the rule config text is intended for use in both tool output and in the reference, so can't be formatted at the source as the Markdown consumed by the MkDocs website generation system. This raw text may contain incidental Markdown markup, which would result in it being incorrectly rendered in the website, so it must be escaped. Despite much searching at the time the rule documentation website generation system was created, I could not find a good Go package for Markdown escaping of text. I did find an excellent package for Markdown escaping of HTML, and so I used that instead. However, this is not sufficient to completely escape the text. The reason is that Markdown is a partial superset of HTML. The `github.com/JohannesKaufmann/html-to-markdown/escape` package intentionally does not escape HTML. So it is necessary to do HTML escaping of the raw text in addition to Markdown escaping. HTML escaping was not done previously, which resulted in raw text which incidentally had the angle bracket enclosed form of HTML tags not being rendered in the website. For example, the "brief" text of rule PF009: ``` use of compiler.<pattern type>.extra_flags ``` was rendered as: ``` use of compiler..extra_flags ``` The raw text is now escaped both for HTML and for Markdown during the generation of the rule documentation website content.
per1234
added
topic: infrastructure
Codecov Report
@@ Coverage Diff @@
## main #326 +/- ##
=======================================
Coverage 90.01% 90.01%
=======================================
Files 44 44
Lines 6770 6770
=======================================
Hits 6094 6094
Misses 553 553
Partials 123 123
Flags with carried forward coverage won't be shown. Click here to find out more.
Continue to review full report at Codecov.
|
silvanocerza
approved these changes
Jan 19, 2022
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.
Some the rule config text is intended for use in both tool output and in the reference, so can't be formatted at the source as the Markdown consumed by the MkDocs website generation system.
This raw text may contain incidental Markdown markup, which would result in it being incorrectly rendered in the website, so it must be escaped. Despite much searching at the time the rule documentation website generation system was created, I could not find a good Go package for Markdown escaping of text. I did find an excellent package for Markdown escaping of HTML, and so I used that instead.
However, this is not sufficient to completely escape the text. The reason is that Markdown is a partial superset of HTML. The
github.com/JohannesKaufmann/html-to-markdown/escapepackage intentionally does not escape HTML. So it is necessary to do HTML escaping of the raw text in addition to Markdown escaping.HTML escaping was not done previously, which resulted in raw text which incidentally had the angle bracket enclosed form of HTML tags not being rendered in the website.
For example, the "brief" text of rule PF009:
was rendered as:
The raw text is now escaped both for HTML and for Markdown during the generation of the rule documentation website content.