add markdownlint search and replace rule (#41371)

content/contributing/collaborating-on-github-docs/using-the-todocs-placeholder-to-leave-notes.md

@@ -7,6 +7,7 @@ versions:
   feature: 'contributing'
 ---
 
+<!-- markdownlint-disable search-replace -->
 ## 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.
-```
+```
+<!-- markdownlint-enable search-replace -->

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",

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,

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

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',
+      },
+    ],
+  },
 }