Add dashesInHeadings doc file

markdownlint/docs/TOP011.md

@@ -0,0 +1,46 @@
+# `TOP011`: Dashes in headings
+
+Tags: `headings`
+
+Aliases: `dashes-in-headings`
+
+This rule is triggered when a heading contains dashes used for separating the heading's main title from a subtitle. For example:
+
+```markdown
+### Headings - Should dashes be used as separators?
+
+### Headings -- Should double dashes be used as separators?
+```
+
+Instead of the dash(es), use a colon instead.
+
+```markdown
+### Headings: Colons must be used as separators
+```
+
+This rule only triggers for dashes used in this way. Dashes used as hyphens or CLI flags will not trigger this rule.
+
+```markdown
+### Hyphenated-words are perfectly acceptable
+
+### As are headings with CLI -f --flags
+```
+
+Headings that violate this rule can be fixed via the appropriate `fix:*` script.
+
+```markdown
+### Headings - Hyphenated-words and --flags will be left alone
+
+<!-- Will get fixed to -->
+### Headings: Hyphenated-words and --flags will be left alone
+```
+
+## Rationale
+
+Markdownlint and Visual Studio Code uses the [GitHub heading algorithm](https://github.com/gjtorikian/html-pipeline/blob/f13a1534cb650ba17af400d1acd3a22c28004c09/lib/html/pipeline/toc_filter.rb) to generate the appropriate fragments from headings, which preserves *all* dashes in the heading. The TOP web app uses [Ruby on Rails' `#parameterize` method](https://apidock.com/rails/String/parameterize) to generate heading IDs and fragments, which removes separator dashes.
+
+For example, the heading `### Heading - Hyphenated-subheading` will be converted to `heading---hyphenated-subheading` by Visual Studio Code and Markdownlint, but our web app will convert it to `heading-hypenated-subheading`.
+
+This creates a discrepancy between the fragment any of our links would require for our website, and what Markdownlint considers "valid". Using the website-valid fragment would trigger Markdownlint's [MD051 rule](https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md). Using the Markdownlint-valid fragment would not match the right heading on our website.
+
+Enforcing colons instead of dashes as separators, we can also avoid messy heading ID syntax such as `### Heading - Hyphenated-subheading {#heading-hypenated-subheading}`, as now if the heading text changes, we have an additional thing to need to remember to change.