Markdown linting: Emphasis used instead of a header (MD036)

[dshevtsov]

Bug report

Description

The Markdown linter reports about 415 issues when the rule 'MD036' is enabled.

Steps to reproduce

1. In the _checks/styles/style-rules-prod change exclude_rule 'MD036' to rule 'MD036'.
2. In your terminal, run rake test:md.

Test your updates

1. Follow "Steps to reproduce" locally to get list of errors to fix.
2. Preview the HTML locally to ensure your changes did not break formatting in the resulting HTML (run rake:preview). For more information, refer to the README.

Note-->Do NOT use special keywords in your commit message.

Expected result

All the reported issues are fixed.
The rake test:md command returns No issues found.

[jeff-matthews]

We have several places in our API reference docs that use bolded text as a type of header (e.g., Request and Response body examples). More often than not, these headers follow an H2 heading, so changing from bolded text to an H3 heading may not be appropriate because H3s show up in the on page navigation.

Even in places where the bolded text header is preceded by an H3 and therefore would be a good candidate to be made an H4, it may break the consistency we're trying to keep across all API reference docs.

To enable this rule, we would need to either use the {:.procedure} class that we created for the cloud docs or create a new class.

After doing this research, I'm questioning the value of rule MD036 overall. I think we should exclude it.

[dshevtsov]

They can be changed to bolded text followed by :

**Request:**

**Response:**

[jeff-matthews]

@dshevtsov, are you saying that adding the colon will keep these from triggering the rule?

[dshevtsov]

We cannot use headings for this because headings with the same names will be generated with same ids. This will be detected by HTML checker as invalid HTML.

[dshevtsov]

@dshevtsov, are you saying that adding the colon will keep these from triggering the rule?

yes