From 34a58846988fd884e9c8d23eb31fbeb0cafa4f5a Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Thu, 16 May 2024 17:42:00 -0400 Subject: [PATCH] Strip HTML comments within Markdown rendering (#50523) Co-authored-by: Rachael Sewell --- .../using-the-content-linter.md | 38 ++++++++------- .../basic-writing-and-formatting-syntax.md | 8 ++-- .../quickstart-for-writing-on-github.md | 12 ++--- package-lock.json | 47 +++++++++++++++++-- package.json | 2 +- src/content-linter/scripts/lint-content.js | 3 ++ src/content-render/liquid/index.js | 2 - src/content-render/liquid/pre.js | 13 ----- src/content-render/tests/render-content.js | 39 --------------- src/content-render/unified/processor.js | 2 + .../get-started/markdown/html-comments.md | 38 +++++++++++++++ .../content/get-started/markdown/index.md | 1 + src/fixtures/tests/html-comments.js | 16 +++++++ 13 files changed, 134 insertions(+), 87 deletions(-) delete mode 100644 src/content-render/liquid/pre.js create mode 100644 src/fixtures/fixtures/content/get-started/markdown/html-comments.md create mode 100644 src/fixtures/tests/html-comments.js diff --git a/content/contributing/collaborating-on-github-docs/using-the-content-linter.md b/content/contributing/collaborating-on-github-docs/using-the-content-linter.md index 2eda0687d1..aa42be9888 100644 --- a/content/contributing/collaborating-on-github-docs/using-the-content-linter.md +++ b/content/contributing/collaborating-on-github-docs/using-the-content-linter.md @@ -118,12 +118,16 @@ Some linting rules return warnings or errors based on HTML comments that you can Rules `GHD038` and `GHD039` check for content that has been manually given an expiration date. Fourteen days before the specified date, the content linter will return a warning that the content is expiring soon. Starting on the specified date, the content linter will return an error and flag the content for remediation. -You can add an expiration date to content by wrapping it in HTML tags that contain an expiration date in the format: 
<!-- expires yyyy-mm-dd --> <!-- end expires yyyy-mm-dd -->
+You can add an expiration date to content by wrapping it in HTML tags that contain an expiration date in the format: ` ` **Use:** ```markdown -This content does not expire. {% raw %}<{% endraw %}!-- expires 2022-01-28 -->This content expires on January 28, 2022. {% raw %}<{% endraw %}!-- end expires 2022-01-28 -->This content also does not expire. +This content does not expire. + +This content expires on January 28, 2022. + +This content also does not expire. ``` ## Suppressing linter rules @@ -133,19 +137,19 @@ Rarely, you may need to document something that violates one or more linter rule For example, if you are writing an article that includes the regular expression `(^|/)[Cc]+odespace/` that checks for reversed link syntax, it will trigger the `MD011` rule that checks for reversed links. You can disable the rule `MD011` on that specific line by adding the following comment. -
-(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->
-
+```text +(^|/)[Cc]+odespace/ +``` If the line you're trying to ignore is in a code block, you can ignore the code block by surrounding it with the following comments. -
-<!-- markdownlint-disable MD011 -->
+````text
+
 ```
 (^|/)[Cc]+odespace/
 ```
-<!-- markdownlint-enable MD011 -->
-
+ +```` @@ -153,11 +157,11 @@ You can use these comments to enable or disable rules. | Comment | Effect | | :-- | :-- | -| 
<!-- markdownlint-disable -->
| Disable all rules | -| 
<!-- markdownlint-enable -->
| Enable all rules | -| 
<!-- markdownlint-disable-line -->
| Disable all rules for the current line | -| 
<!-- markdownlint-disable-next-line -->
| Disable all rules for the next line | -| 
<!-- markdownlint-disable RULE-ONE RULE-TWO -->
| Disable one or more rules by name | -| 
<!-- markdownlint-enable RULE-ONE RULE-TWO -->
| Enable one or more rules by name | -| 
<!-- markdownlint-disable-line RULE-NAME -->
| Disable one or more rules by name for the current line | -| 
<!-- markdownlint-disable-next-line RULE-NAME -->
| Disable one or more rules by name for the next line | +| `` | Disable all rules | +| ``| Enable all rules | +| `` | Disable all rules for the current line | +| `` | Disable all rules for the next line | +| ``| | Disable one or more rules by name | +| `` | Enable one or more rules by name | +| `` | Disable one or more rules by name for the current line | +| `` | Disable one or more rules by name for the next line | diff --git a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md index fa05af31be..544cd5a349 100644 --- a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md +++ b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md @@ -73,7 +73,7 @@ Use `git status` to list all new or modified files that haven't yet been committ To format code or text into its own distinct block, use triple backticks. -````text +````markdown Some basic Git commands are: ``` git status @@ -373,9 +373,9 @@ Here are the rendered alerts: You can tell {% data variables.product.product_name %} to hide content from the rendered Markdown by placing the content in an HTML comment. -
-<!-- This content will not appear in the rendered Markdown -->
-
+```text + +``` ## Ignoring Markdown formatting diff --git a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github.md b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github.md index 1f0e33849e..44d2c76742 100644 --- a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github.md +++ b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github.md @@ -191,20 +191,20 @@ You can use HTML comment syntax to add a comment that will be hidden in the outp 1. Two lines below the `## About me` header, insert a comment by using the following markup. - 
-   <!-- COMMENT -->
-
+ ```text + + ``` Replace `COMMENT` with a "to-do" item you remind yourself to do something later (for example, to add more items to the table). 1. To check your comment is hidden in the output, click the **Preview** tab. ### Example of a comment -
+```markdown
 ## About me
 
-<!-- TO DO: add more details about me later -->
-
+ +``` ## Saving your work diff --git a/package-lock.json b/package-lock.json index 1bf847d646..4ac0236092 100644 --- a/package-lock.json +++ b/package-lock.json @@ -79,13 +79,13 @@ "remark-gfm": "^4.0.0", "remark-parse": "^11.0.0", "remark-rehype": "^11.1.0", + "remark-remove-comments": "^1.0.1", "rss-parser": "^3.13.0", "scroll-anchoring": "^0.1.0", "semver": "^7.6.2", "sharp": "0.33.1", "slash": "^5.1.0", "strip-ansi": "7.1.0", - "strip-html-comments": "^1.0.0", "styled-components": "^5.3.5", "swr": "^2.2.4", "tcp-port-used": "1.0.2", @@ -8078,6 +8078,11 @@ "node": ">=14" } }, + "node_modules/html-comment-regex": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/html-comment-regex/-/html-comment-regex-1.1.2.tgz", + "integrity": "sha512-P+M65QY2JQ5Y0G9KKdlDpo0zK+/OHptU5AaBwUfAIDJZk1MYf32Frm84EcOytfJE0t5JvkAnKlmjsXDnWzCJmQ==" + }, "node_modules/html-entities": { "version": "2.5.2", "resolved": "https://registry.npmjs.org/html-entities/-/html-entities-2.5.2.tgz", @@ -12736,6 +12741,42 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/remark-remove-comments": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/remark-remove-comments/-/remark-remove-comments-1.0.1.tgz", + "integrity": "sha512-aoBnwdr9VjMdRYkKLzU2MD11KuxLAiCYGFimR79z7DIzfmC8yjohbpCl9x/6+qx0SpPnfZ2aFBFa2QPXPdT/LQ==", + "dependencies": { + "html-comment-regex": "^1.1.2", + "unist-util-visit": "^4.1.1" + } + }, + "node_modules/remark-remove-comments/node_modules/unist-util-visit": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-4.1.2.tgz", + "integrity": "sha512-MSd8OUGISqHdVvfY9TPhyK2VdUrPgxkUtWSuMHF6XAAFuL4LokseigBnZtPnJMu+FbynTkFNnFlyjxpVKujMRg==", + "dependencies": { + "@types/unist": "^2.0.0", + "unist-util-is": "^5.0.0", + "unist-util-visit-parents": "^5.1.1" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-remove-comments/node_modules/unist-util-visit-parents": { + "version": "5.1.3", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-5.1.3.tgz", + "integrity": "sha512-x6+y8g7wWMyQhL1iZfhIPhDAs7Xwbn9nRosDXl7qoPTSCy0yNxnKc+hWokFifWQIDGi154rdUqKvbCa4+1kLhg==", + "dependencies": { + "@types/unist": "^2.0.0", + "unist-util-is": "^5.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/remark-stringify": { "version": "11.0.0", "resolved": "https://registry.npmjs.org/remark-stringify/-/remark-stringify-11.0.0.tgz", @@ -13637,10 +13678,6 @@ "node": ">=6" } }, - "node_modules/strip-html-comments": { - "version": "1.0.0", - "license": "MIT" - }, "node_modules/strip-json-comments": { "version": "3.1.1", "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz", diff --git a/package.json b/package.json index 7bdeb3c253..09026f8079 100644 --- a/package.json +++ b/package.json @@ -266,13 +266,13 @@ "remark-gfm": "^4.0.0", "remark-parse": "^11.0.0", "remark-rehype": "^11.1.0", + "remark-remove-comments": "^1.0.1", "rss-parser": "^3.13.0", "scroll-anchoring": "^0.1.0", "semver": "^7.6.2", "sharp": "0.33.1", "slash": "^5.1.0", "strip-ansi": "7.1.0", - "strip-html-comments": "^1.0.0", "styled-components": "^5.3.5", "swr": "^2.2.4", "tcp-port-used": "1.0.2", diff --git a/src/content-linter/scripts/lint-content.js b/src/content-linter/scripts/lint-content.js index 0abed3c98c..26f512a276 100755 --- a/src/content-linter/scripts/lint-content.js +++ b/src/content-linter/scripts/lint-content.js @@ -469,6 +469,9 @@ function formatResult(object, isPrecommit) { // Add severity to each result object const ruleName = object.ruleNames[1] || object.ruleNames[0] + if (!allConfig[ruleName]) { + throw new Error(`Rule not found in allConfig: '${ruleName}'`) + } formattedResult.severity = allConfig[ruleName].severity || getSearchReplaceRuleSeverity(ruleName, object, isPrecommit) diff --git a/src/content-render/liquid/index.js b/src/content-render/liquid/index.js index e1b4386abf..b95bb1bdac 100644 --- a/src/content-render/liquid/index.js +++ b/src/content-render/liquid/index.js @@ -1,9 +1,7 @@ -import { processLiquidPre } from './pre.js' import { processLiquidPost } from './post.js' import { engine } from './engine.js' export async function renderLiquid(template, context) { - template = processLiquidPre(template) template = await engine.parseAndRender(template, context) template = processLiquidPost(template) return template diff --git a/src/content-render/liquid/pre.js b/src/content-render/liquid/pre.js deleted file mode 100644 index 1d9f1a1d7a..0000000000 --- a/src/content-render/liquid/pre.js +++ /dev/null @@ -1,13 +0,0 @@ -import stripHtmlComments from 'strip-html-comments' - -export function processLiquidPre(template) { - template = removeHtmlComments(template) - return template -} - -function removeHtmlComments(template) { - // remove any newlines that precede html comments, then remove the comments - template = template.replace(/\n + + + +```html +This is a +``` + +You can use HTML comments inside the `<-- paragraph -->` + +## Tables are OK too + +| Comment | Effect | +| :-- | :-- | +| `` | Disable all rules | +| `` | Enable all rules | diff --git a/src/fixtures/fixtures/content/get-started/markdown/index.md b/src/fixtures/fixtures/content/get-started/markdown/index.md index 8b0c49e7dd..6fe218b5e7 100644 --- a/src/fixtures/fixtures/content/get-started/markdown/index.md +++ b/src/fixtures/fixtures/content/get-started/markdown/index.md @@ -11,4 +11,5 @@ children: - /code-annotations - /alerts - /replace-domain + - /html-comments --- diff --git a/src/fixtures/tests/html-comments.js b/src/fixtures/tests/html-comments.js new file mode 100644 index 0000000000..6abc9484cb --- /dev/null +++ b/src/fixtures/tests/html-comments.js @@ -0,0 +1,16 @@ +import { describe, expect, test } from 'vitest' + +import { getDOMCached as getDOM } from '#src/tests/helpers/e2etest.js' + +describe('html-comments', () => { + test('regular comments are removed', async () => { + const $ = await getDOM('/get-started/markdown/html-comments') + const contents = $('#article-contents') + const html = contents.html() + expect(html).not.toContain('This comment should get deleted since it mentions gooblygook') + expect(html).toContain('<-- paragraph -->') + expect(html).toContain('<!-- html comment -->') + expect(html).toContain('<!-- markdownlint-disable -->') + expect(html).not.toContain('Another multi-line') + }) +})