Update docs

CHANGELOG

@@ -0,0 +1,55 @@
+## [1.2.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.2.0)
+
+### Bug Fixes
+
+- Table weren't filling the entire width of the content container. They now scale at 100%. Thanks [@dhruvbhatia](https://github.com/dhruvbhatia)
+
+### Enhancements
+
+- Decreased spacing between Markdown footnotes
+- Removed dark background on footer
+- Removed UPPERCASE styling on post titles in the index listing
+
+## [1.1.4](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.1.4)
+
+### Bug Fixes
+
+- Fix top navigation bug issue ([#10](https://github.com/mmistakes/minimal-mistakes/issues/10)) for real this time. Remember to clear your floats kids.
+
+## [1.1.3](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.1.3)
+
+### Bug Fixes
+
+- Fix top navigation links that weren't click able on small viewports (Issue [#10](https://github.com/mmistakes/minimal-mistakes/issues/10)).
+- Remove line wrap from top navigation links that may span multiple lines.
+
+## [1.1.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.1.2)
+
+### Enhancements
+
+- Added Grunt build script for compiling Less/JavaScript and optimizing image assets.
+- Added support for large image summary Twitter card.
+- Stylesheet adjustments
+
+## [1.1.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.1.1)
+
+### Bug Fixes
+
+- Removed [Typeplate](http://typeplate.com/) styles. Was [causing issues with newer versions of Less](https://github.com/typeplate/typeplate.github.io/issues/108) and is no longer maintained.
+
+### Enhancements
+
+- Added [image attribution](http://mmistakes.github.io/minimal-mistakes/theme-setup/#feature-images) for post and page feature images.
+- Added [404 page](http://mmistakes.github.io/minimal-mistakes/404.html).
+- Cleaned up various Less variables to better align with naming conventions used in other MM Jekyll themes.
+- Removed Chrome Frame references.
+- Added global CSS3 transitions to text and block elements.
+- Improved typography in a few places.
+
+## [1.0.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/v1.0.2)
+
+### Enhancements
+
+- Google Analytics, Google Authorship, webmaster verifies, and Twitter card meta are now optional.
+
+## [1.0.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/v1.0.1)

README

@@ -1,16 +1,16 @@
-# Minimal Mistakes
+# Minimal Mistakes Jekyll Theme
 
 **[Minimal Mistakes](http://mmistakes.github.io/minimal-mistakes)** is a two column responsive Jekyll theme perfect for powering your GitHub hosted blog built. Compatible with Jekyll 3.0 and up.
 
 ## Minimal Mistakes is all about:
 
-* Responsive templates. Looking good on mobile, tablet, and desktop.
+- Responsive templates. Looking good on mobile, tablet, and desktop.
-* Gracefully degrading in older browsers. Compatible with Internet Explorer 8+ and all modern browsers.
+- Gracefully degrading in older browsers. Compatible with Internet Explorer 8+ and all modern browsers.
-* Minimal embellishments -- content first.
+- Minimal embellishments -- content first.
-* Optional large feature images for posts and pages.
+- Optional large feature images for posts and pages.
-* Simple and clear permalink structure.
+- Simple and clear permalink structure.
-* [Custom 404 page](http://mmistakes.github.io/minimal-mistakes/404.html) to get you started.
+- [Custom 404 page](http://mmistakes.github.io/minimal-mistakes/404.html) to get you started.
-* Support for Disqus Comments
+- Support for Disqus Comments
 
 ![screenshot of Minimal Mistakes theme](http://mmistakes.github.io/minimal-mistakes/images/mm-theme-post-600.jpg)
 

_config.yml

@@ -108,6 +108,7 @@ exclude:
   - assets/js/_main.js
   - assets/js/vendor
   - Capfile
+  - CHANGELOG
   - config
   - Gemfile
   - Gruntfile.js

_docs/03-installation.md

@@ -14,7 +14,7 @@ modified: 2016-04-13T15:54:02-04:00
 
 There are several ways to install the theme:
 
-**1.** For a **new site**, fork the Minimal Mistakes repo on GitHub. If you plan on hosting your site with GitHub Pages follow the steps outlined in the *Quick-Start Guide*.
+**1.** For a **new site**, fork the Minimal Mistakes repo on GitHub. If you plan on hosting your site with GitHub Pages follow the steps outlined in the [*Quick-Start Guide*]({{ base_path }}/docs/quick-start-guide/).
 
 **2.** For an **existing site** you have some more work ahead of you. What I suggest is to fork and rename the theme's repo as before, then clone it locally by running `git clone https://github.com/USERNAME/REPONAME.git` --- replacing **USERNAME** and **REPONAME** with your own.
 
@@ -32,13 +32,13 @@ There are several ways to install the theme:
 
 ---
 
-To move over any existing content you'll want to copy the contents of your `_posts` folder to the new site. Along with any pages, collections, data files, images, or other assets.
+To move over any existing content you'll want to copy the contents of your `_posts` folder to the new site. Along with any pages, collections, data files, images, or other assets you may have.
 
 Next you'll need to convert posts and pages to use the proper layouts and settings. In most cases you simply need to update `_config.yml` to your liking and set the correct `layout` in their YAML Front Matter.
 
 [**Front Matter defaults**](https://jekyllrb.com/docs/configuration/#front-matter-defaults) are your friend and I encourage you to leverage them instead of setting a layout and other global options in each post/page's YAML Front Matter.
 
-With something like this in your `_config.yml` all posts can be assigned the `single` page layout with reading time, comments, social sharing links, and related posts enabled.
+Posts can be configured to use the `single` layout --- with reading time, comments, social sharing links, and related posts enabled. Adding the following to `_config.yml` will set these defaults for all posts:
 
 ```yaml
 defaults:
@@ -54,16 +54,16 @@ defaults:
       related: true
 ```
 
-**Post/Page Settings**: Be sure to read through the "Working with Posts/Pages/Collections" documentation to learn about all the options available to you. Minimal Mistakes has been designed to be flexible, with numerous settings for toggling features on/off.
+**Post/Page Settings**: Be sure to read through the "Working with..." documentation to learn about all the options available to you. The theme has been designed to be flexible --- with numerous settings for each.
 {: .notice--info}
 
 ## Install Dependencies
 
-If this is your first time using Jekyll be sure to read through the [official documentation](https://jekyllrb.com/docs/home/) to familiarize yourself. This guide assumes you've done that and have Jekyll v3 and Ruby v2 installed.
+If this is your first time using Jekyll be sure to read through the [official documentation](https://jekyllrb.com/docs/home/) before jumping in. This guide assumes you have Ruby v2 installed and a basic understanding of how Jekyll works.
 
-To keep your sanity and better manage dependencies I strongly urge you to [install Bundler](http://bundler.io/) with `gem install bundler` and use the included [`Gemfile`]({{ site.gh_repo }}/blob/master/Gemfile). Minimal Mistake's Gemfile defaults to the `github-pages` gem to maintain a local Jekyll environment in sync with GitHub Pages.
+To keep your sanity and better manage dependencies I strongly urge you to [install Bundler](http://bundler.io/) with `gem install bundler` and use the included [`Gemfile`]({{ site.gh_repo }}/blob/master/Gemfile). The theme's Gemfile includes the `github-pages` gem to maintain a local Jekyll environment in sync with GitHub Pages.
 
-If you're not planning on hosting with GitHub Pages and want to leverage features found in the latest version of Jekyll replace `gem "github-pages"` with `gem "jekyll"` in your `Gemfile` and then run:
+If you're not planning on hosting with GitHub Pages and want to leverage features found in the latest version of Jekyll, replace `gem "github-pages"` with `gem "jekyll"` in your `Gemfile`. In either case run the following:
 
 ```bash
 $ bundle install
@@ -73,8 +73,8 @@ $ bundle install
   <img src="{{ base_path }}/images/mm-bundle-install.gif" alt="bundle install in Terminal window">
 </figure>
 
-Depending on what gems you already have installed you may have to run `bundle update` to clear up any dependency issues. Bundler is usually pretty good at letting you know what the issue is to work through them.
+Depending on what gems you already have installed you may have to run `bundle update` to clear up any dependency issues. Bundler is usually pretty good at letting you know what gems need updating or have issues installing, to further investigate.
 
-When using Bundler to manage gems you'll want to run Jekyll using `bundle exec jekyll serve` and `bundle exec jekyll build`. Essentially prepending any Jekyll command with `bundle exec`.
+When using Bundler to manage gems you'll want to run Jekyll using `bundle exec jekyll serve` and `bundle exec jekyll build`.
 
-Doing so executes the gem versions specified in `Gemfile.lock`. Sure you can go cowboy and test your luck with a naked `jekyll serve`. A lot of Jekyll errors I see can be tracked down to gems fighting with each other. So do yourself a favor and just use Bundler.
+Doing so executes the gem versions specified in `Gemfile.lock`. Sure you can test your luck with a naked `jekyll serve`, but I wouldn't suggest it. A lot of Jekyll errors originate from outdated or conflicting gems fighting with each other. So do yourself a favor and just use Bundler.

_docs/04-upgrading.md

@@ -14,7 +14,7 @@ Currently there is no good way of upgrading the theme without doing a bit of man
 
 ## Use Git
 
-If you want to get the most out of the Jekyll + GitHub Pages workflow, then you'll need to utilize Git. To pull down theme updates you must first ensure there's an upstream remote. If you forked the Minimal Mistakes repo then you're likely good to go.
+If you want to get the most out of the Jekyll + GitHub Pages workflow, then you'll need to utilize Git. To pull down theme updates you must first ensure there's an upstream remote. If you forked the theme's repo then you're likely good to go.
 
 To double check, run `git remote -v` and verify that you can fetch from `origin {{ site.gh_repo }}/minimal-mistakes.git`.
 
@@ -26,23 +26,25 @@ $ git remote add upstream {{ site.gh_repo }}/minimal-mistakes.git
 
 ### Pull Down Updates
 
-Now you can pull any commits made to Minimal Mistakes `master` branch with:
+Now you can pull any commits made to theme's `master` branch with:
 
 ```bash
 $ git pull upstream master
 ```
 
-Depending on the amount of customizations you've made after forking, there's likely to be merge conflicts. Work through the files Git lists as having conflicts and you should be all set.
+Depending on the amount of customizations you've made after forking, there's likely to be merge conflicts. Work through any conflicting files Git flags, stagging the changes you wish to keep, and then commit them.
 
 ## Update Files Manually
 
-The alternate way of dealing with updates is [downloading the theme]({{ site.gh_repo }}/archive/master.zip) --- replacing your layouts, includes, and assets with the newer ones. To be sure that you don't miss any changes it's probably a good idea to review the [history]({{ site.gh_repo }}/commits/master) to see what's changed since you last forked/cloned the theme.
+Another way of dealing with updates is [downloading the theme]({{ site.gh_repo }}/archive/master.zip) --- replacing your layouts, includes, and assets with the newer ones manually. To be sure that you don't miss any changes it's probably a good idea to review the theme's [commit history]({{ site.gh_repo }}/commits/master) to see what's changed since.
 
 Here's a quick checklist of the important folders/files you'll want to be mindful of:
 
-* `_layouts`
+| Name                   |     |
-* `_includes`
+| ----                   | --- |
-* `assets` --- if you customized the stylesheets or added your own scripts make sure you reapply those changes
+| `_layouts`             | Replace all. Apply edits if you customized any layouts. |
-* `_data\navigation.yml` --- you likely edited this so double check that there were no major structural changes
+| `_includes`            | Replace all. Apply edits if you customized any includes. |
-* `_data\ui-text.yml` --- same as above
+| `assets`               | Replace all. Apply edits if you customized stylesheets or scripts. |
-* `_config.yml` --- same as above
+| `_data/navigation.yml` | Safe to keep. Verify that there were no major structural changes or additions. |
+| `_data/ui-text.yml`    | Safe to keep. Verify that there were no major structural changes or additions. |
+| `_config.yml`          | Safe to keep. Verify that there were no major structural changes or additions. |

_docs/05-configuration.md

@@ -15,7 +15,7 @@ Settings that affect your entire site can be changed in [Jekyll's configuration
 **Note:** for technical reasons, `_config.yml` is NOT reloaded automatically when used with `jekyll serve`. If you make any changes to this file, please restart the server process for them to be applied.
 {: .notice--warning}
 
-Take a moment to look over the configuration file included with the theme. Light comments have been added to provide examples and defaults values for most variables. Detailed explanations of each can be found below.
+Take a moment to look over the configuration file included with the theme. Comments have been added to provide examples and default values for most settings. Detailed explanations of each can be found below.
 
 ## Site Settings
 
@@ -23,23 +23,23 @@ Take a moment to look over the configuration file included with the theme. Light
 
 `site.locale` is used to declare the primary language for each web page within the site.
 
-*Example:* `locale: "en-US"` sets the `lang` attribute for the site to *United States* flavor of English, while `en-GB` would be for the `United Kingdom` style of English. Country codes are optional and the shorter `locale: "en"` is also acceptable. To find your language and country codes check this [reference table](https://msdn.microsoft.com/en-us/library/ee825488(v=cs.20).aspx). 
+*Example:* `locale: "en-US"` sets the `lang` attribute for the site to the *United States* flavor of English, while `en-GB` would be for the `United Kingdom` style of English. Country codes are optional and the shorter `locale: "en"` is also acceptable. To find your language and country codes check this [reference table](https://msdn.microsoft.com/en-us/library/ee825488(v=cs.20).aspx). 
 
-Properly setting the locale is important for associating localized text found in the **UI Text** data file. For more information on that see below.
+Properly setting the locale is important for associating localized text found in the [**UI Text**]({{ base_path }}/docs/ui-text/) data file. For more information on that see below.
 
 ### Site Title
 
-The name of your site. Is used throughout the theme in places like masthead and `<title>` tags.
+The name of your site. Is used throughout the theme in places like the site masthead and `<title>` tags.
 
 *Example:* `title: "My Awesome Site"`
 
-You also have the option of customizing the character used in SEO-friendly page titles.
+You also have the option of customizing the separation character used in SEO-friendly page titles.
 
 *Example:* `title_separator: "|"` would produce page titles like `Sample Page | My Awesome Site`.
 
 ### Site Name
 
-Used to assign a site author. Don't worry, you can assign different authors on specific posts, pages, or collections if you desire.
+Used to assign a site author. Don't worry, you can override the site author with different ones on specific posts, pages, or collection documents.
 
 *Example:* `name: "Michael Rose"`.
 
@@ -54,19 +54,19 @@ Fairly obvious. `site.description` describes the site. Used predominantly in met
 
 ### Site URL
 
-The base hostname and protocol for your site. If you're hosting with GitHub Pages this will be something like `url: "http://github.io.mmistakes"`, or for self-hosting `url: "https://mademistakes.com"`.
+The base hostname and protocol for your site. If you're hosting with GitHub Pages this will be something like `url: "http://github.io.mmistakes"` or `url: "https://mademistakes.com"` if you have a custom domain name.
 
-**Note:** It's important to remember that when testing locally you need to change this. Ideally you'd use [multiple config files](https://mademistakes.com/articles/using-jekyll-2016/#environments-and-configurations) with `bundle exec jekyll serve --config _config.yml,_config.dev.yml` to apply development override settings. Simply commenting out the line works as well `# url: "http://mmistakes.github.io"`. Just remember to uncomment it before pushing or else you'll have broken assets and links all over the place!
+**Note:** It's important to remember that when testing locally you need to change the `site.url`. Ideally you'd use [multiple config files](https://mademistakes.com/articles/using-jekyll-2016/#environments-and-configurations) with `bundle exec jekyll serve --config _config.yml,_config.dev.yml` to apply development overrides. Simply commenting out the line works as well `# url: "http://mmistakes.github.io"`. Just remember to uncomment it before pushing or else you'll have broken assets and links all over the place!
 {: .notice--warning}
 
-**ProTip:** GitHub serves pages over `http://` and `https://` so to take advantage of that go protocol-less like so `url: "//github.io.mmistakes"`.
+**ProTip:** GitHub serves pages over `http://` and `https://` so to take advantage of that go protocol-less like so `url: "//github.io.mmistakes"`. Mre info on serving your GitHub Pages hosted site over https can be [found here](https://konklone.com/post/github-pages-now-sorta-supports-https-so-use-it).
 {: .notice--info}
 
 ### Site Base URL
 
 This little option causes all kinds of confusion in the Jekyll community. If you're not hosting your site as a GitHub Pages Project or in a subfolder (eg: `/blog`), then don't mess with it.
 
-In the case of the Minimal Mistakes demo site it's hosting on GitHub Pages at <https://mmistakes.github.io/minimal-mistakes>. To correctly set this base path I'd use `url: "https://mmistakes.github.io"` and `baseurl: "/minimal-mistakes"`.
+In the case of the Minimal Mistakes demo site it's hosted on GitHub at <https://mmistakes.github.io/minimal-mistakes>. To correctly set this base path I'd use `url: "https://mmistakes.github.io"` and `baseurl: "/minimal-mistakes"`.
 
 For more information on how to properly use `site.url` and `site.baseurl` as intended by the Jekyll maintainers, check [Parker Moore's post on the subject](https://byparker.com/blog/2014/clearing-up-confusion-around-baseurl/).
 
@@ -75,7 +75,7 @@ For more information on how to properly use `site.url` and `site.baseurl` as int
 
 ### Site Default Teaser Image
 
-To assign a fallback teaser image used in modules like the "**Related Posts**" module, place a graphic in the `/images/` directory and add the filename to `_config.yml` like so:
+To assign a fallback teaser image used in the "**Related Posts**" module, place a graphic in the `/images/` directory and add the filename to `_config.yml` like so:
 
 ```yaml
 teaser: "500x300.png"
@@ -90,12 +90,12 @@ header:
 
 <figure>
   <img src="{{ base_path }}/images/mm-teaser-images-example.jpg" alt="teaser image example">
-  <figcaption>Teasers images as shown in the grid archive view for related posts.</figcaption>
+  <figcaption>Example of teaser images found in the related posts module.</figcaption>
 </figure>
 
 ### Breadcrumb Navigation (Beta)
 
-Enable breadcrumb links to help visitors better navigate deeply structure sites. Because of the fragile method of implementing them they don't always produce accurate links reliably. For best results:
+Enable breadcrumb links to help visitors better navigate deep sites. Because of the fragile method of implementing them they don't always produce accurate links reliably. For best results:
 
 1. Use a category based permalink structure e.g. `permalink: /:categories/:title/`
 2. Manually create pages for each category or use a plugin like [jekyll-archives][jekyll-archives] to auto-generate them. If these pages don't exist breadcrumb links to them will be broken.
@@ -106,15 +106,15 @@ Enable breadcrumb links to help visitors better navigate deeply structure sites.
 breadcrumbs: true  # disabled by default
 ```
 
-Breadcrumb start link text and separator character can both be changed in the UI Text data file.
+Breadcrumb start link text and separator character can both be changed in the [UI Text data file]({{ base_path }}/docs/ui-text/).
 
 ### Reading Time
 
-Enable estimated reading time snippets with `read_time: true` in YAML Front Matter. 200 has been set as the default words per minute, which can be changed by adjusting `words_per_minutes: 200` in `_config.yml`.
+Enable estimated reading time snippets with `read_time: true` in YAML Front Matter. `200` has been set as the default words per minute value --- which can be changed by adjusting `words_per_minutes: ` in `_config.yml`.
 
 ![reading time example]({{ base_path }}/images/mm-read-time-example.jpg)
 
-Instead of adding YAML Front Matter to each document, apply as a default in `_config.yml`. To enable the **reading time** snippet for all posts:
+Instead of adding `read_time: true` to each post, apply as a default in `_config.yml` like so:
 
 ```yaml
 defaults:
@@ -126,18 +126,18 @@ defaults:
       read_time: true
 ```
 
-If you add `read_time: false` to a post's YAML Front Matter it will override the default and "reading time" for just that post.
+To disable reading time for a post, add `read_time: false` its YAML Front Matter to override what was set in `_config.yml`.
 
 ### Comments
 
 Commenting for [**Disqus**](https://disqus.com/), [**Facebook**](https://developers.facebook.com/docs/plugins/comments), and **Google+** are built into the theme. First set the comment provider you'd like to use: 
 
-|               | Comment Provider  |
+| Name            | Comment Provider  |
-| ------------- | ----------------  |
+| ----            | ----------------  |
-| `disqus`      | Disqus            |
+| **disqus**      | Disqus            |
-| `facebook`    | Facebook Comments |
+| **facebook**    | Facebook Comments |
-| `google-plus` | Google+ Comments  |
+| **google-plus** | Google+ Comments  |
-| `custom`      | Other             |
+| **custom**      | Other             |
 
 Then add `comments: true` to each document you want comments visible on.
 
@@ -157,7 +157,7 @@ If you add `comments: false` to a post's YAML Front Matter it will override the
 
 ##### Disqus
 
-To use Disqus you'll need to create an account and get a [shortname](https://help.disqus.com/customer/portal/articles/466208-what-s-a-shortname-). Once you have one update `_config.yml` to:
+To use Disqus you'll need to create an account and [shortname](https://help.disqus.com/customer/portal/articles/466208-what-s-a-shortname-). Once you have both update `_config.yml` to:
 
 ```yaml
 comments:
@@ -185,7 +185,7 @@ To use another provider not included with the theme set `provider: "custom"` the
 
 ### SEO, Social Sharing, and Analytics Settings
 
-All optional, but a good idea to take the time setting up to activate various tools for optimizing your site for search engines and link sharing.
+All optional, but a good idea to take the time setting up to improve SEO and links shared from the site.
 
 #### Google Search Console
 
@@ -234,23 +234,23 @@ To improve the appearance of links shared from your site to social networks like
 
 ##### Site Twitter Username
 
-Twitter username for the site. For documents that have custom author Twitter accounts assigned in YAML Front Matter or a data file, those will be attributed as a **creator** in the Twitter Card. 
+Twitter username for the site. For pages that have custom author Twitter accounts assigned in their YAML Front Matter or data file, they will be attributed as a **creator** in the Twitter Card. 
 
-For example if my site's Twitter account is @mmistakes-theme I would add the following to `_config.yml`
+For example if my site's Twitter account is `@mmistakes-theme` I would add the following to `_config.yml`
 
 ```yaml
 twitter:
   username: "mmistakes-theme"
 ```
 
-And if I assign `@mmistakes` as an author account it will appear in the Twitter Card along with `@mmistakes-theme` attributed as a creator or document being shared.
+And if I assign `@mmistakes` as an author account it will appear in the Twitter Card along with `@mmistakes-theme`, attributed as a creator of the page being shared.
 
 **Note**: You need to [apply for Twitter Cards](https://dev.twitter.com/docs/cards) and validate they're working on your site before they will begin showing up.
 {: .notice--warning}
 
 ##### Facebook Open Graph
 
-If you have Facebook ID or publisher page add them:
+If you have a Facebook ID or publisher page add them:
 
 ```yaml
 facebook:
@@ -262,7 +262,7 @@ While not part a part of Open Graph, you can also add your Facebook username for
 
 ```yaml
 facebook:
-  username: "michaelrose"  # ref. page https://www.facebook.com/michaelrose
+  username: "michaelrose"  # https://www.facebook.com/michaelrose
 ```
 
 **ProTip:** To debug Open Graph data use [this tool](https://developers.facebook.com/tools/debug/og/object?q=https%3A%2F%2Fmademistakes.com) to test your pages. If content changes aren't reflected you will probably have to hit the **Fetch new scrape information** button to refresh.
@@ -270,7 +270,7 @@ facebook:
 
 ##### Open Graph Default Image
 
-For documents who don't have a `header.image` assigned in their YAML Front Matter, `site.og_image` will be used as a fallback. Your logo, icon, or avatar are something else that is meaningful. Just make sure it is place in the `/images/` folder, a minimum size of 120px by 120px, and less than 1MB in file size. *The image will be cropped to a square on all platforms.*
+For pages that don't have a `header.image` assigned in their YAML Front Matter, `site.og_image` will be used as a fallback. Use you logo, icon, avatar or something else that is meaningful. Just make sure it is place in the `/images/` folder, a minimum size of 120px by 120px, and less than 1MB in file size.
 
 ```yaml
 og_image: "site-logo.png"
@@ -299,8 +299,8 @@ Use markup on your official website to add your [social profile information](htt
 
 ```yaml
 social:
-  type :  # Person or Organization (defaults to Person)
+  type:  # Person or Organization (defaults to Person)
-  name :  # If the user or organization name differs from the site's name
+  name:  # If the user or organization name differs from the site's name
   links:
     - "https://twitter.com/yourTwitter"
     - "https://facebook.com/yourFacebook"
@@ -313,11 +313,11 @@ social:
 
 Analytics is disabled by default. To enable globally select one of the following:
 
-|                    | Analytics Provider                                              |
+| Name                 | Analytics Provider                                              |
-| ------------------ | ------------------                                              |
+| ----                 | ------------------                                              |
-| `google`           | [Google Standard Analytics](https://www.google.com/analytics/)  |
+| **google**           | [Google Standard Analytics](https://www.google.com/analytics/)  |
-| `google-universal` | [Google Universal Analytics](https://www.google.com/analytics/) |
+| **google-universal** | [Google Universal Analytics](https://www.google.com/analytics/) |
-| `custom`           | Other analytics providers                                       |
+| **custom**           | Other analytics providers                                       |
 
 For Google Analytics add your Tracking Code:
 
@@ -335,19 +335,19 @@ Used as the defaults for defining what appears in the author sidebar.
 
 ![author sidebar example]({{ base_path }}/images/mm-author-sidebar-example.jpg)
 
-**Note:** For sites with multiple authors these values can be overridden post by post with custom YAML Front Matter and a data file. For more information on how that see below.
+**Note:** For sites with multiple authors these values can be overridden post by post with custom YAML Front Matter and a data file. For more information on how that works see below.
 {: .notice--info}
 
 ```yaml
 author:
   name   : "Your Name"
   avatar : "bio-photo.jpg"  # placed in /images/
-  bio    : "My awesome biography constrained to a sentence or goes here."
+  bio    : "My awesome biography constrained to a sentence or two goes here."
   email  : # optional
   uri    : "http://your-site.com"
 ```
 
-Social media links are all optional, include the ones you want visible. In most cases you just need to add the username. If you're unsure double check `_includes/author-profile.html`.
+Social media links are all optional, include the ones you want visible. In most cases you just need to add the username. If you're unsure double check `_includes/author-profile.html` to see how the URL is constructed.
 
 ## Reading Files
 
@@ -355,13 +355,13 @@ Nothing out of the ordinary here. `include` and `exclude` may be the only things
 
 ## Conversion and Markdown Processing
 
-Again nothing out of the ordinary here as the theme adheres to the defaults used by GitHub Pages. [**Kramdown**](http://kramdown.gettalong.org/) for Markdown conversion, [**Rouge**](http://rouge.jneen.net/) syntax highlighting, and incremental building disabled.
+Again nothing out of the ordinary here as the theme adheres to the defaults used by GitHub Pages. [**Kramdown**](http://kramdown.gettalong.org/) for Markdown conversion, [**Rouge**](http://rouge.jneen.net/) syntax highlighting, and incremental building disabled. Change them if you need to.
 
 ## Front Matter Defaults
 
 To save yourself time setting [Front Matter Defaults](https://jekyllrb.com/docs/configuration/#front-matter-defaults) for posts, pages, and collections is the way to go. Sure you can assign layouts and toggle settings like **reading time**, **comments**, and **social sharing** in each file, but that's not ideal.
 
-Using the `default` key in `_config.yml` you could set the layout and enable author profiles, reading time, comments, social sharing, and related posts for all posts.
+Using the `default` key in `_config.yml` you could set the layout and enable author profiles, reading time, comments, social sharing, and related posts for all posts --- in one shot.
 
 ```yaml
 defaults:
@@ -406,7 +406,7 @@ And of course any default value can be overridden by settings in a post, page, o
 
 ## Outputting
 
-The default permalink style used by Minimal Mistakes is `permalink: /:categories/:title/`. If you have a post named `2016-01-01-my-post.md` with `categories: foo` in the YAML Front Matter, Jekyll will generate `/foo/my-post/index.html`.
+The default permalink style used by the theme is `permalink: /:categories/:title/`. If you have a post named `2016-01-01-my-post.md` with `categories: foo` in the YAML Front Matter, Jekyll will generate `_site/foo/my-post/index.html`.
 
 **Note:** If you plan on enabling breadcrumb links --- including category names in permalinks is a big part of how those are created.
 {: .notice--warning}
@@ -419,11 +419,11 @@ If [using pagination](https://github.com/jekyll/jekyll-paginate) on the homepage
 paginate: 5
 ```
 
-You'll also need to include some modified Liquid to properly use the paginator, which you can find in the **Layouts** section under [Home Page]({{ base_path }}/docs/layouts/#home-page).
+You'll also need to include some Liquid and HTML to properly use the paginator, which you can find in the **Layouts** section under [Home Page]({{ base_path }}/docs/layouts/#home-page).
 
 ### Timezone
 
-Set the time zone for site generation. This sets the TZ environment variable, which Ruby uses to handle time and date creation and manipulation. Any entry from the [IANA Time Zone Database](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) is valid. The default is the local time zone, as set by your operating system.
+This sets the timezone environment variable, which Ruby uses to handle time and date creation and manipulation. Any entry from the [IANA Time Zone Database](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) is valid. The default is the local time zone, as set by your operating system.
 
 ```yaml
 timezone: America/New_York
@@ -447,11 +447,11 @@ When hosting with GitHub Pages a small [set of gems](https://pages.github.com/ve
 [jekyll-feed]: https://github.com/jekyll/jekyll-feed
 [jemoji]: https://github.com/jekyll/jemoji
 
-If you're hosting elsewhere then you don't really have to worry about that and are free to include whatever [Jekyll plugins](https://jekyllrb.com/docs/plugins/) you desire.
+If you're hosting elsewhere then you don't really have to worry about what is whitelisted as you are free to include whatever [Jekyll plugins](https://jekyllrb.com/docs/plugins/) you desire.
 
 ## Archive Settings
 
-Minimal Mistakes ships with support for taxonomy (category and tag) pages. GitHub Pages hosted sites get strip down Liquid only approach while those hosting elsewhere can use plugins like [**jekyll-archives**][jekyll-archives] to generate these pages automatically.
+The theme ships with support for taxonomy (category and tag) pages. GitHub Pages hosted sites need to use a *Liquid only* approach while those hosted elsewhere can use plugins like [**jekyll-archives**][jekyll-archives] to generate these pages automatically.
 
 [jekyll-archives]: https://github.com/jekyll/jekyll-archives
 
@@ -468,7 +468,7 @@ tags:
 
 Which would create category and tag links in the breadcrumbs and page meta like: `/categories/#foo` and `/tags/#foo`.
 
-**Note:** for these links to resolve category and tag index pages need to exist at [`/categories/index.html`]({{ site.gh_repo }}/blob/gh-pages/_pages/category-archive.html) and [`/tags/index.html`]({{ site.gh_repo }}/blob/gh-pages/_pages/tag-archive.html). Examples with the necessary Liquid code can be taken from the demo site.
+**Note:** for these links to resolve properly, category and tag index pages need to exist at [`/categories/index.html`]({{ site.gh_repo }}/blob/gh-pages/_pages/category-archive.html) and [`/tags/index.html`]({{ site.gh_repo }}/blob/gh-pages/_pages/tag-archive.html). The necessary Liquid code to build these pages can be taken from the demo site.
 {: .notice--warning}
 
 If you have the luxury of using Jekyll Plugins then [**jekyll-archives**][jekyll-archives] will make your life much easier as category and tag pages are created for you.
@@ -501,9 +501,9 @@ jekyll-archives:
 
 If you care at all about performance (and really who doesn't) compressing the HTML files generated by Jekyll is a good thing to do.
 
-Now if you're hosting with GitHub Pages there aren't many options afforded to you unless commit compiled files to your repo instead. Thankfully there is some Liquid wizardry you can use to strip whitespace and comments.
+If you're hosting with GitHub Pages there aren't many options afforded to you for optimizing the HTML Jekyll generates. Thankfully there is some Liquid wizardry you can use to strip whitespace and comments to reduce file size.
 
-There's a variety of configurations and cavets to using the `compress` layout, so be sure to read through the [documentation](http://jch.penibelst.de/) if you decide to make changes to anything, but here's the settings I've found work well:
+There's a variety of configurations and cavets to using the `compress` layout, so be sure to read through the [documentation](http://jch.penibelst.de/) if you decide to make change the defaults set in the theme's `_config.yml`.
 
 ```yaml
 compress_html:

_docs/06-navigation.md

@@ -49,7 +49,7 @@ Which will give you a responsive masthead similar to this:
 
 ## Breadcrumbs (Beta)
 
-Enable breadcrumb links to help visitors better navigate deeply structure sites. Because of the fragile method of implementing them they don't always produce accurate links reliably. For best results:
+Enable breadcrumb links to help visitors better navigate deep sites. Because of the fragile method of implementing them they don't always produce accurate links reliably. For best results:
 
 1. Use a category based permalink structure e.g. `permalink: /:categories/:title/`
 2. Manually create pages for each category or use a plugin like [jekyll-archives](https://github.com/jekyll/jekyll-archives) to auto-generate them. If these pages don't exist breadcrumb links to them will be broken.

_docs/07-ui-text.md

@@ -10,10 +10,10 @@ modified: 2016-04-13T15:54:02-04:00
 
 {% include base_path %}
 
-Text found various UI elements, `_layouts`, and `_includes` have all been grouped together as a set of translation keys. This is by no means a full-on i18n solution, but it does help make customizing things a bit easier.
+Text for various UI elements, `_layouts`, and `_includes` have all been grouped together as a set of translation keys. This is by no means a full-on i18n solution, but it does help make customizing things a bit easier.
 
-Currently all of the keys in `_data/ui-text.yml` are English only. If you're are interested in localizing for other languages feel free to submit pull-requests and I will be happy to look the over and merge in.
+Currently all of the keys in `_data/ui-text.yml` are English only. If you're are interested in localizing them into other languages feel free to submit a pull request and I will be happy to look it over
 
-Many of the label based keys like `meta_label`, `categories_label`, `tags_label`, `share_on_label`, `follow_label`, and more can be left blank if you'd like to omit them. It really depends on you and if you want an even more minimal look to your site.
+Many of the label based keys like `meta_label`, `categories_label`, `tags_label`, `share_on_label`, and `follow_label` can be left blank if you'd like to omit them from view. It really depends on you and if you want an even more minimal look to your site.
 
 ![UI text labels]({{ base_path }}/images/mm-ui-text-labels.jpg)

_docs/08-authors.md

@@ -12,9 +12,9 @@ modified: 2016-04-13T15:54:02-04:00
 
 Sites that may have content authored from various individuals can be accommodated by using [data files](https://jekyllrb.com/docs/datafiles/).
 
-To attribute an author to a post or page that is different from the site author specified in `_config.yml`:
+To assign an author to a post or page that is different from the site author specified in `_config.yml`:
 
-**Step 1.** Create `_data/authors.yml` and add authors using the following format. Anything variables found under `author` in `_config.yml` can be used (e.g. `name`, `avatar`, `uri`, social media profiles, etc.).
+**Step 1.** Create `_data/authors.yml` and add authors using the following format. Any variables found under `author:` in `_config.yml` can be used (e.g. `name`, `avatar`, `uri`, social media profiles, etc.).
 
 ```yaml
 # /_data/authors.yml

_docs/09-layouts.md

@@ -122,7 +122,7 @@ To produce something like this:
   <figcaption>Grid view example.</figcaption>
 </figure>
 
-**Note:** More information on using this `_include` can be found under [**Helpers and Shortcodes**]({{ base_path }}/docs/helpers-and-shortcodes/).
+**Note:** More information on using this `_include` can be found under [**Helpers**]({{ base_path }}/docs/helpers/).
 {: .notice--info}
 
 ### Taxonomy Archive
@@ -186,7 +186,7 @@ Feature blocks can be assigned and aligned to the `left`, `right`, or `center` w
 
 To add some visual punch to a post or page, a large full-width header image can be included.
 
-**Note:** Be sure to resize your header images. `~1280px` is a good medium if you aren't [responsively serving up images](http://alistapart.com/article/responsive-images-in-practice). Through the magic of CSS they will scale up or down to fill the container. If you go with something too small it will look like garbage when upscaled, and something too large will hurt performance.
+**Note:** Be sure to resize your header images. `~1280px` is a good width if you aren't [responsively serving up images](http://alistapart.com/article/responsive-images-in-practice). Through the magic of CSS they will scale up or down to fill the container. If you go with something too small it will look like garbage when upscaled, and something too large will hurt performance.
 {: .notice--warning}
 
 ![single layout header image example]({{ base_path }}/images/mm-single-header-example.jpg)
@@ -238,7 +238,7 @@ header:
   cta_url: "https://unsplash.com"
 ```
 
-You should get an header image overlaid with text and a call to action button.
+You'd get a header image overlaid with text and a call to action button like this:
 
 ![single layout header overlay example]({{ base_path }}/images/mm-single-header-overlay-example.jpg)
 
@@ -256,7 +256,7 @@ header:
 
 ## Sidebars
 
-The space to the left of a page's main content is blank by default, but has the option to show an author profile (name, short biography, social media links), custom content, or both.
+The space to the left of a page's main content is blank by default, but has the ability to show an author profile (name, short biography, social media links), custom content, or both.
 
 ### Author Profile
 

_docs/11-pages.md

@@ -30,9 +30,9 @@ Examples:
 
 | filename            | permalink              |
 | --------            | ---------              |
-| `_pages/about.md`   | `permalink: /about/`   |
+| _pages/about.md     | `permalink: /about/`   |
-| `_pages/home.md`    | `permalink: /`         |
+| _pages/home.md      | `permalink: /`         |
-| `_pages/contact.md` | `permalink: /contact/` |
+| _pages/contact.md   | `permalink: /contact/` |
 
 **Recommended Front Matter Defaults:**
 

_docs/12-collections.md

@@ -12,14 +12,14 @@ modified: 2016-04-13T15:54:02-04:00
 
 Collections like posts and pages work as you'd expect. If you're new to them be sure to read [Jekyll's documentation](https://jekyllrb.com/docs/collections/).
 
-Minimal Mistakes has been built with collections in mind and you will find [several examples]({{ base_path }}/collection-archive/) on the demo site ([portfolio]({{ base_path }}/portfolio/), [recipes]({{ base_path }}/recipes/), pets). 
+The theme has been built with collections in mind and you will find [several examples]({{ base_path }}/collection-archive/) on the demo site ([portfolio]({{ base_path }}/portfolio/), [recipes]({{ base_path }}/recipes/), pets). 
 
-**Collections in the Wild:** This set of documentation is also [built as a collection]({{ site.gh_repo }}/gh-pages/_docs/) if you're looking for a fully fleshed out example with custom sidebar navigation, next/previous pagination, and more.
+**Collections in the Wild:** This set of documentation is also [built as a collection]({{ site.gh_repo }}/gh-pages/_docs/) if you're looking for a fully fleshed out example to inspect.
 {: .notice--info}
 
 ---
 
-A popular use case for collections is to build a portfolio section as part of a personal site. Let's quickly walk through the steps to do that.
+A popular use case for collections is to build a portfolio section as part of one's personal site. Let's quickly walk through the steps to do that.
 
 **Step 1:** Configure the portfolio collection by adding the following to `_config.yml`.
 

_docs/13-helpers.md

@@ -117,7 +117,7 @@ To add a feature row containing three content blocks with text and image, add th
 | ----           | -----------  | ----------- | ------- |
 | **image_path** | **Required** | For images placed in the `/images/` directory just add the filename and extension. Use absolute URLS for those hosted externally. | |
 | **alt**        | Optional     | Alternate text for image. | |
-| **title**      | Optional     | Content block title | |
+| **title**      | Optional     | Content block title. | |
 | **excerpt**    | Optional     | Content block excerpt text. Markdown is allowed. | |
 | **url**        | Optional     | URL that the button should link to. | |
 | **btn_label**  | Optional     | Button text label. | `more_label` in UI Text data file. |

_docs/14-utility-classes.md

@@ -11,9 +11,9 @@ modified: 2016-04-13T15:54:02-04:00
 {% include base_path %}
 {% include toc icon="gears" title="Utility Classes" %}
 
-Using the Kramdown Markdown rendered with Jekyll allows you to add [block](http://kramdown.gettalong.org/quickref.html#block-attributes) and [inline attributes](http://kramdown.gettalong.org/quickref.html#inline-attributes). This is nice if you want to add styling to text and image, and still write in Markdown. As of v3 Kramdown is also the default for `jekyll new` sites and those hosted on GitHub Pages.
+Using the Kramdown Markdown renderer with Jekyll allows you to add [block](http://kramdown.gettalong.org/quickref.html#block-attributes) and [inline attributes](http://kramdown.gettalong.org/quickref.html#inline-attributes). This is nice if you want to add custom styling to text and image, and still write in Markdown.
 
-**Not Using Kramdown?** That's OK. The following classes can still available when used with standard HTML.
+**Jekyll 3:** Kramdown is the default for `jekyll new` sites and those hosted on GitHub Pages. Not using Kramdonw? That's OK. The following classes are still available when used with standard HTML.
 {: .notice--warning}
 
 ## Text Alignment

_docs/15-stylesheets.md

@@ -45,22 +45,22 @@ minimal mistakes
 
 ## Customizing
 
-The following settings in `/assets/_scss/_variables.scss` can modify the following aspects of the theme:
+The settings in `/assets/_scss/_variables.scss` can modify the following aspects of the theme:
 
 ### Paragraph Indention 
 
-To mimic the look of type set in a printed book or manuscript you may want to enable paragraph indention. When `$paragraph-indent` is set to `true` the margin below each paragraph is remove, and indents added to each sibling.
+To mimic the look of type set in a printed book or manuscript you may want to enable paragraph indention. When `$paragraph-indent` is set to `true` indents are added to each sibling and the margin below each paragraph is removed.
 
 <figure>
   <img src="{{ base_path }}/images/mm-paragraph-indent-example.jpg" alt="indented paragraph example">
   <figcaption>Example of indented paragraphs.</figcaption>
 </figure>
 
-The size of the indent can also be customized by changing `$indent-var: 1.3em;`.
+The size of the indent can also be customized by changing the value of `$indent-var`.
 
 ### Font Stacks
 
-By default the theme uses [system fonts](https://medium.com/designing-medium/system-shock-6b1dc6d6596f#.rb81vgn7i) for all of the font stacks (serif, sans-serif, and monospace). This is done in part to provide a clean base for you to build off of and to improve performance since we aren't loading any custom webfonts[^font-awesome].
+By default the theme uses [system fonts](https://medium.com/designing-medium/system-shock-6b1dc6d6596f#.rb81vgn7i) for all of the font stacks (serif, sans-serif, and monospace). This is done in part to provide a clean base for you to build off of and to improve performance since we aren't loading any custom webfonts[^font-awesome] by default.
 
 ```scss
 /* system typefaces */
@@ -78,7 +78,7 @@ Sans-serif fonts have been used for most of the type, with serifs reserved for c
 
 ### Type Scale
 
-Wherever possible type scale variables have been used instead of writing out fixed sizes. This has the added benefit of easily updating later on by editing `_variables.scss`. 
+Wherever possible type scale variables have been used instead of writing out fixed sizes. This makes updating much easier by changing values in one file, `_variables.scss`. 
 
 Example:
 
@@ -111,7 +111,7 @@ Change the mood of your site by altering a few color variables. `$body-color`, `
 
 Probably won't need to touch these, but they're there if you need to. Width variables are used with the [`@include breakpoint()`](http://breakpoint-sass.com/) mixin to adapt the design of certain elements.
 
-And `$susy` is used for setting the grid the theme uses. Uncommenting the lines under `debug` can be useful if you want to show the columns if tweaking the layout.
+And `$susy` is used for setting [the grid](http://susy.oddbird.net/) the theme uses. Uncommenting the lines under `debug` can be useful if you want to show the columns when adjusting the layout.
 
 <figure>
   <img src="{{ base_path }}/images/mm-susy-grid-overlay.jpg" alt="Susy grid overlay for debugging">
@@ -120,11 +120,11 @@ And `$susy` is used for setting the grid the theme uses. Uncommenting the lines
 
 ---
 
-Minimal Mistakes does not leverage Jekyll's built-in support for preprocessing Sass files. Why is that you ask? [**Autoprefixer**](https://github.com/postcss/autoprefixer)! As part of a build step the stylesheet is post processed with Autoprefixer to add vendor prefixes --- something not currently possible without a plugin[^jekyll-assets].
+The theme does not leverage Jekyll's [built-in support for preprocessing Sass](https://jekyllrb.com/docs/assets/#sassscss) files. Why is that you ask? [**Autoprefixer**](https://github.com/postcss/autoprefixer)! As part of a build step the stylesheet is post processed with Autoprefixer to add vendor prefixes --- something not currently possible without a plugin[^jekyll-assets].
 
 [^jekyll-assets]: A better solution would be to use the fantastic [jekyll-assets](https://github.com/jekyll/jekyll-assets) plugin to manage your assets if you aren't hosting with GitHub Pages. Autoprefixer support is built-in :smile:.
 
-If you plan on making any changes to the `.scss` partials you will need build the stylesheet outside of your normal workflow.
+If you plan on making any changes to the `.scss` partials you will need to rebuild the stylesheet outside of the normal Jekyll workflow.
 
 **Sass/SCSS files:** You can of course modify the structure of the CSS files to have Jekyll natively process `main.scss` for you. Just be sure to update the partials to include any vendor prefixes or else things may look off in older browsers.
 {: .notice--info}
@@ -142,7 +142,7 @@ To get started:
 **Note:** If you upgraded from a previous version of the theme be sure you copied over [`package.json`]({{ site.gh_repo }}/master/package.json) prior to running `npm install`.
 {: .notice--warning}
 
-If all goes well running `npm build:css` should process the SCSS files into `main.css`, which should then pipe through Autoprefixer.
+If all goes well, running `npm build:css` will process all SCSS files into `main.css`, which should then pipe through Autoprefixer.
 
 ```
 Rendering Complete, saving .css file...

_docs/16-javascript.md

@@ -50,4 +50,4 @@ To get started:
 **Note:** If you upgraded from a previous version of the theme be sure you copied over [`package.json`]({{ site.gh_repo }}/master/package.json) prior to running `npm install`.
 {: .notice--warning}
 
-If all goes well running `npm build:js` should compress and concatenate `_main.js` and all plugin scripts into `main.min.js`.
+If all goes well, running `npm build:js` will compress/concatenate `_main.js` and all plugin scripts into `main.min.js`.

_docs/18-contributing.md

@@ -8,8 +8,8 @@ sidebar:
 modified: 2016-04-13T15:54:02-04:00
 ---
 
-Having trouble working with the theme? Found a typo in the documentation? Interested in adding a feature or [fixing a bug]({{ site.gh_repo }}/issues)? Then by all means [submit an issue]({{ site.gh_repo }}/issues/new) or [pull request]({{ site.gh_repo }}/compare). If this is your first pull request, it may help to read up on the [GitHub Flow](https://guides.github.com/introduction/flow/).
+Having trouble working with the theme? Found a typo in the documentation? Interested in adding a feature or [fixing a bug]({{ site.gh_repo }}/issues)? Then by all means [submit an issue]({{ site.gh_repo }}/issues/new) or [pull request]({{ site.gh_repo }}/compare). If this is your first pull request, it may be helpful to read up on the [GitHub Flow](https://guides.github.com/introduction/flow/) first.
 
-As the theme's name implies I'd like to keep it as minimal as possible. It has been designed as a base for you to build off of.
+As the theme's name implies strives to keep things as minimal as possible. It has been designed as a base for you to build off of.
 
 Please keep this in mind when requesting features and/or submitting pull requests. If it's not something that most people will use, I probably won't consider it. When in doubt ask :smile:.