Add lint rule that headings must increment one level at a time

Also fixes instances in Markdown that broke the rule.

.gitlab/ci/docs.gitlab-ci.yml

@@ -68,7 +68,7 @@ docs lint:
     # Lint Markdown
     # https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
     - bundle exec mdl content/$DOCS_GITLAB_REPO_SUFFIX/**/*.md --ignore-front-matter --rules \
-        MD004,MD032,MD034
+        MD001,MD032,MD034
     # Build HTML from Markdown
     - bundle exec nanoc
     # Check the internal links

doc/administration/high_availability/database.md

@@ -1109,7 +1109,7 @@ If you enable Monitoring, it must be enabled on **all** database servers.
 
 ## Troubleshooting
 
-#### Consul and PostgreSQL changes not taking effect.
+### Consul and PostgreSQL changes not taking effect.
 
 Due to the potential impacts, `gitlab-ctl reconfigure` only reloads Consul and PostgreSQL, it will not restart the services. However, not all changes can be activated by reloading.
 
@@ -1119,7 +1119,7 @@ For PostgreSQL, it is usually safe to restart the master node by default. Automa
 
 On the consul server nodes, it is important to restart the consul service in a controlled fashion. Read our [consul documentation](consul.md#restarting-the-server-cluster) for instructions on how to restart the service.
 
-#### `gitlab-ctl repmgr-check-master` command produces errors
+### `gitlab-ctl repmgr-check-master` command produces errors
 
 If this command displays errors about database permissions it is likely that something failed during
 install, resulting in the `gitlab-consul` database user getting incorrect permissions. Follow these
@@ -1134,7 +1134,7 @@ steps to fix the problem:
 
 Now there should not be errors. If errors still occur then there is another problem.
 
-#### PGBouncer error `ERROR: pgbouncer cannot connect to server`
+### PGBouncer error `ERROR: pgbouncer cannot connect to server`
 
 You may get this error when running `gitlab-rake gitlab:db:configure` or you
 may see the error in the PGBouncer log file.
@@ -1162,7 +1162,7 @@ postgresql['trust_auth_cidr_addresses'] = %w(123.123.123.123/32 <other_cidrs>)
 
 [Reconfigure GitLab] for the changes to take effect.
 
-#### Issues with other components
+### Issues with other components
 
 If you're running into an issue with a component not outlined here, be sure to check the troubleshooting section of their specific documentation page.
 

doc/administration/merge_request_diffs.md

@@ -10,7 +10,7 @@ By default, merge request diffs are stored in the database, in a table named
 `merge_request_diff_files`. Larger installations may find this table grows too
 large, in which case, switching to external storage is recommended.
 
-### Using external storage
+## Using external storage
 
 Merge request diffs can be stored on disk, or in object storage. In general, it
 is better to store the diffs in the database than on disk.
@@ -59,13 +59,13 @@ To enable external storage of merge request diffs, follow the instructions below
 
 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
 
-### Using object storage
+## Using object storage
 
 Instead of storing the external diffs on disk, we recommended the use of an object
 store like AWS S3 instead. This configuration relies on valid AWS credentials to
 be configured already.
 
-### Object Storage Settings
+## Object Storage Settings
 
 For source installations, these settings are nested under `external_diffs:` and
 then `object_store:`. On Omnibus installations, they are prefixed by
@@ -80,7 +80,7 @@ then `object_store:`. On Omnibus installations, they are prefixed by
 | `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` |
 | `connection` | Various connection options described below | |
 
-#### S3 compatible connection settings
+### S3 compatible connection settings
 
 The connection settings match those provided by [Fog](https://github.com/fog), and are as follows:
 
@@ -146,7 +146,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a
 
 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
 
-### Alternative in-database storage
+## Alternative in-database storage
 
 Enabling external diffs may reduce the performance of merge requests, as they
 must be retrieved in a separate operation to other data. A compromise may be

doc/administration/uploads.md

@@ -3,7 +3,7 @@
 >**Notes:**
 Uploads represent all user data that may be sent to GitLab as a single file. As an example, avatars and notes' attachments are uploads. Uploads are integral to GitLab functionality, and therefore cannot be disabled.
 
-### Using local storage
+## Using local storage
 
 >**Notes:**
 This is the default configuration
@@ -48,7 +48,7 @@ _The uploads are stored by default in
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
-### Using object storage **(CORE ONLY)**
+## Using object storage **(CORE ONLY)**
 
 > **Notes:**
 >
@@ -60,7 +60,7 @@ If you don't want to use the local disk where GitLab is installed to store the
 uploads, you can use an object storage provider like AWS S3 instead.
 This configuration relies on valid AWS credentials to be configured already.
 
-### Object Storage Settings
+## Object Storage Settings
 
 For source installations the following settings are nested under `uploads:` and then `object_store:`. On omnibus installs they are prefixed by `uploads_object_store_`.
 
@@ -73,7 +73,7 @@ For source installations the following settings are nested under `uploads:` and
 | `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` |
 | `connection` | Various connection options described below | |
 
-#### S3 compatible connection settings
+### S3 compatible connection settings
 
 The connection settings match those provided by [Fog](https://github.com/fog), and are as follows:
 

doc/api/project_snippets.md

 # Project snippets
 
-### Snippet visibility level
+## Snippet visibility level
 
 Snippets in GitLab can be either private, internal or public.
 You can set it with the `visibility` field in the snippet.

doc/api/v3_to_v4.md

@@ -9,7 +9,7 @@ The V3 API documentation is still
 
 Below are the changes made between V3 and V4.
 
-### 8.17
+## 8.17
 
 - Removed `GET /projects/:search` (use: `GET /projects?search=x`) [!8877](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8877)
 - `iid` filter has been removed from `GET /projects/:id/issues` [!8967](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8967)
@@ -18,7 +18,7 @@ Below are the changes made between V3 and V4.
 - Project snippets do not return deprecated field `expires_at` [!8723](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8723)
 - Endpoints under `GET /projects/:id/keys` have been removed (use `GET /projects/:id/deploy_keys`) [!8716](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8716)
 
-### 9.0
+## 9.0
 
 - Status 409 returned for `POST /projects/:id/members` when a member already exists [!9093](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9093)
 - Moved `DELETE /projects/:id/star` to `POST /projects/:id/unstar` [!9328](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9328)

doc/ci/examples/end_to_end_testing_webdriverio/index.md

@@ -32,7 +32,7 @@ through the process of setting up GitLab CI/CD for end-to-end testing Javascript
 with WebdriverIO, but the general strategy should carry over to other languages.
 We assume you are familiar with GitLab, [GitLab CI/CD](../../README.md), [Review Apps](../../review_apps/index.md), and running your app locally, e.g., on `localhost:8000`.
 
-### What to test
+## What to test
 
 In the widely-used [testing pyramid strategy](https://martinfowler.com/bliki/TestPyramid.html), end-to-end tests act more like a
 safeguard: [most of your code should be covered by
@@ -42,7 +42,7 @@ will likely want to
 to just enough to give you the confidence that the deployment went as intended, that your
 infrastructure is up and running, and that your units of code work well together.
 
-### Selenium and WebdriverIO
+## Selenium and WebdriverIO
 
 [Selenium](http://www.seleniumhq.org/) is a piece of software that can control web browsers, e.g., to make them
 visit a specific URL or interact with elements on the page. It can be programmatically controlled

doc/customization/libravatar.md

@@ -6,12 +6,12 @@ Libravatar is a service which delivers your avatar (profile picture) to other we
 
 This means that it is not complicated to switch to Libravatar avatar service or even self hosted Libravatar server.
 
-# Configuration
+## Configuration
 
 In [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122) set
 the configuration options as follows:
 
-## For HTTP
+### For HTTP
 
 ```yml
   gravatar:
@@ -20,7 +20,7 @@ the configuration options as follows:
     plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
 ```
 
-## For HTTPS
+### For HTTPS
 
 ```yml
   gravatar:
@@ -29,7 +29,7 @@ the configuration options as follows:
     ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
 ```
 
-## Self-hosted
+### Self-hosted
 
 If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/) the URL will be different in the configuration
 but the important part is to provide the same placeholders so GitLab can parse the URL correctly.
@@ -38,7 +38,7 @@ For example, you host a service on `http://libravatar.example.com` the `plain_ur
 
 `http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon`
 
-## Omnibus-gitlab example
+### Omnibus-gitlab example
 
 In `/etc/gitlab/gitlab.rb`:
 
@@ -67,7 +67,7 @@ For example, you can use `retro` set in which case the URL would look like: `pla
 
 ## Usage examples
 
-#### For Microsoft Office 365
+### For Microsoft Office 365
 
 If your users are Office 365-users, the "GetPersonaPhoto" service can be used. Note that this service requires login, so this use case is
 most useful in a corporate installation, where all users have access to Office 365.

doc/development/changelog.md

@@ -144,7 +144,7 @@ If you're working on the GitLab EE repository, the entry will be added to
 | [`--type`](#--type-or--t)          | `-t`      | The category of the change, valid options are: `added`, `fixed`, `changed`, `deprecated`, `removed`, `security`, `performance`, `other` |
 | `--help`          | `-h`      | Print help message                                                                                                                      |
 
-##### `--amend`
+#### `--amend`
 
 You can pass the **`--amend`** argument to automatically stage the generated
 file and amend it to the previous commit.
@@ -166,7 +166,7 @@ author:
 type:
 ```
 
-##### `--force` or `-f`
+#### `--force` or `-f`
 
 Use **`--force`** or **`-f`** to overwrite an existing changelog entry if it
 already exists.
@@ -184,7 +184,7 @@ author:
 type:
 ```
 
-##### `--merge-request` or `-m`
+#### `--merge-request` or `-m`
 
 Use the **`--merge-request`** or **`-m`** argument to provide the
 `merge_request` value:
@@ -199,7 +199,7 @@ author:
 type:
 ```
 
-##### `--dry-run` or `-n`
+#### `--dry-run` or `-n`
 
 Use the **`--dry-run`** or **`-n`** argument to prevent actually writing or
 committing anything:
@@ -216,7 +216,7 @@ type:
 $ ls changelogs/unreleased/
 ```
 
-##### `--git-username` or `-u`
+#### `--git-username` or `-u`
 
 Use the **`--git-username`** or **`-u`** argument to automatically fill in the
 `author` value with your configured Git `user.name` value:
@@ -234,7 +234,7 @@ author: Jane Doe
 type:
 ```
 
-##### `--type` or `-t`
+#### `--type` or `-t`
 
 Use the **`--type`** or **`-t`** argument to provide the `type` value:
 

doc/development/ee_features.md

@@ -446,7 +446,6 @@ The disadvantage of this:
   port `render_if_exists` to CE.
 - If we have typos in the partial name, it would be silently ignored.
 
-
 ##### Caveats
 
 The `render_if_exists` view path argument must be relative to `app/views/` and `ee/app/views`.
@@ -973,7 +972,7 @@ For regular JS files, the approach is similar.
    1. An EE file should be created with the EE only code, and it should extend the CE counterpart.
    1. For code inside functions that can't be extended, the code should be moved into a new file and we should use `ee_else_ce` helper:
 
-##### Example:
+#### Example:
 
 ```javascript
   import eeCode from 'ee_else_ce/ee_code';
@@ -1000,7 +999,7 @@ styles are usually kept in stylesheet that is common for both CE and EE, and it
 to isolate such ruleset from rest of CE rules (along with adding comment describing the same)
 to avoid conflicts during CE to EE merge.
 
-#### Bad
+### Bad
 
 ```scss
 .section-body {
@@ -1016,7 +1015,7 @@ to avoid conflicts during CE to EE merge.
 }
 ```
 
-#### Good
+### Good
 
 ```scss
 .section-body {
@@ -1034,7 +1033,7 @@ to avoid conflicts during CE to EE merge.
 // EE-specific end
 ```
 
-### Backporting changes from EE to CE
+## Backporting changes from EE to CE
 
 Until the work completed to merge the ce and ee codebases, which is tracked on [epic &802](https://gitlab.com/groups/gitlab-org/-/epics/802), there exists times in which some changes for EE require specific changes to the CE
 code base.  Examples of backports include the following:

doc/development/fe_guide/security.md

 # Security
-### Resources
+
+## Resources
 
 [Mozilla’s HTTP Observatory CLI][observatory-cli] and the
 [Qualys SSL Labs Server Test][qualys-ssl] are good resources for finding
@@ -56,7 +57,7 @@ Some resources on implementing Subresource Integrity:
 
 -->
 
-### Including external resources
+## Including external resources
 
 External fonts, CSS, and JavaScript should never be used with the exception of
 Google Analytics and Piwik - and only when the instance has enabled it. Assets
@@ -64,7 +65,7 @@ should always be hosted and served locally from the GitLab instance. Embedded
 resources via `iframes` should never be used except in certain circumstances
 such as with ReCaptcha, which cannot be used without an `iframe`.
 
-### Avoiding inline scripts and styles
+## Avoiding inline scripts and styles
 
 In order to protect users from [XSS vulnerabilities][xss], we will disable
 inline scripts in the future using Content Security Policy.

doc/development/testing_guide/ci.md

 # GitLab tests in the Continuous Integration (CI) context
 
-### Test suite parallelization on the CI
+## Test suite parallelization on the CI
 
 Our current CI parallelization setup is as follows:
 
@@ -26,7 +26,7 @@ Our current CI parallelization setup is as follows:
 After that, the next pipeline will use the up-to-date
 `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file.
 
-### Monitoring
+## Monitoring
 
 The GitLab test suite is [monitored] for the `master` branch, and any branch
 that includes `rspec-profile` in their name.

doc/integration/oauth2_generic.md

@@ -12,7 +12,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc
 1. Strategy parses user information from the response, using a **configurable** format
 1. GitLab finds or creates the returned user and logs them in
 
-### Limitations of this Strategy:
+## Limitations of this Strategy:
 
 - It can only be used for Single Sign on, and will not provide any other access granted by any OAuth provider
   (importing projects or users, etc)
@@ -20,7 +20,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc
 - It is not able to fetch user information from more than one URL
 - It has not been tested with user information formats other than JSON
 
-### Config Instructions
+## Config Instructions
 
 1. Register your application in the OAuth2 provider you wish to authenticate with.