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

Also fixes instances in Markdown that broke the rule.

13 files changed, 50 insertions, 50 deletions

diff --git a/.gitlab/ci/docs.gitlab-ci.yml b/.gitlab/ci/docs.gitlab-ci.yml
index 6acbce6cf0c..57ee91e4385 100644
--- a/.gitlab/ci/docs.gitlab-ci.yml
+++ b/.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
diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md
index 88b5aa883e8..d7acc1e7eb1 100644
--- a/doc/administration/high_availability/database.md
+++ b/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.
 
diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md
index 65b8c0000ce..c328d4c3aaa 100644
--- a/doc/administration/merge_request_diffs.md
+++ b/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.
@@ -46,7 +46,7 @@ To enable external storage of merge request diffs, follow the instructions below
       enabled: true
     ```
 
-1. _The external diffs will be stored in 
+1. _The external diffs will be stored in
    `/home/git/gitlab/shared/external-diffs`._ To change the path, for example,
    to `/mnt/storage/external-diffs`, edit `/home/git/gitlab/config/gitlab.yml`
    and add or amend the following lines:
@@ -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
diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md
index acfc0684f6d..c6103a28204 100644
--- a/doc/administration/uploads.md
+++ b/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:
 
diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md
index 2b2e40fb276..c1588f2292a 100644
--- a/doc/api/project_snippets.md
+++ b/doc/api/project_snippets.md
@@ -1,6 +1,6 @@
 # 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.
@@ -14,7 +14,7 @@ Constants for snippet visibility levels are:
 | `public`   | The snippet can be accessed without any authentication |
 
 NOTE: **Note:**
-From July 2019, the `Internal` visibility setting is disabled for new projects, groups, 
+From July 2019, the `Internal` visibility setting is disabled for new projects, groups,
 and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal`
 visibility setting keep this setting. You can read more about the change in the
 [relevant issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12388).
diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md
index 5752fb7c078..5f875528a6c 100644
--- a/doc/api/v3_to_v4.md
+++ b/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)
diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md
index 7f1beb96bbf..38fcf05f519 100644
--- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md
+++ b/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
@@ -40,9 +40,9 @@ unit tests](https://vincenttunru.com/100-percent-coverage/) that allow you to ea
 will likely want to
 [limit the number of end-to-end tests](https://testing.googleblog.com/2015/04/just-say-no-to-more-end-to-end-tests.html)
 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. 
+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
@@ -65,7 +65,7 @@ describe('A visitor without account', function(){
         expect(browser.getUrl()).toMatch('page-that-does-not-exist');
 
         browser.element('.content a[href="/"]').click();
-        
+
         expect(browser.getUrl()).not.toMatch('page-that-does-not-exist');
     });
 });
diff --git a/doc/customization/libravatar.md b/doc/customization/libravatar.md
index 18aaeb5a712..e618f3be2fe 100644
--- a/doc/customization/libravatar.md
+++ b/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.
diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index f13c447fef2..3ed586f07e9 100644
--- a/doc/development/changelog.md
+++ b/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:
 
diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md
index 6f4a36d4066..dc17b59a9a0 100644
--- a/doc/development/ee_features.md
+++ b/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:
diff --git a/doc/development/fe_guide/security.md b/doc/development/fe_guide/security.md
index 83bb449e54d..47ac87fc895 100644
--- a/doc/development/fe_guide/security.md
+++ b/doc/development/fe_guide/security.md
@@ -1,5 +1,6 @@
 # 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.
diff --git a/doc/development/testing_guide/ci.md b/doc/development/testing_guide/ci.md
index 7a7fca46534..87d48726268 100644
--- a/doc/development/testing_guide/ci.md
+++ b/doc/development/testing_guide/ci.md
@@ -1,6 +1,6 @@
 # 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.
diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md
index 3e72589ce12..3c1a0f2a117 100644
--- a/doc/integration/oauth2_generic.md
+++ b/doc/integration/oauth2_generic.md
@@ -1,7 +1,7 @@
 # Sign into GitLab with (almost) any OAuth2 provider
 
 The `omniauth-oauth2-generic` gem allows Single Sign On between GitLab and your own OAuth2 provider
-(or any OAuth2 provider compatible with this gem) 
+(or any OAuth2 provider compatible with this gem)
 
 This strategy is designed to allow configuration of the simple OmniAuth SSO process outlined below:
 
@@ -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.
 
@@ -57,9 +57,9 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc
 
 1. Restart GitLab for the changes to take effect
 
-On the sign in page there should now be a new button below the regular sign in form. 
+On the sign in page there should now be a new button below the regular sign in form.
 Click the button to begin your provider's authentication process. This will direct
 the browser to your OAuth2 Provider's authentication page. If everything goes well
 the user will be returned to your GitLab instance and will be signed in.
 
-[1]: https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example
\ No newline at end of file
+[1]: https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example