Clean up headers in markdown

Some markdown headers needed tweaking to adhere
to standards, including blank lines above and below,
only one space after hash, first header should be
h1, and only one h1 per doc

12 files changed, 28 insertions, 18 deletions

diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md
index 098d946a9fa..604dff5983d 100644
--- a/doc/administration/troubleshooting/debug.md
+++ b/doc/administration/troubleshooting/debug.md
@@ -209,7 +209,7 @@ ps auwx | grep unicorn | awk '{ print " -p " $2}' | xargs strace -tt -T -f -s 10
 
 The output in `/tmp/unicorn.txt` may help diagnose the root cause.
 
-# More information
+## More information
 
 - [Debugging Stuck Ruby Processes](https://blog.newrelic.com/2013/04/29/debugging-stuck-ruby-processes-what-to-do-before-you-kill-9/)
 - [Cheatsheet of using gdb and ruby processes](gdb-stuck-ruby.txt)
diff --git a/doc/api/epics.md b/doc/api/epics.md
index d05eb0a8804..3036b3c2364 100644
--- a/doc/api/epics.md
+++ b/doc/api/epics.md
@@ -10,7 +10,7 @@ If epics feature is not available a `403` status code will be returned.
 
 The [epic issues API](epic_issues.md) allows you to interact with issues associated with an epic.
 
-# Milestone dates integration
+## Milestone dates integration
 
 > [Introduced][ee-6448] in GitLab 11.3.
 
diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md
index 06a81c3d0c7..98f30350968 100644
--- a/doc/ci/pipelines.md
+++ b/doc/ci/pipelines.md
@@ -345,7 +345,7 @@ GitLab provides API endpoints to:
   - [Triggering pipelines through the API](triggers/README.md).
   - [Pipeline triggers API](../api/pipeline_triggers.md).
 
-### Start multiple manual actions in a stage
+### Start multiple manual actions in a stage
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27188) in GitLab 11.11.
 
diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md
index 3296cb173d7..7d2d1b77a0e 100644
--- a/doc/development/contributing/community_roles.md
+++ b/doc/development/contributing/community_roles.md
@@ -1,4 +1,4 @@
-### Community members & roles
+# Community members & roles
 
 GitLab community members and their privileges/responsibilities.
 
diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md
index 0d9397c3bd5..09b4a3c3d96 100644
--- a/doc/development/fe_guide/axios.md
+++ b/doc/development/fe_guide/axios.md
@@ -1,15 +1,18 @@
 # Axios
+
 We use [axios][axios] to communicate with the server in Vue applications and most new code.
 
 In order to guarantee all defaults are set you *should not use `axios` directly*, you should import `axios` from `axios_utils`.
 
 ## CSRF token
+
 All our request require a CSRF token.
 To guarantee this token is set, we are importing [axios][axios], setting the token, and exporting `axios` .
 
 This exported module should be used instead of directly using `axios` to ensure the token is set.
 
 ## Usage
+
 ```javascript
   import axios from './lib/utils/axios_utils';
 
diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md
index f895cfd36ac..95c4a094c04 100644
--- a/doc/development/fe_guide/style_guide_scss.md
+++ b/doc/development/fe_guide/style_guide_scss.md
@@ -212,6 +212,7 @@ selectors are intended for use only with JavaScript to allow for removal or
 renaming without breaking styling.
 
 ### IDs
+
 Don't use ID selectors in CSS.
 
 ```scss
diff --git a/doc/development/module_with_instance_variables.md b/doc/development/module_with_instance_variables.md
index 7bdfa04fc57..443eee0b62c 100644
--- a/doc/development/module_with_instance_variables.md
+++ b/doc/development/module_with_instance_variables.md
@@ -1,6 +1,6 @@
-## Modules with instance variables could be considered harmful
+# Modules with instance variables could be considered harmful
 
-### Background
+## Background
 
 Rails somehow encourages people using modules and instance variables
 everywhere. For example, using instance variables in the controllers,
@@ -9,7 +9,7 @@ helpers, and views. They're also encouraging the use of
 saving everything in a giant, single object, and people could access
 everything in that one giant object.
 
-### The problems
+## The problems
 
 Of course this is convenient to develop, because we just have everything
 within reach. However this has a number of downsides when that chosen object
@@ -24,7 +24,7 @@ manipulated from 3 different modules. It's hard to track when those variables
 start giving us troubles. We don't know which module would suddenly change
 one of the variables. Everything could touch anything.
 
-### Similar concerns
+## Similar concerns
 
 People are saying multiple inheritance is bad. Mixing multiple modules with
 multiple instance variables scattering everywhere suffer from the same issue.
@@ -40,7 +40,7 @@ Note that `included` doesn't solve the whole issue. They define the
 dependencies, but they still allow each modules to talk implicitly via the
 instance variables in the final giant object, and that's where the problem is.
 
-### Solutions
+## Solutions
 
 We should split the giant object into multiple objects, and they communicate
 with each other with the API, i.e. public methods. In short, composition over
@@ -53,7 +53,7 @@ With clearly defined API, this would make things less coupled and much easier
 to debug and track, and much more extensible for other objects to use, because
 they communicate in a clear way, rather than implicit dependencies.
 
-### Acceptable use
+## Acceptable use
 
 However, it's not always bad to use instance variables in a module,
 as long as it's contained in the same module; that is, no other modules or
@@ -74,7 +74,7 @@ Unfortunately it's not easy to code more complex rules into the cop, so
 we rely on people's best judgement. If we could find another good pattern
 we could easily add to the cop, we should do it.
 
-### How to rewrite and avoid disabling this cop
+## How to rewrite and avoid disabling this cop
 
 Even if we could just disable the cop, we should avoid doing so. Some code
 could be easily rewritten in simple form. Consider this acceptable method:
@@ -181,7 +181,7 @@ rather than whatever includes the module, and those modules which were also
 included, making it much easier to track down any issues,
 and reducing the chance of having name conflicts.
 
-### How to disable this cop
+## How to disable this cop
 
 Put the disabling comment right after your code in the same line:
 
@@ -210,14 +210,14 @@ end
 Note that you need to enable it at some point, otherwise everything below
 won't be checked.
 
-### Things we might need to ignore right now
+## Things we might need to ignore right now
 
 Because of the way Rails helpers and mailers work, we might not be able to
 avoid the use of instance variables there. For those cases, we could ignore
 them at the moment. At least we're not going to share those modules with
 other random objects, so they're still somewhat isolated.
 
-### Instance variables in views
+## Instance variables in views
 
 They're bad because we can't easily tell who's using the instance variables
 (from controller's point of view) and where we set them up (from partials'
diff --git a/doc/development/new_fe_guide/development/accessibility.md b/doc/development/new_fe_guide/development/accessibility.md
index 81a29170129..ae5c4c6a6cc 100644
--- a/doc/development/new_fe_guide/development/accessibility.md
+++ b/doc/development/new_fe_guide/development/accessibility.md
@@ -1,17 +1,21 @@
 # Accessiblity
+
 Using semantic HTML plays a key role when it comes to accessibility.
 
 ## Accessible Rich Internet Applications - ARIA
+
 WAI-ARIA, the Accessible Rich Internet Applications specification, defines a way to make Web content and Web applications more accessible to people with disabilities.
 
 > Note: It is [recommended][using-aria] to use semantic elements as the primary method to achieve accessibility rather than adding aria attributes. Adding aria attributes should be seen as a secondary method for creating accessible elements.
 
 ### Role
+
 The `role` attribute describes the role the element plays in the context of the document.
 
 Check the list of WAI-ARIA roles [here][roles]
 
 ## Icons
+
 When using icons or images that aren't absolutely needed to understand the context, we should use `aria-hidden="true"`.
 
 On the other hand, if an icon is crucial to understand the context we should do one of the following:
@@ -20,6 +24,7 @@ On the other hand, if an icon is crucial to understand the context we should do
 1. Use `aria-labelledby` to point to an element that contains the explanation for that icon
 
 ## Form inputs
+
 In forms we should use the `for` attribute in the label statement:
 
 ```
diff --git a/doc/development/new_fe_guide/style/index.md b/doc/development/new_fe_guide/style/index.md
index 335d9e66240..f073dc56f1f 100644
--- a/doc/development/new_fe_guide/style/index.md
+++ b/doc/development/new_fe_guide/style/index.md
@@ -8,7 +8,7 @@
 
 ## [Vue style guide](vue.md)
 
-# Tooling
+## Tooling
 
 ## [Prettier](prettier.md)
 
diff --git a/doc/development/verifying_database_capabilities.md b/doc/development/verifying_database_capabilities.md
index 661ab9cef1a..ccec6f7d719 100644
--- a/doc/development/verifying_database_capabilities.md
+++ b/doc/development/verifying_database_capabilities.md
@@ -25,7 +25,7 @@ else
 end
 ```
 
-# Read-only database
+## Read-only database
 
 The database can be used in read-only mode. In this case we have to
 make sure all GET requests don't attempt any write operations to the
diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md
index f698e0a1608..516600c9d99 100644
--- a/doc/user/admin_area/settings/usage_statistics.md
+++ b/doc/user/admin_area/settings/usage_statistics.md
@@ -52,8 +52,8 @@ You can view the exact JSON payload in the administration panel. To view the pay
 1. Expand **Settings** in the left sidebar and click on **Metrics and profiling**.
 1. Expand **Usage statistics** and click on the **Preview payload** button.
 
-You can see how [the usage ping data maps to different stages of the product](https://gitlab.com/gitlab-data/analytics/blob/master/transform/snowflake-dbt/data/ping_metrics_to_stage_mapping_data.csv). 
- 
+You can see how [the usage ping data maps to different stages of the product](https://gitlab.com/gitlab-data/analytics/blob/master/transform/snowflake-dbt/data/ping_metrics_to_stage_mapping_data.csv).
+
 ### Deactivate the usage ping
 
 The usage ping is opt-out. If you want to deactivate this feature, go to
diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md
index 6be8fc82431..90a725f271b 100644
--- a/doc/user/project/integrations/prometheus_library/haproxy.md
+++ b/doc/user/project/integrations/prometheus_library/haproxy.md
@@ -1,4 +1,5 @@
 # Monitoring HAProxy
+
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12621) in GitLab 9.4
 
 GitLab has support for automatically detecting and monitoring HAProxy. This is provided by leveraging the [HAProxy Exporter](https://github.com/prometheus/haproxy_exporter), which translates HAProxy statistics into a Prometheus readable form.