Enable markdownlint and fix issues

.codeclimate.yml

@@ -6,9 +6,15 @@ engines:
     enabled: true
     exclude_paths:
       - config/engines.yml
+  markdownlint:
+    enabled: true
+    checks:
+      MD002: # "First header should be a h1 header"
+        enabled: false
 ratings:
   paths:
   - "**.rb"
+  - "**.md"
 exclude_paths:
   - .bundle/
   - spec/**/*

README.md

@@ -1,4 +1,4 @@
-# Code Climate CLI<br>
+# Code Climate CLI
 
 [![Code Climate](https://codeclimate.com/github/codeclimate/codeclimate/badges/gpa.svg)](https://codeclimate.com/github/codeclimate/codeclimate)
 
@@ -90,26 +90,44 @@ Available commands:
 
 The following is a brief explanation of each available command.
 
-* `analyze`: Analyze all relevant files in the current working directory. All engines that are enabled in your `.codeclimate.yml` file will run, one after another. The `-f` (or `format`) argument allows you to set the output format of the analysis (using `json`, `text`, or `html`). The `--dev` flag lets you run your own engines during
-development.
-* `console`: start an interactive session providing access to the classes within the CLI. Useful for engine developers and maintainers.
-* `engines:disable engine_name`: Changes the engine's `enabled:` node to be `false` in your `.codeclimate.yml` file. This engine will not be run the next time your project is analyzed.
-* `engines:enable engine_name`: Installs the specified engine (`engine_name`). Also changes the engine's `enabled:` node to be `true` in your `.codeclimate.yml` file. This engine will be run the next time your project is analyzed.
-* `engines:install`: Compares the list of engines in your `.codeclimate.yml` file to those that are currently installed, then installs any missing engines.
-* `engines:list`: Lists all available engines in the [Code Climate Docker Hub](https://hub.docker.com/u/codeclimate/).
-* `engines:remove engine_name`: Removes an engine from your `.codeclimate.yml` file.
-* `help`: Displays a list of commands that can be passed to the Code Climate CLI.
-* `init`: Generates a new `.codeclimate.yml` file in the current working directory.
-* `validate-config`: Validates the `.codeclimate.yml` file in the current working directory.
-* `version`: Displays the current version of the Code Climate CLI.
-
-## Debugging
-
-Occasionally light may be shed on issues encountered during analysis by turning
-on debug mode and tweaking some additional settings that may be configured via
-environment variables.
-
-- To run `codeclimate` in debug mode:
+* `analyze`
+  Analyze all relevant files in the current working directory. All
+  engines that are enabled in your `.codeclimate.yml` file will run, one after
+  another. The `-f` (or `format`) argument allows you to set the output format of
+  the analysis (using `json`, `text`, or `html`). The `--dev` flag lets you run
+  engines not known to the CLI, for example if you're an engine author developing
+  your own, unreleased image.
+* `console`
+  start an interactive session providing access to the classes
+  within the CLI. Useful for engine developers and maintainers.
+* `engines:disable engine_name`
+  Changes the engine's `enabled:` node to be `false` in your `.codeclimate.yml`
+  file. This engine will not be run the next time your project is analyzed.
+* `engines:enable engine_name`
+  Installs the specified engine (`engine_name`). Also changes the engine's
+  `enabled:` node to be `true` in your `.codeclimate.yml` file. This engine
+  will be run the next time your project is analyzed.
+* `engines:install`
+  Compares the list of engines in your `.codeclimate.yml` file to those that
+  are currently installed, then installs any missing engines.
+* `engines:list`
+  Lists all available engines in the
+  [Code Climate Docker Hub](https://hub.docker.com/u/codeclimate/)
+  .
+* `engines:remove engine_name`
+  Removes an engine from your `.codeclimate.yml` file.
+* `help`
+  Displays a list of commands that can be passed to the Code Climate CLI.
+* `init`
+  Generates a new `.codeclimate.yml` file in the current working directory.
+* `validate-config`
+  Validates the `.codeclimate.yml` file in the current working directory.
+* `version`
+  Displays the current version of the Code Climate CLI.
+
+## Environment Variables
+
+* To run `codeclimate` in debug mode:
 
   ```
   CODECLIMATE_DEBUG=1 codeclimate analyze
@@ -118,12 +136,13 @@ environment variables.
   Prints additional information about the analysis steps, including any stderr
   produced by engines.
 
-- To increase the amount of time each engine container may run (default 15 min):
+* To increase the amount of time each engine container may run (default 15 min):
 
   ```
   CONTAINER_TIMEOUT_SECONDS=1800 codeclimate analyze // 30 minutes
   ```
-- You can also configure the default alotted memory with which each engine runs
+
+* You can also configure the default alotted memory with which each engine runs
   (default is 512_000_000 bytes):
 
   ```

WERE_HIRING.md

@@ -1,5 +1,8 @@
 # Code Climate is Hiring
 
-Thanks for checking our CLI. Since you found your way here, you may be interested in working on open source, and building awesome tools for developers. If so, you should check out our open jobs:
+Thanks for checking our CLI. Since you found your way here, you may be
+interested in working on open source, and building awesome tools for
+developers. If so, you should check out our open jobs:
+
+[http://jobs.codeclimate.com/](http://jobs.codeclimate.com/)
 
-#### http://jobs.codeclimate.com/