AGENTS.md, ACCESSIBILITY.md but also A11Y.md, DESIGN.md—as well as taste.md.
Following this trend of specialized specification files, here is a draft for HTML.md (gist)—foundational instructions you need for writing HTML, geared towards both humans and machines (if only to improve parsing and save tokens).
* Use the elements most appropriate semantically.
* Use as little HTML as possible.
* Validate all HTML output against an HTML validator (preferably the W3C one), and fix any errors.
That’s it.
Is this a joke?
No: While these instructions are opinionated insofar as they reflect a school of minimal web development honoring the first rule of ARIA and suggesting no use of optional markup, they acknowledge the reality that the HTML code on most websites often isn’t using the right elements for the job (e.g., divitis) and that it’s essentially never error-free (i.e., commonly invalid). Note, then, that this guidance intentionally doesn’t handle “everything,” like accessibility, performance, and search optimization, but the foundation.
Although we can memorize the three instructions, it is useful to document them in writing.
Whether that’s actually in form of an “HTML.md,” however, that’s everyone’s individual call. So this is not a serious request for this particular file convention—but one for us to pay more attention to HTML quality.
