Merge pull request #4556 from nbehrnd/contributing

CONTRIBUTING, lint and hint to markdownlint

CONTRIBUTING.markdown

@@ -16,28 +16,30 @@ review them more effectively and/or individually.
 
 ## Style Guidelines
 
-- **Keep lines under 80 chars**
+* **Keep lines under 80 chars**
-  + Try to keep **line length in code blocks to 80 characters or fewer**.
+   * Try to keep **line length in code blocks to 80 characters or fewer**.
-  + Otherwise, the text will overflow and look odd.
+   * Otherwise, the text will overflow and look odd.
-- **Prefer example to exposition**
+   * This and other potential pitfalls to format the content consistently are
-  + Try to use as few words as possible.
+     identified by the freely available
-  + Code examples are preferred over exposition in all cases.
+     [markdownlint](https://github.com/markdownlint/markdownlint).
-- **Eschew surplusage**
+* **Prefer example to exposition**
-  + We welcome newcomers, but the target audience for this site is programmers
+   * 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
+   * 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.
+   * Keep articles succinct and scannable. We all know how to use Google here.
-- **Use UTF-8**
+* **Use UTF-8**
-  + For translations (or EN articles with non-ASCII characters) please make sure
+   * 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. (`:set nobomb`
+   * Try to leave out the byte-order-mark at the start of the file (in Vim, use
-    in Vim)
+     `:set nobomb`).
-  + You can check if the file contains a BOM on Linux/Unix systems by running
+   * 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`.
 
-
 ### Header configuration
 
 The actual site uses Middleman to generate HTML files from these Markdown ones.
@@ -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
+* **language** The *programming language* in question
-- **contributors** A list of [author, URL] lists to credit
+* **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 
+   * For non-English articles, *filename* should   have a language-specific
      suffix.
-- **lang**: For translations, the human language this article is in. For
+* **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,8 +87,12 @@ 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.
+* Install Ruby language runtime and RubyGems. See
-* Clone or zip download the [learnxinyminutes-site](https://github.com/adambard/learnxinyminutes-site) repo.
+  [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/`
@@ -100,6 +106,6 @@ You can build the site locally to test your changes. Follow the steps below.
       * `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/`).
+  these commands at `learnxinyminutes-site/`).
    * Build - `bundle exec middleman build`
    * Dev server - `bundle exec middleman --force-polling --verbose`