Merge pull request #4556 from nbehrnd/contributing

CONTRIBUTING, lint and hint to markdownlint

1 files changed, 50 insertions, 44 deletions

diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown
index 8d2a8320..430ecea0 100644
--- a/CONTRIBUTING.markdown
+++ b/CONTRIBUTING.markdown
@@ -16,27 +16,29 @@ review them more effectively and/or individually.
 
 ## Style Guidelines
 
-- **Keep lines under 80 chars**
-  + Try to keep **line length in code blocks to 80 characters or fewer**.
-  + Otherwise, the text will overflow and look odd.
-- **Prefer example to exposition**
-  + Try to use as few words as possible.
-  + Code examples are preferred over exposition in all cases.
-- **Eschew surplusage**
-  + We welcome newcomers, but the target audience for this site is programmers
-    with some experience.
-  + Try to avoid explaining basic concepts except for those specific to the
-    language in question.
-  + Keep articles succinct and scannable. We all know how to use Google here.
-- **Use UTF-8**
-  + For translations (or EN articles with non-ASCII characters) please make sure
-    your file is UTF-8 encoded.
-  + Try to leave out the byte-order-mark at the start of the file. (`:set nobomb`
-    in Vim)
-  + You can check if the file contains a BOM on Linux/Unix systems by running
+* **Keep lines under 80 chars**
+   * Try to keep **line length in code blocks to 80 characters or fewer**.
+   * Otherwise, the text will overflow and look odd.
+   * This and other potential pitfalls to format the content consistently are
+     identified by the freely available
+     [markdownlint](https://github.com/markdownlint/markdownlint).
+* **Prefer example to exposition**
+   * Try to use as few words as possible.
+   * Code examples are preferred over exposition in all cases.
+* **Eschew surplusage**
+   * We welcome newcomers, but the target audience for this site is programmers
+     with some experience.
+   * Try to avoid explaining basic concepts except for those specific to the
+     language in question.
+   * Keep articles succinct and scannable. We all know how to use Google here.
+* **Use UTF-8**
+   * For translations (or EN articles with non-ASCII characters) please ensure
+     your file is UTF-8 encoded.
+   * Try to leave out the byte-order-mark at the start of the file (in Vim, use
+     `:set nobomb`).
+   * You can check if the file contains a BOM on Linux/Unix systems by running
     `file language.html.markdown`  You will see this if it uses a BOM:
-	`UTF-8 Unicode (with BOM) text`.
-
+    `UTF-8 Unicode (with BOM) text`.
 
 ### Header configuration
 
@@ -47,31 +49,31 @@ some key information be defined in the header.
 The following fields are necessary for English articles about programming
 languages:
 
-- **language** The *programming language* in question
-- **contributors** A list of [author, URL] lists to credit
+* **language** The *programming language* in question
+* **contributors** A list of [author, URL] lists to credit
 
 Other fields:
 
-- **category**: The category of the article. So far, can be one of *language*,
+* **category**: The category of the article. So far, can be one of *language*,
   *tool* or *Algorithms & Data Structures*. Defaults to *language* if omitted.
-- **filename**: The filename for this article's code. It will be fetched, mashed
+* **filename**: The filename for this article's code. It will be fetched, mashed
   together, and made downloadable.
-    + For non-English articles, *filename* should   have a language-specific 
-      suffix.
-- **lang**: For translations, the human language this article is in. For
+   * For non-English articles, *filename* should   have a language-specific
+     suffix.
+* **lang**: For translations, the human language this article is in. For
   categorization, mostly.
 
 Here's an example header for an Esperanto translation of Ruby:
 
 ```yaml
----
+*--
 language: ruby
 filename: learnruby-epo.ruby
 contributors:
     - ["Doktor Esperanto", "http://example.com/"]
     - ["Someone else", "http://someoneelseswebsite.com/"]
 lang: ep-ep
----
+*--
 ```
 
 ### Should I add myself as a Contributor?
@@ -85,21 +87,25 @@ addition or not.
 
 You can build the site locally to test your changes. Follow the steps below.
 
-* Install Ruby language runtime and RubyGems. See [here](https://middlemanapp.com/basics/install/) for more details.
-* Clone or zip download the [learnxinyminutes-site](https://github.com/adambard/learnxinyminutes-site) repo.
-	* `git clone https://github.com/adambard/learnxinyminutes-site`
+* Install Ruby language runtime and RubyGems. See
+  [here](https://middlemanapp.com/basics/install/)
+  for more details.
+* Clone or zip download the
+  [learnxinyminutes-site](https://github.com/adambard/learnxinyminutes-site)
+  repository.
+   * `git clone https://github.com/adambard/learnxinyminutes-site`
 * Install Middleman and other required dependencies using Bundler.
-	* `cd learnxinyminutes-site/`
-	* `bundle install`
+   * `cd learnxinyminutes-site/`
+   * `bundle install`
 * Get the source in place
-	* Copy the contents of your clone of the fork of learnxinyminutes-docs repo
-	into the `source/docs` folder. There shouldn't be a `learnxinyminutes-docs`
-	folder inside the `docs` folder, it should just contain all the repo
-	contents.
-	* Checkout your fork of the learnxinyminutes-docs repo as `source/docs`.
-		* `cd source/docs/`
-		* `git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./source/docs/`
+   * Copy the contents of your clone of the fork of learnxinyminutes-docs repo
+     into the `source/docs` folder. There shouldn't be a `learnxinyminutes-docs`
+     folder inside the `docs` folder, it should just contain all the repo
+     contents.
+   * Checkout your fork of the learnxinyminutes-docs repo as `source/docs`.
+      * `cd source/docs/`
+      * `git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./source/docs/`
 * Build the site or run a development server to test your changes (NOTE: run
-these commands at `learnxinyminutes-site/`).
-	* Build - `bundle exec middleman build`
-	* Dev server - `bundle exec middleman --force-polling --verbose`
+  these commands at `learnxinyminutes-site/`).
+   * Build - `bundle exec middleman build`
+   * Dev server - `bundle exec middleman --force-polling --verbose`