chore: improve docs relative link linting (#26359)

script/check-relative-doc-links.py

@@ -95,14 +95,27 @@ def getBrokenLinks(filepath):
 
 
 def checkSections(sections, lines):
-  sectionHeader = sections[1].replace('-', '')
+  invalidCharsRegex = '[^A-Za-z0-9_ \-]'
+  sectionHeader = sections[1]
   regexSectionTitle = re.compile('# (?P<header>.*)')
   for line in lines:
     matchHeader = regexSectionTitle.search(line)
     if matchHeader:
-     matchHeader = filter(str.isalnum, str(matchHeader.group('header')))
-     if matchHeader.lower() == sectionHeader:
-      return True
+      # This does the following to slugify a header name:
+      #  * Replace whitespace with dashes
+      #  * Strip anything that's not alphanumeric or a dash
+      #  * Anything quoted with backticks (`) is an exception and will
+      #    not have underscores stripped
+      matchHeader = str(matchHeader.group('header')).replace(' ', '-')
+      matchHeader = ''.join(
+        map(
+          lambda match: re.sub(invalidCharsRegex, '', match[0])
+          + re.sub(invalidCharsRegex + '|_', '', match[1]),
+          re.findall('(`[^`]+`)|([^`]+)', matchHeader),
+        )
+      )
+      if matchHeader.lower() == sectionHeader:
+        return True
   return False