Test for missing backticks or improper capitalization in docs
Proposal
The docs, which will be using markdownlint across all docs-related projects (Charts, Omnibus, Runner and GitLab), should make use of this markdownlint feature to enforce proper capitalization automatically, which has the added benefit of often pointing out places where backticks should be used for commands.
For example:
Gitlab uses git. Run git log to see the log.
-
Gitlab
fails, because it needs a capitalL
- The first
git
fails because it needs a capitalG
- The second
git
fails because the linter thinks it needs a capitalG
, but in reality, it needs backticks because it's a command example. By flagging this third issue, the writer will know to add backticks.
Corrected:
GitLab uses Git. Run `git log` to see the log.
In order to enable this, a list will have to be created with all proper names of products, and all examples of improper capitalization will have to be fixed. This will need to be done incrementally.
I am slowly expanding this list, in no particular order, just as I run into mistakes people made and then add it to my personal .markdownlint.json
file:
"proper-names": {
"names": [
"Debian",
"Git LFS",
"git-annex",
"Git",
"Gitaly",
"GitLab Monitor",
"GitLab Rails",
"GitLab Runner",
"GitLab Shell",
"GitLab Workhorse",
"GitLab",
"JavaScript",
"Jenkins",
"Jira",
"Kubernetes",
"NGINX Ingress",
"NGINX",
"Omnibus GitLab",
"OpenShift",
"PostgreSQL",
"Python",
"Redis",
"runit",
"Ubuntu",
"Unicorn"
],
"code_blocks": false
}
This Issue will track the work done on this effort.
Edited by Marcel Amirault