Commit f00a62b5 authored by Evan Read's avatar Evan Read

Merge branch 'docs-capitalization-lint-1' into 'master'

Add caps and backtick testing to docs linting

Closes #31185

See merge request gitlab-org/gitlab!20764
parents 69131010 a731ecb7
......@@ -26,5 +26,103 @@
"first-line-h1": false,
"code-block-style": {
"style": "fenced"
},
"proper-names": {
"names": [
"Akismet",
"Alertmanager",
"API",
"Asana",
"Auth0",
"Authentiq",
"Azure",
"Bamboo",
"Bitbucket",
"Bugzilla",
"CAS",
"CentOS",
"Consul",
"Debian",
"Elasticsearch",
"Facebook",
"Git LFS",
"git-annex",
"gitlab-ui",
"Git",
"Gitaly",
"GitHub",
"GitLab Geo",
"GitLab Monitor",
"GitLab Operator",
"GitLab Pages",
"GitLab Rails",
"GitLab Runner",
"GitLab Shell",
"GitLab Workhorse",
"GitLab",
"Gmail",
"Google",
"Grafana",
"Helm",
"HipChat",
"Ingress",
"jasmine-jquery",
"JavaScript",
"Jaeger",
"Jenkins",
"Jira",
"Jira Cloud",
"Jira Server",
"jQuery",
"JupyterHub",
"Karma",
"Kerberos",
"Knative",
"Kubernetes",
"LDAP",
"Let's Encrypt",
"Markdown",
"markdownlint",
"Mattermost",
"Microsoft",
"MinIO",
"NGINX Ingress",
"NGINX",
"OAuth",
"OAuth 2",
"OmniAuth",
"Omnibus GitLab",
"OpenID",
"OpenShift",
"PgBouncer",
"PostgreSQL",
"Prometheus",
"Puma",
"Python",
"Redis",
"Redmine",
"reCAPTCHA",
"runit",
"Salesforce",
"SAML",
"Sentry",
"Sidekiq",
"Shibboleth",
"Slack",
"SMTP",
"SSH",
"Tiller",
"Trello",
"Trello Power-Ups",
"TypeScript",
"Twitter",
"Ubuntu",
"Ultra Auth",
"Unicorn",
"unicorn-worker-killer",
"WebdriverIO",
"YouTrack"
],
"code_blocks": false
}
}
......@@ -9,7 +9,7 @@ module Types
field :id, GraphQL::ID_TYPE, null: false,
description: 'Label ID'
field :description, GraphQL::STRING_TYPE, null: true,
description: 'Description of the label (markdown rendered as HTML for caching)'
description: 'Description of the label (Markdown rendered as HTML for caching)'
markdown_field :description_html, null: true
field :title, GraphQL::STRING_TYPE, null: false,
description: 'Content of the label'
......
......@@ -20,7 +20,7 @@ module Types
description: 'Title of the merge request'
markdown_field :title_html, null: true
field :description, GraphQL::STRING_TYPE, null: true,
description: 'Description of the merge request (markdown rendered as HTML for caching)'
description: 'Description of the merge request (Markdown rendered as HTML for caching)'
markdown_field :description_html, null: true
field :state, MergeRequestStateEnum, null: false,
description: 'State of the merge request'
......
......@@ -7,7 +7,7 @@ module Types
authorize :read_statistics
field :storage_size, GraphQL::INT_TYPE, null: false, description: 'The total storage in bytes'
field :repository_size, GraphQL::INT_TYPE, null: false, description: 'The git repository size in bytes'
field :repository_size, GraphQL::INT_TYPE, null: false, description: 'The Git repository size in bytes'
field :lfs_objects_size, GraphQL::INT_TYPE, null: false, description: 'The LFS objects size in bytes'
field :build_artifacts_size, GraphQL::INT_TYPE, null: false, description: 'The CI artifacts size in bytes'
field :packages_size, GraphQL::INT_TYPE, null: false, description: 'The packages size in bytes'
......
......@@ -2815,7 +2815,7 @@ type Label {
color: String!
"""
Description of the label (markdown rendered as HTML for caching)
Description of the label (Markdown rendered as HTML for caching)
"""
description: String
......@@ -2917,7 +2917,7 @@ type MergeRequest implements Noteable {
defaultMergeCommitMessage: String
"""
Description of the merge request (markdown rendered as HTML for caching)
Description of the merge request (Markdown rendered as HTML for caching)
"""
description: String
......@@ -5112,7 +5112,7 @@ type RootStorageStatistics {
packagesSize: Int!
"""
The git repository size in bytes
The Git repository size in bytes
"""
repositorySize: Int!
......
......@@ -2647,7 +2647,7 @@
},
{
"name": "repositorySize",
"description": "The git repository size in bytes",
"description": "The Git repository size in bytes",
"args": [
],
......@@ -7591,7 +7591,7 @@
},
{
"name": "description",
"description": "Description of the label (markdown rendered as HTML for caching)",
"description": "Description of the label (Markdown rendered as HTML for caching)",
"args": [
],
......@@ -13656,7 +13656,7 @@
},
{
"name": "description",
"description": "Description of the merge request (markdown rendered as HTML for caching)",
"description": "Description of the merge request (Markdown rendered as HTML for caching)",
"args": [
],
......
......@@ -399,7 +399,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
| Name | Type | Description |
| --- | ---- | ---------- |
| `id` | ID! | Label ID |
| `description` | String | Description of the label (markdown rendered as HTML for caching) |
| `description` | String | Description of the label (Markdown rendered as HTML for caching) |
| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
| `title` | String! | Content of the label |
| `color` | String! | Background color of the label |
......@@ -414,7 +414,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
| `iid` | String! | Internal ID of the merge request |
| `title` | String! | Title of the merge request |
| `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` |
| `description` | String | Description of the merge request (markdown rendered as HTML for caching) |
| `description` | String | Description of the merge request (Markdown rendered as HTML for caching) |
| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
| `state` | MergeRequestState! | State of the merge request |
| `createdAt` | Time! | Timestamp of when the merge request was created |
......@@ -749,7 +749,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
| Name | Type | Description |
| --- | ---- | ---------- |
| `storageSize` | Int! | The total storage in bytes |
| `repositorySize` | Int! | The git repository size in bytes |
| `repositorySize` | Int! | The Git repository size in bytes |
| `lfsObjectsSize` | Int! | The LFS objects size in bytes |
| `buildArtifactsSize` | Int! | The CI artifacts size in bytes |
| `packagesSize` | Int! | The packages size in bytes |
......
......@@ -335,7 +335,7 @@ deploy:
NOTE: **Note:**
Kubernetes configuration is not supported for Kubernetes clusters
that are [managed by GitLab](../user/project/clusters/index.md#gitlab-managed-clusters).
To follow progress on support for Gitlab-managed clusters, see the
To follow progress on support for GitLab-managed clusters, see the
[relevant issue](https://gitlab.com/gitlab-org/gitlab/issues/38054).
### Complete example
......
......@@ -1456,7 +1456,7 @@ For more information, see
NOTE: **Note:**
Kubernetes configuration is not supported for Kubernetes clusters
that are [managed by GitLab](../../user/project/clusters/index.md#gitlab-managed-clusters).
To follow progress on support for Gitlab-managed clusters, see the
To follow progress on support for GitLab-managed clusters, see the
[relevant issue](https://gitlab.com/gitlab-org/gitlab/issues/38054).
#### Dynamic environments
......
......@@ -399,7 +399,7 @@ merge request with new or changed docs is submitted, are:
- The `CHANGELOG.md` does not contain duplicate versions.
- No files in `doc/` are executable.
- No new `README.md` was added.
- [`markdownlint`](#markdownlint).
- [markdownlint](#markdownlint).
- Nanoc tests, which you can [run locally](#previewing-the-changes-live) before
pushing to GitLab by executing the command `bundle exec nanoc check internal_links`
(or `internal_anchors`) on your local [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory:
......@@ -420,7 +420,7 @@ help you catch common issues before raising merge requests for review of documen
The following are some suggested linters you can install locally and sample configuration:
- [`proselint`](#proselint)
- [`markdownlint`](#markdownlint), which is the same as the test run in [`docs-lint`](#testing)
- [markdownlint](#markdownlint), which is the same as the test run in [`docs-lint`](#testing)
NOTE: **Note:**
This list does not limit what other linters you can add to your local documentation writing toolchain.
......@@ -464,18 +464,18 @@ noise. The following sample `proselint` configuration disables these checks:
A file with `proselint` configuration must be placed in a
[valid location](https://github.com/amperser/proselint#checks). For example, `~/.config/proselint/config`.
#### `markdownlint`
#### markdownlint
[`markdownlint`](https://github.com/DavidAnson/markdownlint) checks that Markdown
[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown
syntax follows [certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules),
and is used by the [`docs-lint` test](#testing) with a [configuration file](#markdownlint-configuration).
Our [Documentation Style Guide](styleguide.md#markdown) and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/)
elaborate on which choices must be made when selecting Markdown syntax for GitLab
documentation. This tool helps catch deviations from those guidelines.
`markdownlint` can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--),
markdownlint can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--),
either on a single Markdown file or on all Markdown files in a project. For example, to run
`markdownlint` on all documentation in the [`gitlab` project](https://gitlab.com/gitlab-org/gitlab),
markdownlint on all documentation in the [`gitlab` project](https://gitlab.com/gitlab-org/gitlab),
run the following commands from within your `gitlab` project root directory, which will
automatically detect the [`.markdownlint.json`](#markdownlint-configuration) config
file in the root of the project, and test all files in `/doc` and its subdirectories:
......@@ -490,7 +490,7 @@ If you wish to use a different config file, use the `-c` flag:
markdownlint -c <config-file-name> 'doc/**/*.md'
```
`markdownlint` can also be run from within text editors using [plugins/extensions](https://github.com/DavidAnson/markdownlint#related),
markdownlint can also be run from within text editors using [plugins/extensions](https://github.com/DavidAnson/markdownlint#related),
such as:
- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint)
......@@ -502,9 +502,9 @@ is in use in the four repos that are the sources for <https://docs.gitlab.com>.
plugin/extension has different requirements regarding the configuration file, which
is explained in each editor's docs.
##### `markdownlint` configuration
##### markdownlint configuration
Each formatting issue that `markdownlint` checks has an associated
Each formatting issue that markdownlint checks has an associated
[rule](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules).
These rules are configured in the `.markdownlint.json` files located in the root of
four repos that are the sources for <https://docs.gitlab.com>:
......@@ -518,7 +518,7 @@ By default all rules are enabled, so the configuration file is used to disable u
rules, and also to configure optional parameters for enabled rules as needed. You can
also check [the issue](https://gitlab.com/gitlab-org/gitlab-foss/issues/64352) that
tracked the changes required to implement these rules, and details which rules were
on or off when `markdownlint` was enabled on the docs.
on or off when markdownlint was enabled on the docs.
## Danger Bot
......
......@@ -111,11 +111,38 @@ Hard-coded HTML is valid, although it's discouraged to be used while we have `/h
GitLab ensures that the Markdown used across all documentation is consistent, as
well as easy to review and maintain, by [testing documentation changes](index.md#testing) with
[`markdownlint`](index.md#markdownlint). This lint test fails when any document has an issue
[markdownlint](index.md#markdownlint). This lint test fails when any document has an issue
with Markdown formatting that may cause the page to render incorrectly within GitLab.
It will also fail when a document is using non-standard Markdown (which may render
correctly, but is not the current standard for GitLab documentation).
#### Markdown rule `MD044/proper-names` (capitalization)
A rule that could cause confusion is `MD044/proper-names`, as it might not be immediately
clear what caused markdownlint to fail, or how to correct the failure. This rule
checks a list of known words, listed in the `.markdownlint.json` file in each project,
to verify that proper capitalization and backticks are used. Words in backticks will
be ignored by markdownlint.
In general, product names should follow the exact capitalization of the official names
of the products, protocols, etc.
Some examples that will fail if incorrect capitalization is used:
- MinIO (needs capital `IO`)
- NGINX (needs all capitals)
- runit (needs lowercase `r`)
Additionally, commands, parameters, values, filenames, etc. must be included in backticks.
For example:
- "Change the `needs` keyword in your `.gitlab.yml`..."
- `needs` is a parameter, and `.gitlab.yml` is a file, so both need backticks. Additionally,
`.gitlab.yml` will fail markdownlint without backticks as it does not have capital G or L.
- "Run `git clone` to clone a Git repository..."
- `git clone` is a command, so it must be lowercase, while Git is the product, so
it must have a capital G.
## Structure
### Organize by topic, not by type
......
......@@ -11,7 +11,7 @@ easy to maintain, and performant for the end-user.
### Utility Classes
As part of the effort for [cleaning up our CSS and moving our components into GitLab-UI](https://gitlab.com/groups/gitlab-org/-/epics/950)
As part of the effort for [cleaning up our CSS and moving our components into gitlab-ui](https://gitlab.com/groups/gitlab-org/-/epics/950)
led by the [GitLab UI WG](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/20623) we prefer the use of utility classes over adding new CSS. However, complex CSS can be addressed by adding component classes.
#### Where are utility classes defined?
......
......@@ -2,7 +2,7 @@
## ESLint
We use ESLint to encapsulate and enforce frontend code standards. Our configuration may be found in the [gitlab-eslint-config](https://gitlab.com/gitlab-org/gitlab-eslint-config) project.
We use ESLint to encapsulate and enforce frontend code standards. Our configuration may be found in the [`gitlab-eslint-config`](https://gitlab.com/gitlab-org/gitlab-eslint-config) project.
### Disabling ESLint in new files
......
......@@ -138,7 +138,7 @@ configured or there was an error reporting the status via the API.
### Merge Request event does not trigger a Jenkins Pipeline
Check the **/var/log/gitlab/gitlab-rails/production.log** file for messages like:
Check the `/var/log/gitlab/gitlab-rails/production.log` file for messages like:
```plaintext
WebHook Error => Net::ReadTimeout
......@@ -157,7 +157,7 @@ which is set to 10 seconds by default.
To fix this the `gitlab_rails['webhook_timeout']` value will need to be increased
in the `gitlab.rb` config file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md).
If you don't find the errors above, but do find *duplicate* entries like below (in **/var/log/gitlab/gitlab-rail**), this
If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), this
could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#receiving-duplicate-or-multiple-webhook-requests-triggered-by-one-event):
```
......
......@@ -19,7 +19,7 @@ The following assumes you already have Vault installed and running.
1. On GitLab, click your avatar on the top-right corner, and select your user **Settings > Applications**.
1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt.html#redirect-uris),
making sure to select the **openid** scope.
making sure to select the **OpenID** scope.
1. Save application.
1. Copy client ID and secret, or keep the page open for reference.
![GitLab OAuth provider](img/gitlab_oauth_vault_v12_6.png)
......@@ -42,7 +42,7 @@ The following assumes you already have Vault installed and running.
1. **Write the OIDC config:**
Next, Vault needs to be given the application ID and secret generated by Gitlab.
Next, Vault needs to be given the application ID and secret generated by GitLab.
In the terminal session, run the following command to give Vault access to the GitLab application you've just created with an OpenID scope. This allows Vault to authenticate through GitLab.
......
......@@ -481,7 +481,7 @@ applications you have configured.
### Install Ingress using GitLab CI
To install ingress, define the `.gitlab/managed-apps/config.yaml` file
To install Ingress, define the `.gitlab/managed-apps/config.yaml` file
with:
```yaml
......
......@@ -408,8 +408,8 @@ Note that this sample has a few limitations:
- It does not regard different types of authentication mechanisms for the mirror.
- It does not work with forced updates (rewriting history).
- Only branches that match the `whitelisted` patterns will be proxy pushed.
- The script circumvents the git hook quarantine environment because the update of `$TARGET_REPO`
is seen as a ref update and git will complain about it.
- The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO`
is seen as a ref update and Git will complain about it.
### Mirroring with Perforce Helix via Git Fusion **(STARTER)**
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment