Lint for spelling, capitalization, and other typos of important vocabulary

As highlighted by the immense number of typos of just GitLab (see MRs in #147 (closed)), the most important word in the handbook, we really need some automation to enforce proper spelling and capitalization of our important vocabulary.

Two examples that could be implemented on the handbook project, are the two tools the technical writers for the GitLab product docs implemented to ensure the docs follow our highest standards:

• Markdownlint: Already in use in the handbook for markdown formatting issues, but could be used to enforce proper capitalization (GitLab with capital G and L, not Gitlab or any other variation).

  markdownlint.yml config to enforce proper capitalization in the docs.

• Vale: Can write custom rules to enforce almost anything in text. The docs team has written custom rules to enforce a wide variety of language issues, for example:

  • Strict vocab rules (pipeline fails if certain terms are used incorrectly): https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Substitutions.yml
  • Vocab warnings (pipeline does not fail, but a warning is shown in the MR diff): https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionWarning.yml
  • Double-word typos, like "Go to the the handbook": https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Repetition.yml
  • DIB language rules:
    • https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml
    • https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml
    • https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml
  • And many more: https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab

While it took a long time to create all these rules, the improvement in docs quality has been impressive. Considering the importance of our handbook, we should put in the work to implement linters and ensure our handbook content is as high quality as our docs content.

Rules to add to handbook

The following is a list of the product documentation rules that we'd like to introduce to the handbook.

If you'd like to contribute, please check the item in the list if you intend to work on it, and add a link to the MR when available.

markdownlint

For context, many of the rules were previously updated already to make markdownlint more consistent with product docs: https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4669 and !5738 (merged)

To make the handbook markdownlint file more consistent with the product docs markdownlint config, we should make the following changes:

1. Remove "no-multiple-blanks": false from internal handbook. | (1411) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4858
2. Remove "ul-indent": false | (8352) !6286 (merged) and (2088) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4851
3. Remove "heading-increment": false, Note: true on internal handbook already. | (594) !6763 (merged)
4. Optionally: Add reference-links-images: false once https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ReferenceLinks.yml is added
5. Add no-trailing-spaces: false. If we do this, we'll need to create a follow-up issue to implement something similar to #151 (comment 1785554020) ; also dependent on #270 (closed). | !6530 (merged) and https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4920

To consider

1. Add "fenced-code-language": false, as we don't need to be strict about this. The main advantage is syntax highlighting which is a nice to have, but not a requirement.
2. Add proper-names with code_blocks: false and html_elements: false, with the following names (full list copied as-is from the current version on the default branch):

proper names

1. "Akismet", (?) (0) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
2. "Alertmanager", (?) (1) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
3. "AlmaLinux", (?) (0) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
4. "API",
5. "Asana", (?) (0) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
6. "Auth0", (?) (0) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
7. "Azure", (?) (0) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
8. "Bamboo", (?) (0) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
9. "Bitbucket", (?) (3)
10. "Bugzilla", (?) (0) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
11. "CAS", (?) (1)
12. "CentOS", (?) (0) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
13. "Consul", (?) (3) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
14. "Debian", (?) (1) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
15. "DevOps",
16. "Docker",
17. "DockerSlim",
18. "Elasticsearch",
19. "Facebook", (?) (0) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
20. "fastlane", (?) (0) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
21. "fluent-plugin-redis-slowlog", (?) (0) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4895
22. "GDK",
23. "Geo",
24. "Git LFS",
25. "git-annex",
26. "git-credential-oauth",
27. "git-sizer",
28. "Git",
29. "Gitaly",
30. "GitHub",
31. "gitlab.vim",
32. "GitLab Geo",
33. "GitLab Monitor",
34. "GitLab Operator",
35. "GitLab Pages",
36. "GitLab Rails",
37. "GitLab Runner",
38. "GitLab Shell",
39. "GitLab Workhorse",
40. "GitLab",
41. "Gitleaks",
42. "Gmail",
43. "Google",
44. "Grafana",
45. "Gzip",
46. "Helm",
47. "HipChat",
48. "ID",
49. "IP",
50. "Ingress",
51. "jasmine-jquery",
52. "JavaScript",
53. "Jaeger",
54. "Jenkins",
55. "Jira",
56. "Jira Cloud",
57. "Jira Server",
58. "jQuery",
59. "JSON",
60. "JupyterHub",
61. "Karma",
62. "Kerberos",
63. "Knative",
64. "Kubernetes",
65. "LDAP",
66. "Let's Encrypt",
67. "Markdown",
68. "markdownlint",
69. "Mattermost",
70. "Microsoft",
71. "minikube",
72. "MinIO",
73. "ModSecurity",
74. "Neovim",
75. "NGINX Ingress",
76. "NGINX",
77. "OAuth",
78. "OAuth 2",
79. "OmniAuth",
80. "OpenID",
81. "OpenShift",
82. "PgBouncer",
83. "Postfix",
84. "PostgreSQL",
85. "PowerShell",
86. "Praefect",
87. "Prometheus",
88. "Puma",
89. "puma-worker-killer",
90. "Python",
91. "Rake",
92. "Redis",
93. "Redmine",
94. "reCAPTCHA",
95. "Ruby",
96. "runit",
97. "Salesforce",
98. "SAML",
99. "Sendmail",
100. "Sentry",
101. "Service Desk",
102. "Sidekiq",
103. "Shibboleth",
104. "Slack",
105. "SMTP",
106. "SpotBugs",
107. "SSH",
108. "Tiller",
109. "TOML",
110. "Trello",
111. "Trello Power-Ups",
112. "TypeScript",
113. "Twitter",
114. "Ubuntu",
115. "Ultra Auth",
116. "Unicorn",
117. "unicorn-worker-killer",
118. "URL",
119. "WebdriverIO",
120. "YAML",
121. "YouTrack"

No changes

These have been reviewed and kept as-is on purpose:

1. first-header rules are purposely kept false since we use the title as the h1 in the handbook, so we actually prefer not having a H1.
2. ol-prefix and ul-style are left at the default, letting it be consistent rather than forcing one and dash.
3. no-bare-urls: false: This is currently not possible due to the shortcodes in the handbook. There's a feature request for custom regex exemption but it's still open: https://github.com/DavidAnson/markdownlint/issues/249 . The only other solution I've found is to disable the rule for all instances: https://discourse.gohugo.io/t/ignore-a-line-with-markdownlint/44269 . We can consider making an equivalent Vale rule instead.

Vale rules

Note: vale can be suggestion, warning, or error. Where not specified, use the same as what's in the docs rule.

1. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml (as warning)
2. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/EOLWhitespace.yml (warning)
3. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml (warning)
4. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml (warning)
5. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml (warning)
6. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InternalLinkCase.yml (error) | (57) !6600 (merged) and (2) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4896
7. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InternalLinkFormat.yml (as warning)
8. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml (warning)
9. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/MeaningfulLinkWords.yml (warning)
10. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/MergeConflictMarkers.yml (error) | (0) !6422 (merged) and https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4866
11. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/MultiLineLinks.yml (error) | (163) !6616 (merged) and (19) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4894
12. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/NonStandardQuotes.yml (warning)
13. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml (warning)
14. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ReferenceLinks.yml (error) | (745) !6682 (merged) and (30) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4940
15. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/RelativeLinks.yml (a version of) | (289) !6583 (merged) and (29) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4896
16. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/RelativeLinksDoubleSlashes.yml | (0) !6422 (merged) and https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4866
17. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Repetition.yml | (291) !6422 (merged) and (42) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4866
18. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Spelling.yml (warning) ; don't forget the spelling exceptions file
19. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Zip.yml | (0) !6422 (merged) and (1) https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4866

Warnings added in !6707 (merged) and https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/4960.

To consider

1. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceLength.yml
2. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml
3. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionWarning.yml
4. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Substitutions.yml
5. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Units.yml The matching isn't great though. We would need to make exceptions for things like "1st", and "3D".
6. https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Uppercase.yml There are a lot of uppercase words that we'd have to add.