search

ocaml / ocaml.org

The official OCaml website.
https://ocaml.org
Other
162 stars 326 forks source link

Fix invalid HTML everywhere and prevent invalid HTML in the future #829

Open sabine opened 1 year ago

sabine commented 1 year ago

Currently, we have a lot of pages with invalid HTML and this completely breaks the UX for people using screen-readers (and can also lead to funny visual artifacts and strange behaviour on different screen sizes).

Thus, we must fix all the invalid HTML markup.

Also, we need to introduce technical means to ensure that we do not serve invalid HTML. There are two ways we can achieve that:

  1. use only template-preprocessors and tools that provide guarantees around admitting/producing ONLY valid HTML, and
  2. extend the CI to also test validity of HTML output (at the very least for some "token" pages from all parts of the site).

To do:

shindere commented 1 year ago

Many thanks, @sabine, for your interest in improving this asppect of the website. I am fully convinced that this is a fundamental issue and that many improvements do have this prerequisite that the generated HTML code is valid.

May I suggest to slightly modify the terminology in this issue to make it more pprecise? To be more precise myself, I think invalid HTMML would be clearer and more well-defined than broken HTML.

The HTML not being valid does indeed make it possible that the rendering varies between browsers, because the way a browser renders HTML is well defined only if the HTML is valid. If it is not, then the browser will render it as best as it can but the way to recover from invalid HTML is browser-specific and has thus no reason to be consistent from one browser to another. this of course imppacts accessibility but the impact is much broader.

Thanks again! Very well done!

sabine commented 1 year ago

@shindere Indeed, you're correct that invalid HTML has a much wider negative impact than bad (or impossible) accessibility.

I opened another issue focusing explicitly on improving accessibility here: https://github.com/ocaml/ocaml.org/issues/880