Docs Discussion: URL use within docs

markdownlint rule 44 will be a really useful addition, and I'm working on implementing it in gitlab#31185 (closed).

The main advantage is that it will help us catch all the improperly capitalized product names, and there are examples in the issue linked above. It will also flag commands, which are always lowercase, hinting to authors that they should use backticks.

Unfortunately, we identified a drawback, in that it will not allow some references to URLs in bare text, which we used from time to time. For example:

- I'm talking about how <http://docs.gitlab.com> does something.
- Later, I'm talking about how http://docs.gitlab.com does something else
- Finally, I'm talking about how docs.gitlab.com does another thing.
  • The first item will pass both rule 44, and also rule 34 (no bare URLs).
  • The second item will fail rule 34, and there should be no more examples of this already (taken care of by Evan a few months ago). Rule 34 is active.
  • The third item will pass rule 34, but will fail rule 44, because the gitlab is not properly capitalized. Up to now, this was always considered OK in our docs.

It's clear that we need to do something, because Rule 44 would be extremely beneficial (no more Gitlab anywhere in the docs, not to mention the other 1000+ examples of improperly capitalized product names I found).

Some possibilities for imaginary product "WhatEver" (capitalized W and E) with website "whatever.com":

  1. Change all remaining references in bare URLs (URLs that are bare, but didn't use http:// like simply whatever.com) to full URLs and link them like <http://whatever.com> or [WhatEver](whatever.com)
  2. Change all remaining references to use backticks instead, so the linter will ignore them, so `whatever.com`.
  3. Use capitalization in website names so they pass rule 44, so I can talk about: WhatEver.com
  4. Add exceptions to the naming list for sites that we frequently want to refer to in plain text.
Edited by Marcel Amirault