3 new rules to potentially upstream from the github/docs repo

[rachmari]

We have a few custom Markdownlint rules that might be worth upstreaming into this repo.
The Markdownlint rules are written for the specific flavor of Markdown used to author docs.github.com. The rules are open-source and located here: https://github.com/github/docs/tree/main/src/content-linter/lib/linting-rules. We're open to any modifications or naming updates that would make these rules more useful to projects outside of docs.github.com. ✨

While most of our rules are very custom to the way we write Markdown for docs.github.com, these are a few we’ve identified that might be generic enough to add to this repo.

Image alt text punctuation

A rule that checks that image alt text ends with punctuation. Image alt text should be grammatically correct. The rule we've already written allows for the sentence to end with a period, exclamation point, or question mark (although this is generally not recommended). The rule also allows the sentence to include single or double quotes.

Here is the existing rule: image-alt-text-end-punctuation.

Image alt text starting words

A rule that check that image alt text does not start with specific generic words. I know that a generic word rule already exists and this is closely related but specifically checks for the image alter text to not start with "image" or "graphic."

Here is the existing rule: image-alt-text-exclude-start-words.

Image alt text length

A rule that checks the length of image alt text. Our rule is currently configured to error if the length is not within 40-150 characters per the docs style guidance, but the lower limit could be optional and configurable as well as making the upper limit configurable. I've seen guidance that screen readers typically cut off alt text after 125 characters and the general recommendation is to keep it below 100 characters.

Here is the existing rule: image-alt-text-length.

[andrialexandrou]

Thanks for the suggestions! We'll review.

[andrialexandrou]

Alright @rachmari the tl;dr is that these rules make sense in certain contexts, but we are inclined to encourage local definition and configuration rather than upstreaming them into this package.

Regarding length, we do want to allow for as lengthy an alt text as e.g. a browser would support. Restricting to some subset would be essentially a style choice by a brand or product, we feel. Regarding a text string not beginning with "image" or "graphic", this is more of a best practice rather than a WCAG requirement. Regarding punctuation, this is again more of a best practice.

We appreciate the proposal and want to invite more suggestions! We're eager to improve this and hearing your experience certainly lets us know how it's being used, where we might want to extend functionality, and so on. Some of these are good potential "warning" cases, but for now I think we're focusing on error states.

[rachmari]

@andrialexandrou thank you for considering this. 🙏 I'll go ahead and close this out.