Unify the usage of headings in our docs

Every page should start with a level 1 heading (# Heading).

manual/auto_correct.md

@@ -1,16 +1,16 @@
-## Auto-correct
+# Auto-correct
 
 In auto-correct mode, RuboCop will try to automatically fix offenses:
 
 ```sh
 $ rubocop -a
 ```
 
-For some offenses, it is not possible to implement automatic correction. 
+For some offenses, it is not possible to implement automatic correction.
 
 Some automatic corrections that _are_ possible have not been implemented yet.
 
-### Safe auto-correct
+## Safe auto-correct
 
 ```sh
 $ rubocop --safe-auto-correct
@@ -27,7 +27,7 @@ the safety of each cop will be determined.
 
 If a cop is annotated as "not safe", it will be omitted.
 
-#### Example of Unsafe Cop
+### Example of Unsafe Cop
 
 ```ruby
 array = []
@@ -52,7 +52,7 @@ Therefore, in this (unusual) scenario, `Style/LineEndConcatenation` is unsafe.
 (This is a contrived example. Real code would use `%w` for an array of string
 literals.)
 
-### Generating comments
+## Generating comments
 
 ```sh
 $ rubocop --auto-correct --disable-uncorrectable

manual/automated_code_review.md

@@ -1,34 +1,34 @@
-## Automated Code Review
+# Automated Code Review
 
 The section describes SaaS that provides automated code reviews.
 
-### Codacy
+## Codacy
 
 [Codacy](https://www.codacy.com/) checks your code from style to security, duplication, complexity, and also integrates with coverage.
 Codacy is free for open source, and it provides RuboCop analysis out-of-the-box.
 
-### Code Climate
+## Code Climate
 
 [Code Climate](https://codeclimate.com/) provides automated code review for test coverage, complexity, duplication, security, style, and more, and merge with confidence.
 
-### CodeFactor
+## CodeFactor
 
 [CodeFactor](https://www.codefactor.io) reports various code metrics like duplication, churn, and problems for code style, performance, complexity, and many others. CodeFactor is free for open source. It supports analysis and auto-correction for RuboCop.
 
-### Hound
+## Hound
 
 [Hound](https://houndci.com/) comments on style violations in GitHub pull requests, allowing you and your team to better review and maintain a clean codebase.
 It is open source software.
 
-### Pronto
+## Pronto
 
 [Pronto](https://github.com/prontolabs/pronto) does quick automated code review of your changes. Created to be used on GitHub pull requests, but also works locally and integrates with GitLab and Bitbucket.
 
-### Sider
+## Sider
 
 [Sider](https://sider.review) improves your team's productivity by automating code analysis.
 It supports Auto-correction.
 
-### Awesome Code
+## Awesome Code
 
 [Awesome Code](https://awesomecode.io) improves your code readability by git push or sending pull requests, with one click or even fully automated. It's an online `rubocop -a` service.

manual/basic_usage.md

@@ -1,4 +1,4 @@
-## Basic Usage
+# Basic Usage
 
 RuboCop has three primary uses:
 
@@ -8,7 +8,7 @@ RuboCop has three primary uses:
 
 In the next sections we'll briefly cover all of them.
 
-### 1. Code style checker
+## 1. Code style checker
 
 Running `rubocop` with no arguments will check all Ruby source files
 in the current directory:
@@ -60,7 +60,7 @@ test.rb:4:5: W: Layout/EndAlignment: end at 4, 4 is not aligned with if at 2, 2.
 1 file inspected, 5 offenses detected
 ```
 
-#### Auto-correcting offenses
+### Auto-correcting offenses
 
 You can also run RuboCop in an auto-correct mode, where it will try to
 automatically fix the problems it found in your code:
@@ -71,7 +71,7 @@ $ rubocop -a
 
 See [Auto-correct](auto_correct.md).
 
-#### Changing what RuboCop considers to be offenses
+### Changing what RuboCop considers to be offenses
 
 RuboCop comes with a preconfigured set of rules for each of its cops, based on the [Ruby Style Guide](https://rubystyle.guide).
 Depending on your project, you may wish to reconfigure a cop, tell to ignore certain files, or disable it altogether.
@@ -81,7 +81,7 @@ project's root directory.
 
 For more information, see [Configuration](configuration.md).
 
-### 2. RuboCop as a replacement for `ruby -w`
+## 2. RuboCop as a replacement for `ruby -w`
 
 RuboCop natively implements almost all `ruby -w` lint warning checks, and then some. If you want you can use RuboCop
 simply as a replacement for `ruby -w`:
@@ -90,7 +90,7 @@ simply as a replacement for `ruby -w`:
 $ rubocop -l
 ```
 
-### 3. RuboCop as a formatter
+## 3. RuboCop as a formatter
 
 There's a handy shortcut to run auto-correction only on code layout (a.k.a. formatting) offenses:
 

manual/caching.md

@@ -1,11 +1,11 @@
-## Caching
+# Caching
 
 Large projects containing hundreds or even thousands of files can take
 a really long time to inspect, but RuboCop has functionality to
 mitigate this problem. There's a caching mechanism that stores
 information about offenses found in inspected files.
 
-### Cache Validity
+## Cache Validity
 
 Later runs will be able to retrieve this information and present the
 stored information instead of inspecting the file again. This will be
@@ -20,7 +20,7 @@ are no changes in:
 * version of the `rubocop` program (or to be precise, anything in the
   source code of the invoked `rubocop` program)
 
-### Enabling and Disabling the Cache
+## Enabling and Disabling the Cache
 
 The caching functionality is enabled if the configuration parameter
 `AllCops: UseCache` is `true`, which it is by default. The command
@@ -29,7 +29,7 @@ overriding the configuration parameter. If `AllCops: UseCache` is set
 to `false` in the local `.rubocop.yml`, then it's `--cache true` that
 overrides the setting.
 
-### Cache Path
+## Cache Path
 
 By default, the cache is stored in either
 `$XDG_CACHE_HOME/$UID/rubocop_cache` if `$XDG_CACHE_HOME` is set or in
@@ -41,7 +41,7 @@ RuboCop cache. Another could be that a Continuous Integration system
 allows directories, but not a temporary directory, to be saved between
 runs.
 
-### Cache Pruning
+## Cache Pruning
 
 Each time a file has changed, its offenses will be stored under a new
 key in the cache. This means that the cache will continue to grow

manual/configuration.md

@@ -1,4 +1,4 @@
-## Configuration
+# Configuration
 
 The behavior of RuboCop can be controlled via the
 [.rubocop.yml](https://github.com/rubocop-hq/rubocop/blob/master/.rubocop.yml)
@@ -24,7 +24,7 @@ Layout/LineLength:
     Qualifying cop name with its type, e.g., `Style`, is recommended,
     but not necessary as long as the cop name is unique across all types.
 
-### Config file locations
+## Config file locations
 
 RuboCop will start looking for the configuration file in the directory
 where the inspected file is and continue its way up to the root directory.
@@ -52,7 +52,7 @@ files:
 * `~/.config/rubocop/config.yml`
 * [RuboCop's default configuration][1]
 
-### Inheritance
+## Inheritance
 
 All configuration inherits from [RuboCop's default configuration][1] (See
 "Defaults").
@@ -64,7 +64,7 @@ Configuration" below).
 Settings in the child file (that which inherits) override those in the parent
 (that which is inherited), with the following caveats.
 
-#### Inheritance of hashes vs. other types
+### Inheritance of hashes vs. other types
 
 Configuration parameters that are hashes, for example `PreferredMethods` in
 `Style/CollectionMethods`, are merged with the same parameter in the parent
@@ -90,7 +90,7 @@ remove elements in child files.
 However, advanced users can still merge arrays using the `inherit_mode` setting.
 See "Merging arrays using inherit_mode" below.
 
-#### Inheriting from another configuration file in the project
+### Inheriting from another configuration file in the project
 
 The optional `inherit_from` directive is used to include configuration
 from one or more files. This makes it possible to have the common
@@ -109,7 +109,7 @@ inherit_from:
   - ../conf/.rubocop.yml
 ```
 
-### Inheriting configuration from a remote URL
+## Inheriting configuration from a remote URL
 
 The optional `inherit_from` directive can contain a full url to a remote
 file. This makes it possible to have common project settings stored on a http
@@ -132,7 +132,7 @@ inherit_from:
   - ../.rubocop.yml
 ```
 
-#### Inheriting configuration from a dependency gem
+### Inheriting configuration from a dependency gem
 
 The optional `inherit_gem` directive is used to include configuration from
 one or more gems external to the current project. This makes it possible to
@@ -175,7 +175,7 @@ dependency's installation path at runtime:
 $ bundle exec rubocop <options...>
 ```
 
-#### Merging arrays using inherit_mode
+### Merging arrays using inherit_mode
 
 The optional directive `inherit_mode` specifies which configuration keys that
 have array values should be merged together instead of overriding the inherited
@@ -237,15 +237,15 @@ Style/For:
 In this example the `Exclude` would only include `bar.rb`.
 
 
-### Defaults
+## Defaults
 
 The file [config/default.yml][1] under the RuboCop home directory contains the
 default settings that all configurations inherit from. Project and personal
 `.rubocop.yml` files need only make settings that are different from the
 default ones. If there is no `.rubocop.yml` file in the project, home or XDG
 directories, `config/default.yml` will be used.
 
-### Including/Excluding files
+## Including/Excluding files
 
 RuboCop does a recursive file search starting from the directory it is
 run in, or directories given as command line arguments. Files that
@@ -296,15 +296,15 @@ $ bundle exec rubocop foo.rb
 $ bundle exec rubocop --force-exclusion foo.rb
 ```
 
-#### Path relativity
+### Path relativity
 
 In `.rubocop.yml` and any other configuration file beginning with `.rubocop`,
 files, and directories are specified relative to the directory where the
 configuration file is. In configuration files that don't begin with `.rubocop`,
 e.g. `our_company_defaults.yml`, paths are relative to the directory where
 `rubocop` is run.
 
-#### Unusual files, that would not be included by default
+### Unusual files, that would not be included by default
 
 RuboCop comes with a comprehensive list of common ruby file names and
 extensions. But, if you'd like RuboCop to check files that are not included by
@@ -333,7 +333,7 @@ via [#5882](https://github.com/rubocop-hq/rubocop/pull/5882). This change allows
 people to include/exclude precisely what they need to, without the defaults
 getting in the way.
 
-##### Another example, using `inherit_mode`
+#### Another example, using `inherit_mode`
 
 ```yaml
 inherit_mode:
@@ -347,7 +347,7 @@ AllCops:
 
 See "Merging arrays using inherit_mode" above.
 
-#### Deprecated patterns
+### Deprecated patterns
 
 Patterns that are just a file name, e.g. `Rakefile`, will match
 that file name in any directory, but this pattern style is deprecated. The
@@ -369,7 +369,7 @@ is taken from the nearest `.rubocop.yml`, searching upwards. _This behavior
 will be overridden if you specify the `--ignore-parent-exclusion` command line
 argument_.
 
-#### Cop-specific `Include` and `Exclude`
+### Cop-specific `Include` and `Exclude`
 
 Cops can be run only on specific sets of files when that's needed (for
 instance you might want to run some Rails model checks only on files whose
@@ -392,12 +392,12 @@ Rails/HasAndBelongsToMany:
     - app/models/problematic.rb
 ```
 
-### Generic configuration parameters
+## Generic configuration parameters
 
 In addition to `Include` and `Exclude`, the following parameters are available
 for every cop.
 
-#### Enabled
+### Enabled
 
 Specific cops can be disabled by setting `Enabled` to `false` for that specific cop.
 
@@ -431,7 +431,7 @@ Style:
 All cops are then enabled by default. Only cops explicitly disabled
 using `Enabled: false` in user configuration files are disabled.
 
-#### Severity
+### Severity
 
 Each cop has a default severity level based on which department it belongs
 to. The level is normally `warning` for `Lint` and `convention` for all the
@@ -452,7 +452,7 @@ Metrics/CyclomaticComplexity:
   Severity: warning
 ```
 
-#### Details
+### Details
 
 Individual cops can be embellished with extra details in offense messages:
 
@@ -468,7 +468,7 @@ Layout/LineLength:
 
 These details will only be seen when RuboCop is run with the `--extra-details` flag or if `ExtraDetails` is set to true in your global RuboCop configuration.
 
-#### AutoCorrect
+### AutoCorrect
 
 Cops that support the `--auto-correct` option can have that support
 disabled. For example:
@@ -478,7 +478,7 @@ Style/PerlBackrefs:
   AutoCorrect: false
 ```
 
-### Setting the target Ruby version
+## Setting the target Ruby version
 
 Some checks are dependent on the version of the Ruby interpreter which the
 inspected code must run on. For example, enforcing using Ruby 2.3+ safe
@@ -496,7 +496,7 @@ AllCops:
 Otherwise, RuboCop will then check your project for `.ruby-version` and
 use the version specified by it.
 
-### Automatically Generated Configuration
+## Automatically Generated Configuration
 
 If you have a code base with an overwhelming amount of offenses, it can
 be a good idea to use `rubocop --auto-gen-config`, which creates
@@ -533,7 +533,7 @@ prefer to exclude files, like for other cops, add `--auto-gen-only-exclude`
 when running with `--auto-gen-config`. It will still change the maximum if the
 number of excluded files is higher than the exclude limit.
 
-### Updating the configuration file
+## Updating the configuration file
 
 When you update RuboCop version, sometimes you need to change `.rubocop.yml`.
 If you use [mry](https://github.com/pocke/mry), you can update `.rubocop.yml`
@@ -596,7 +596,7 @@ Running `rubocop --[safe-]auto-correct --disable-uncorrectable` will
 create comments to disable all offenses that can't be automatically
 corrected.
 
-### Setting the style guide URL
+## Setting the style guide URL
 
 You can specify the base URL of the style guide using `StyleGuideBaseURL`.
 If specified under `AllCops`, all cops are targeted.