diff --git a/content/contributing/collaborating-on-github-docs/using-the-todocs-placeholder-to-leave-notes.md b/content/contributing/collaborating-on-github-docs/using-the-todocs-placeholder-to-leave-notes.md index 4d6dce4335..949770814e 100644 --- a/content/contributing/collaborating-on-github-docs/using-the-todocs-placeholder-to-leave-notes.md +++ b/content/contributing/collaborating-on-github-docs/using-the-todocs-placeholder-to-leave-notes.md @@ -7,6 +7,7 @@ versions: feature: 'contributing' --- + ## Using the TODOCS placeholder Sometimes technical writers use placeholders while writing documentation to remind themselves to come back to something later. It's a useful technique, but there's always the possibility that the placeholder will be overlooked and slip into production. At that point, the only way the Docs team will find out about it is if someone sees it and reports it. @@ -21,10 +22,11 @@ To prevent slips, use the string `TODOCS` as your placeholder. The Docs test sui ### Example -``` +```markdown 1. In the dropdown, select the settings you want to sync. TODOCS: ADD A SCREENSHOT OF THE SETTINGS SYNC OPTIONS 1. Click **Sign in & Turn on**, then select the account to which you want your settings to be synced. -``` \ No newline at end of file +``` + diff --git a/package-lock.json b/package-lock.json index 6f6921ab29..f54f9d6ba1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -138,6 +138,7 @@ "make-promises-safe": "^5.1.0", "markdownlint": "^0.28.2", "markdownlint-rule-helpers": "^0.19.0", + "markdownlint-rule-search-replace": "^1.2.0", "mdast-util-gfm-table": "^2.0.0", "micromark-extension-gfm-table": "^2.0.0", "mkdirp": "^3.0.0", @@ -9986,6 +9987,30 @@ "node": ">=14.18.0" } }, + "node_modules/markdownlint-rule-search-replace": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/markdownlint-rule-search-replace/-/markdownlint-rule-search-replace-1.2.0.tgz", + "integrity": "sha512-l2eeVjb0ijxO+dO1ZrODcht+qnJ0VuiAAdBx1J8oa2kAugXl3NhxAGjfNuTfEJae5OQbdSGT+NjMczyzBXvWMA==", + "dev": true, + "dependencies": { + "markdownlint-rule-helpers": "0.21.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/markdownlint-rule-search-replace/node_modules/markdownlint-rule-helpers": { + "version": "0.21.0", + "resolved": "https://registry.npmjs.org/markdownlint-rule-helpers/-/markdownlint-rule-helpers-0.21.0.tgz", + "integrity": "sha512-27WM6H76t79EZjEl3jSabV0ZzXsC5QaSslI/5N1XuXV0mJRA6i3BPMGFrtZUbhlCNgtY6oC9h5JhtpDMv95tKg==", + "dev": true, + "dependencies": { + "markdownlint-micromark": "0.1.2" + }, + "engines": { + "node": ">=16" + } + }, "node_modules/matcher-collection": { "version": "2.0.1", "license": "ISC", diff --git a/package.json b/package.json index 834ff21f7c..d53b37c154 100644 --- a/package.json +++ b/package.json @@ -187,6 +187,7 @@ "make-promises-safe": "^5.1.0", "markdownlint": "^0.28.2", "markdownlint-rule-helpers": "^0.19.0", + "markdownlint-rule-search-replace": "^1.2.0", "mdast-util-gfm-table": "^2.0.0", "micromark-extension-gfm-table": "^2.0.0", "mkdirp": "^3.0.0", diff --git a/src/content-linter/lib/linting-rules/index.js b/src/content-linter/lib/linting-rules/index.js index e6ae8ca2ac..f402fde205 100644 --- a/src/content-linter/lib/linting-rules/index.js +++ b/src/content-linter/lib/linting-rules/index.js @@ -1,3 +1,5 @@ +import searchReplace from 'markdownlint-rule-search-replace' + import { codeFenceLineLength } from './code-fence-line-length.js' import { imageAltTextEndPunctuation } from './image-alt-text-end-punctuation.js' import { imageFileKebab } from './image-file-kebab.js' @@ -7,6 +9,7 @@ import { internalLinksSlash } from './internal-links-slash.js' export const gitHubDocsMarkdownlint = { rules: [ + searchReplace, // Open-source plugin codeFenceLineLength, imageAltTextEndPunctuation, imageFileKebab, diff --git a/src/content-linter/scripts/markdownlint.js b/src/content-linter/scripts/markdownlint.js index 22a052cf76..b5763b6ba5 100755 --- a/src/content-linter/scripts/markdownlint.js +++ b/src/content-linter/scripts/markdownlint.js @@ -18,7 +18,7 @@ program ) .addOption( new Option( - '-e, --errors', + '--errors-only', 'Only report rules that have the severity of error, not warning.', ).conflicts('rules'), ) @@ -38,7 +38,7 @@ program ) .parse(process.argv) -const { fix, paths, errors, rules, summaryByRule, verbose } = program.opts() +const { fix, paths, errorsOnly, rules, summaryByRule, verbose } = program.opts() const ALL_CONTENT_DIR = ['content', 'data'] main() @@ -57,7 +57,7 @@ async function main() { const start = Date.now() // Initializes the config to pass to markdownlint based on the input options - const config = getMarkdownLintConfig(errors, rules) + const config = getMarkdownLintConfig(errorsOnly, rules) // Run Markdownlint on content and data directories individually // and get all results const results = await getMarkdownlintResults(config, files) @@ -189,8 +189,11 @@ function formatResult(object) { const formattedResult = {} // Add severity of error or warning - const ruleName = object.ruleNames[1] - formattedResult.severity = allConfig[ruleName].severity + const ruleName = object.ruleNames[1] || object.ruleNames[0] + // The severity of the rule can be different when running locally vs in CI + formattedResult.severity = process.env.CI + ? allConfig[ruleName].severity + : allConfig[ruleName]['severity-local-env'] || allConfig[ruleName].severity return Object.entries(object).reduce((acc, [key, value]) => { if (key === 'fixInfo') { @@ -263,7 +266,7 @@ async function getMarkdownlintResults(config, files) { // those Markdown files are partials included in full Markdown files. // Rules that can't be run on partials have the property // `partial-markdown-files` set to false. -function getMarkdownLintConfig(errors, rules) { +function getMarkdownLintConfig(errorsOnly, rules) { const config = { content: { default: false, // By default, don't turn on all markdownlint rules @@ -274,7 +277,7 @@ function getMarkdownLintConfig(errors, rules) { } // Only configure the rules that have the severity of error - if (errors) { + if (errorsOnly) { const errorConfig = Object.keys(allConfig).reduce((acc, key) => { if (allConfig[key].severity === 'error') acc[key] = allConfig[key] return acc diff --git a/src/content-linter/style/github-docs.js b/src/content-linter/style/github-docs.js index d3813ac8e8..eca647f70e 100644 --- a/src/content-linter/style/github-docs.js +++ b/src/content-linter/style/github-docs.js @@ -29,4 +29,17 @@ export const githubDocsConfig = { severity: 'error', 'partial-markdown-files': true, }, + 'search-replace': { + severity: 'error', + 'severity-local-env': 'warning', + 'partial-markdown-files': true, + rules: [ + { + name: 'todocs-placeholder', + message: 'Catch occurrences of TODOCS placeholder.', + search: 'TODOCS', + searchScope: 'all', + }, + ], + }, }