Update theme documentation

README.md

@@ -1,4 +1,4 @@
-# [Minimal Mistakes Jekyll Theme](https://mmistakes.github.io/minimal-mistakes/)
+# [Minimal Mistakes Jekyll theme](https://mmistakes.github.io/minimal-mistakes/)
 
 [![LICENSE](https://img.shields.io/badge/license-MIT-lightgrey.svg)](https://raw.githubusercontent.com/mmistakes/minimal-mistakes/master/LICENSE)
 [![Jekyll](https://img.shields.io/badge/jekyll-%3E%3D%203.6-blue.svg)](https://jekyllrb.com/)
@@ -22,7 +22,7 @@ Minimal Mistakes is a flexible two-column Jekyll theme, perfect for building per
 
 ![layout examples](screenshot-layouts.png)
 
-## Notable Features
+## Notable features
 
 - Bundled as a "theme gem" for easier installation/upgrading.
 - Compatible with GitHub Pages.
@@ -35,7 +35,7 @@ Minimal Mistakes is a flexible two-column Jekyll theme, perfect for building per
 - [Google Analytics](https://www.google.com/analytics/) support.
 - UI localized text in English (default), Brazilian Portuguese (Português brasileiro), Chinese, Danish, Dutch, French (Français), German (Deutsch), Greek, Hindi, Hungarian, Indonesian, Italian (Italiano), Japanese, Korean, Nepali (Nepalese), Polish, Punjabi (ਪੰਜਾਬੀ), Romanian, Russian, Slovak, Spanish (Español), Swedish, Turkish (Türkçe), and Vietnamese.
 
-## Skins (Color Variations)
+## Skins (color variations)
 
 This theme comes in nine different skins (including the default one).
 
@@ -51,7 +51,7 @@ This theme comes in nine different skins (including the default one).
 | --- | --- | --- |
 | ![aqua skin](https://mmistakes.github.io/minimal-mistakes/assets/images/aqua-skin-archive.png) | ![neon skin](https://mmistakes.github.io/minimal-mistakes/assets/images/neon-skin-archive.png) | ![plum skin](https://mmistakes.github.io/minimal-mistakes/assets/images/plum-skin-archive.png) |
 
-## Demo Pages
+## Demo pages
 
 | Name                                        | Description                                           |
 | ------------------------------------------- | ----------------------------------------------------- |
@@ -76,11 +76,15 @@ Additional sample posts are available under [posts archive][year-archive] on the
 
 ## Installation
 
-There are three ways to install the theme: as a Ruby gem (for self-hosted sites), as a Ruby gem + jekyll-remote-theme plugin (GitHub Pages hosted sites), or forking/directly copying all of the theme files into your project.
+There are three ways to install: as a [gem-based theme](https://jekyllrb.com/docs/themes/#understanding-gem-based-themes), as a [remote theme](https://blog.github.com/2017-11-29-use-any-theme-with-github-pages/) (GitHub Pages compatible), or forking/directly copying all of the theme files into your project.
 
-### Ruby Gem Method
+### Gem-based method
 
-1. Install the theme as a Ruby Gem by adding it to your `Gemfile` like so:
+With Gem-based themes, directories such as the `assets`, `_layouts`, `_includes`, and `_sass` are stored in the theme’s gem, hidden from your immediate view. Yet all of the necessary directories will be read and processed during Jekyll’s build process.
+
+This allows for easier installation and updating as you don't have to manage any of the theme files. To install:
+
+1. Add the following to your `Gemfile`:
 
    ```ruby
    gem "minimal-mistakes-jekyll"
@@ -100,7 +104,11 @@ There are three ways to install the theme: as a Ruby gem (for self-hosted sites)
 
 To update the theme run `bundle update`.
 
-### GitHub Pages Method
+### Remote theme method
+
+Remote themes are similar to Gem-based themes, but do not require `Gemfile` changes or whitelisting making them ideal for sites hosted with GitHub Pages.
+
+To install:
 
 1. Create/replace the contents of your `Gemfile` with the following:
 
@@ -110,13 +118,15 @@ To update the theme run `bundle update`.
    gem "github-pages", group: :jekyll_plugins
    ```
 
-2. Fetch and update bundled gems by running the following [Bundler](http://bundler.io/) command:
+2. Add `jekyll-include-cache` to the `plugins` array of your `_config.yml`.
+
+3. Fetch and update bundled gems by running the following [Bundler](http://bundler.io/) command:
 
    ```bash
    bundle
    ```
 
-3. Add `remote_theme: "mmistakes/minimal-mistakes"` to your `_config.yml` file. Remove any other `theme:` or `remote_theme:` entry.
+4. Add `remote_theme: "mmistakes/minimal-mistakes@4.13.0"` to your `_config.yml` file. Remove any other `theme:` or `remote_theme:` entry.
 
 ## Usage
 

docs/_docs/01-quick-start-guide.md

@@ -2,15 +2,15 @@
 title: "Quick-Start Guide"
 permalink: /docs/quick-start-guide/
 excerpt: "How to quickly install and setup Minimal Mistakes for use with GitHub Pages."
-last_modified_at: 2018-11-18T12:59:42-05:00
+last_modified_at: 2018-11-25T19:29:40-05:00
 redirect_from:
   - /theme-setup/
 toc: true
 ---
 
-Minimal Mistakes has been developed as a [Jekyll theme gem](http://jekyllrb.com/docs/themes/) for easier use. It is also 100% compatible with GitHub Pages --- just with slightly different installation process.
+Minimal Mistakes has been developed as a [Gem-based theme](http://jekyllrb.com/docs/themes/) for easier use. It is also 100% compatible with GitHub Pages when used as a remote theme.
 
-## Installing the Theme
+## Installing the theme
 
 If you're running Jekyll v3.5+ and self-hosting you can quickly install the theme as a Ruby gem.
 
@@ -22,53 +22,57 @@ If you're running Jekyll v3.5+ and self-hosting you can quickly install the them
 **Note:** The theme uses the [jekyll-include-cache](https://github.com/benbalter/jekyll-include-cache) plugin which will need to be installed in your `Gemfile` and added to the `plugins` array of `_config.yml`. Otherwise you'll throw `Unknown tag 'include_cached'` errors at build.
 {: .notice--warning}
 
-### Ruby Gem Method
+### Gem-based method
 
-Add this line to your Jekyll site's `Gemfile`:
+With Gem-based themes, directories such as the `assets`, `_layouts`, `_includes`, and `_sass` are stored in the theme’s gem, hidden from your immediate view. This allows for easier installation and updating as you don't have to manage any of the theme files. 
 
-```ruby
+To install as a Gem-based theme:
-gem "minimal-mistakes-jekyll"
-```
 
-Add these lines to your Jekyll site's `_config.yml` file:
+1. Add the following to your `Gemfile`:
 
-```yaml
+   ```ruby
-theme: minimal-mistakes-jekyll
+   gem "minimal-mistakes-jekyll"
+   ```
 
-plugins:
+2. Fetch and update bundled gems by running the following [Bundler](http://bundler.io/) command:
-  - jekyll-include-cache
-```
 
-Then run Bundler to install the theme gem and dependencies:
+   ```bash
+   bundle
+   ```
 
-```bash
+3. Set the `theme` in your project's Jekyll `_config.yml` file:
-bundle install
-```
 
-### GitHub Pages Method
+   ```yaml
+   theme: minimal-mistakes-jekyll
+   ```
 
-GitHub Pages has added [full support](https://github.com/blog/2464-use-any-theme-with-github-pages) for any GitHub-hosted theme.
+To update the theme run `bundle update`.
 
-Replace `gem "jekyll"` with:		
+### Remote theme method
 
-```ruby		
+Remote themes are similar to Gem-based themes, but do not require `Gemfile` changes or whitelisting making them ideal for sites hosted with GitHub Pages.
-gem "github-pages", group: :jekyll_plugins			
-```
 
-Add `gem "jekyll-include-cache"`
+To install as a remote theme:
 
-Run `bundle update` and verify that all gems install properly.
+1. Create/replace the contents of your `Gemfile` with the following:
 
-Add `remote_theme: "mmistakes/minimal-mistakes"` to your `_config.yml` file. Remove any other `theme:` or `remote_theme:` entry.
+   ```ruby
+   source "https://rubygems.org"
 
-Add `jekyll-include-cache` to `plugins` like so:
+   gem "github-pages", group: :jekyll_plugins
+   ```
 
-```yaml
+2. Add `jekyll-include-cache` to the `plugins` array of your `_config.yml`.
-plugins:
-  - jekyll-include-cache
-```
 
-You may also optionally specify a branch, [tag](https://github.com/mmistakes/minimal-mistakes/tags), or commit to use by appending an @ and the Git ref (e.g., `mmistakes/minimal-mistakes@4.9.0` or `mmistakes/minimal-mistakes@bbf3cbc5fd64a3e1885f3f99eb90ba92af84063d`). If you don't specify a Git ref, the master branch will be used.
+3. Fetch and update bundled gems by running the following [Bundler](http://bundler.io/) command:
+
+   ```bash
+   bundle
+   ```
+
+4. Add `remote_theme: "mmistakes/minimal-mistakes@4.13.0"` to your `_config.yml` file. Remove any other `theme:` or `remote_theme:` entry.
+
+You may also optionally specify a branch, [tag](https://github.com/mmistakes/minimal-mistakes/tags), or commit to use by appending an @ and the Git ref (e.g., `mmistakes/minimal-mistakes@4.9.0` or `mmistakes/minimal-mistakes@bbf3cbc5fd64a3e1885f3f99eb90ba92af84063d`). This is useful when rolling back to older versions of the theme. If you don't specify a Git ref, the latest on `master` will be used.
 
 ---
 

docs/_docs/03-installation.md

@@ -2,19 +2,19 @@
 title: "Installation"
 permalink: /docs/installation/
 excerpt: "Instructions for installing the theme for new and existing Jekyll based sites."
-last_modified_at: 2018-10-04T20:16:07-04:00
+last_modified_at: 2018-11-25T19:32:34-05:00
 toc: true
 ---
 
-## Install the Theme
+## Install the theme
 
-**1.** For a **new site**, install the `minimal-mistakes-jekyll` theme gem or fork the Minimal Mistakes repo on GitHub following the steps outlined in the [*Quick-Start Guide*]({{ "/docs/quick-start-guide/" | relative_url }}).
+**1.** For a **new site**, install the `minimal-mistakes-jekyll` gem, remote theme, or fork the Minimal Mistakes repo on GitHub following the steps outlined in the [*Quick-Start Guide*]({{ "/docs/quick-start-guide/" | relative_url }}).
 
 If you plan to host with GitHub Pages be sure to properly setup [**jekyll-remote-theme**](https://github.com/benbalter/jekyll-remote-theme) as it is required for the theme to work properly. 
 
 **2.** For an **existing site** follow the steps outlined in the [*Quick-Start Guide*]({{ "/docs/quick-start-guide/" | relative_url }}). Then work through the guidelines below for migration and setup.
 
-**3.** And for those who'd like to make substantial edits to the theme, it can be downloaded as a ZIP file to customize.
+**3.** For those who'd like to make substantial edits to the theme, download as a ZIP file to customize.
 
 [<i class="fas fa-download"></i> Download Minimal Mistakes Theme](https://github.com/mmistakes/minimal-mistakes/archive/master.zip){: .btn .btn--success}
 
@@ -24,7 +24,7 @@ If you plan to host with GitHub Pages be sure to properly setup [**jekyll-remote
 **Note:** The theme uses the [jekyll-include-cache](https://github.com/benbalter/jekyll-include-cache) plugin which will need to be installed in your `Gemfile` and added to the `plugins` array of `_config.yml`. Otherwise you'll throw `Unknown tag 'include_cached'` errors at build.
 {: .notice--warning}
 
-## Theme Migration
+## Theme migration
 
 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.
 
@@ -51,7 +51,7 @@ defaults:
 **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
+## Install dependencies
 
 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.
 

docs/_docs/04-upgrading.md

@@ -2,7 +2,7 @@
 title: "Upgrading"
 permalink: /docs/upgrading/
 excerpt: "Instructions and suggestions for upgrading the theme."
-last_modified_at: 2018-03-20T15:59:07-04:00
+last_modified_at: 2018-11-25T19:38:20-05:00
 toc: true
 ---
 
@@ -33,11 +33,11 @@ gem "minimal-mistakes-jekyll", :git => "https://github.com/mmistakes/minimal-mis
 
 For more information on [installing gems from git repositories](http://bundler.io/v1.16/guides/git.html) consult Bundler's documentation.
 
-## Remote Theme
+## Remote theme
 
-When setting `remote_theme: "mmistakes/minimal-mistakes"` in your `_config.yml` you may also optionally specify a branch, [tag](https://github.com/mmistakes/minimal-mistakes/tags), or commit to use by appending an @ and the Git ref.
+When setting `remote_theme: "mmistakes/minimal-mistakes@4.13.0"` in your `_config.yml` you may also optionally specify a branch, [tag](https://github.com/mmistakes/minimal-mistakes/tags), or commit to use by appending an @ and the Git ref.
 
-For example you can roll back to release 4.8.1 with `mmistakes/minimal-mistakes@4.8.1` or a specific commit with `mmistakes/minimal-mistakes@bbf3cbc5fd64a3e1885f3f99eb90ba92af84063d`).
+For example you can roll back to release 4.8.1 with `mmistakes/minimal-mistakes@4.8.1` or a specific commit with `mmistakes/minimal-mistakes@bbf3cbc5fd64a3e1885f3f99eb90ba92af84063d`). For a complete list of theme versions consult the [releases page](https://github.com/mmistakes/minimal-mistakes/releases).
 
 To update the theme on GitHub Pages you'll need to push up a commit to force a rebuild. An empty commit works well if you don't have anything to push at the moment:
 
@@ -57,7 +57,7 @@ To add it you can do the following:
 git remote add upstream https://github.com/{{ site.repository }}.git
 ```
 
-### Pull Down Updates
+### Pull down updates
 
 Now you can pull any commits made to theme's `master` branch with:
 
@@ -67,7 +67,7 @@ git pull upstream master
 
 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, staging the changes you wish to keep, and then commit them.
 
-## Update Files Manually
+## Update files manually
 
 Another way of dealing with updates is [downloading the theme](https://github.com/{{ site.repository }}/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](https://github.com/{{ site.repository }}/commits/master) to see what's changed since.
 

docs/_docs/05-configuration.md

@@ -2,7 +2,7 @@
 title: "Configuration"
 permalink: /docs/configuration/
 excerpt: "Settings for configuring and customizing the theme."
-last_modified_at: 2018-11-21T14:46:33-05:00
+last_modified_at: 2018-11-25T19:42:42-05:00
 toc: true
 ---
 
@@ -13,7 +13,7 @@ Settings that affect your entire site can be changed in [Jekyll's configuration
 
 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
+## Site settings
 
 ### Theme
 
@@ -46,8 +46,6 @@ minimal_mistakes_skin: "default" # "air", "aqua", "contrast", "dark", "dirt", "n
 
 #### Aqua skin: `aqua`
 
-{:.no_toc}
-
 <figure class="half">
   <a href="{{ site.baseurl }}/assets/images/aqua-skin-archive-large.png"><img src="{{ site.baseurl }}/assets/images/aqua-skin-archive.png"></a>
   <a href="{{ site.baseurl }}/assets/images/aqua-skin-post-large.png"><img src="{{ site.baseurl }}/assets/images/aqua-skin-post.png"></a>
@@ -56,8 +54,6 @@ minimal_mistakes_skin: "default" # "air", "aqua", "contrast", "dark", "dirt", "n
 
 #### Contrast skin: `contrast`
 
-{:.no_toc}
-
 <figure class="half">
   <a href="{{ site.baseurl }}/assets/images/contrast-skin-archive-large.png"><img src="{{ site.baseurl }}/assets/images/contrast-skin-archive.png"></a>
   <a href="{{ site.baseurl }}/assets/images/contrast-skin-post-large.png"><img src="{{ site.baseurl }}/assets/images/contrast-skin-post.png"></a>
@@ -66,8 +62,6 @@ minimal_mistakes_skin: "default" # "air", "aqua", "contrast", "dark", "dirt", "n
 
 #### Dark skin: `dark`
 
-{:.no_toc}
-
 <figure class="half">
   <a href="{{ site.baseurl }}/assets/images/dark-skin-archive-large.png"><img src="{{ site.baseurl }}/assets/images/dark-skin-archive.png"></a>
   <a href="{{ site.baseurl }}/assets/images/dark-skin-post-large.png"><img src="{{ site.baseurl }}/assets/images/dark-skin-post.png"></a>
@@ -76,8 +70,6 @@ minimal_mistakes_skin: "default" # "air", "aqua", "contrast", "dark", "dirt", "n
 
 #### Dirt skin: `dirt`
 
-{:.no_toc}
-
 <figure class="half">
   <a href="{{ site.baseurl }}/assets/images/dirt-skin-archive-large.png"><img src="{{ site.baseurl }}/assets/images/dirt-skin-archive.png"></a>
   <a href="{{ site.baseurl }}/assets/images/dirt-skin-post-large.png"><img src="{{ site.baseurl }}/assets/images/dirt-skin-post.png"></a>
@@ -96,8 +88,6 @@ minimal_mistakes_skin: "default" # "air", "aqua", "contrast", "dark", "dirt", "n
 
 #### Neon skin: `neon`
 
-{:.no_toc}
-
 <figure class="half">
   <a href="{{ site.baseurl }}/assets/images/neon-skin-archive-large.png"><img src="{{ site.baseurl }}/assets/images/neon-skin-archive.png"></a>
   <a href="{{ site.baseurl }}/assets/images/neon-skin-post-large.png"><img src="{{ site.baseurl }}/assets/images/neon-skin-post.png"></a>
@@ -106,8 +96,6 @@ minimal_mistakes_skin: "default" # "air", "aqua", "contrast", "dark", "dirt", "n
 
 #### Neon skin: `plum`
 
-{:.no_toc}
-
 <figure class="half">
   <a href="{{ site.baseurl }}/assets/images/plum-skin-archive-large.png"><img src="{{ site.baseurl }}/assets/images/plum-skin-archive.png"></a>
   <a href="{{ site.baseurl }}/assets/images/plum-skin-post-large.png"><img src="{{ site.baseurl }}/assets/images/plum-skin-post.png"></a>
@@ -116,15 +104,13 @@ minimal_mistakes_skin: "default" # "air", "aqua", "contrast", "dark", "dirt", "n
 
 #### Sunrise skin: `sunrise`
 
-{:.no_toc}
-
 <figure class="half">
   <a href="{{ site.baseurl }}/assets/images/sunrise-skin-archive-large.png"><img src="{{ site.baseurl }}/assets/images/sunrise-skin-archive.png"></a>
   <a href="{{ site.baseurl }}/assets/images/sunrise-skin-post-large.png"><img src="{{ site.baseurl }}/assets/images/sunrise-skin-post.png"></a>
   <figcaption>Oranges and red.</figcaption>
 </figure>
 
-### Site Locale
+### Site locale
 
 `site.locale` is used to declare the primary language for each web page within the site.
 
@@ -135,7 +121,7 @@ Properly setting the locale is important for associating localized text found in
 **Note:** The theme comes with localized text in English (`en`, `en-US`, `en-GB`). If you change `locale` in `_config.yml` to something else, most of the UI text will go blank. Be sure to add the corresponding locale key and translated text to `_data/ui-text.yml` to avoid this.
 {: .notice--warning}
 
-### Site Title
+### Site title
 
 The name of your site. Is used throughout the theme in places like the site masthead and `<title>` tags.
 
@@ -148,7 +134,7 @@ _Example:_ `title_separator: "|"` would produce page titles like `Sample Page |
 **Note:** Long site titles have been known to break the masthead layout. Avoid adding a long "tagline" to the title prevent this from happening eg. `My Awesome Site is the Best Because I Say So".
 {: .notice--warning}
 
-### Site Name
+### Site name
 
 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.
 
@@ -157,7 +143,7 @@ _Example:_ `name: "Michael Rose"`.
 **ProTip:** If you want to get crafty with your YAML you can use [anchors](http://www.yaml.org/spec/1.2/spec.html#id2785586) to reuse values. For example `foo: &var "My String"` allows you to reuse `"My String"` elsewhere in `_config.yml` like so... `bar: *var`. You'll see a few examples of this in the provided Jekyll config.
 {: .notice--info}
 
-### Site Description
+### Site description
 
 Fairly obvious. `site.description` describes the site. Used predominantly in meta descriptions for improving SEO.
 
@@ -172,7 +158,7 @@ GitHub Pages now [forces `https://` for new sites](https://help.github.com/artic
 **Note:** Jekyll 3.3 overrides this value with `url: http://localhost:4000` when running `jekyll serve` locally in development. If you want to avoid this behavior set `JEKYLL_ENV=production` to [force the environment](http://jekyllrb.com/docs/configuration/#specifying-a-jekyll-environment-at-build-time) to production.
 {: .notice--warning}
 
-### Site Base URL
+### 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.
 
@@ -183,7 +169,7 @@ For more information on how to properly use `site.url` and `site.baseurl` as int
 **Note:** When using `baseurl` remember to include it as part of your path when testing your site locally. Values of `url:` and `baseurl: "/blog"` would make your local site visible at `http://localhost:4000/blog` and not `http://localhost:4000`.
 {: .notice--warning}
 
-### Site Repository
+### Site repository
 
 Add your repository name with organization to your site's configuration file, `_config.yml`.
 
@@ -202,7 +188,7 @@ If you don't set `repository` correctly you may see the following error when try
 
 For more information on how `site.github` data can be used with Jekyll check out [`github-metadata`'s documentation](https://github.com/jekyll/github-metadata).
 
-### Site Scripts
+### Site scripts
 
 Add scripts to the `<head>` or closing `</body>` elements by assigning paths to either `head_scripts` and/or `footer_scripts`.
 
@@ -217,7 +203,7 @@ head_scripts:
 Consult the [JavaScript documentation]({{ site.baseurl }}{% link _docs/17-javascript.md %}) for more information on working with theme scripts.
 {: .notice--info}
 
-### Site Default Teaser Image
+### Site default teaser image
 
 To assign a fallback teaser image used in the "**Related Posts**" module, place a graphic in the `/assets/images/` directory and add the filename to `_config.yml` like so:
 
@@ -237,7 +223,7 @@ header:
   <figcaption>Example of teaser images found in the related posts module.</figcaption>
 </figure>
 
-### Breadcrumb Navigation (Beta)
+### Breadcrumb navigation (beta)
 
 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:
 
@@ -252,7 +238,7 @@ breadcrumbs: true  # disabled by default
 
 Breadcrumb start link text and separator character can both be changed in the [UI Text data file]({{ "/docs/ui-text/" | relative_url }}).
 
-### Reading Time
+### 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 value --- which can be changed by adjusting `words_per_minute:` in `_config.yml`.
 
@@ -332,7 +318,7 @@ comments:
 **Note:** Do not include `http://` or `https://` when setting your Discourse `server`. The theme automatically prepends the URL `//`, following a scheme-less pattern.
 {: .notice--info}
 
-#### Facebook Comments
+#### Facebook comments
 
 To enable Facebook Comments choose how many comments you'd like visible per post and the color scheme of the widget.
 
@@ -345,7 +331,7 @@ comments:
     colorscheme: # "light" (default), "dark"
 ```
 
-#### utterances Comments
+#### utterances comments
 
 To use utterances you will need to [install the app](https://github.com/apps/utterances) to your GitHub repository by adding the following to `_config.yml`:
 
@@ -365,7 +351,7 @@ comments:
     theme: "github-light" # "github-dark"
 ```
 
-#### Static-Based Comments via Staticman
+#### Static-based comments via Staticman
 
 Transform user comments into `_data` files that live inside of your GitHub repository by enabling Staticman.
 
@@ -375,7 +361,7 @@ Transform user comments into `_data` files that live inside of your GitHub repos
 **Note:** Please note that as of September 2018, Staticman is reaching GitHub API limits due to its popularity, and it is recommended by its maintainer that users deploy their own instances for production (use `site.staticman.endpoint`).
 {: .notice--warning}
 
-##### Add Staticman as a Collaborator
+##### Add Staticman as a collaborator
 
 1. Allow Staticman push access to your GitHub repository by clicking on **Settings**, then the **Collaborators** tab and adding `staticmanapp` as a collaborator.
 2. To accept the pending invitation visit: `https://api.staticman.net/v2/connect/{your GitHub username}/{your repository name}`. Consult the Staticman "[Get Started](https://staticman.net/docs/index.html)" guide for more info.
@@ -453,7 +439,7 @@ staticman:
         format           : "iso8601" # "iso8601" (default), "timestamp-seconds", "timestamp-milliseconds"
 ```
 
-##### Comment Moderation
+##### Comment moderation
 
 By default comment moderation is enabled in `staticman.yml`. As new comments are submitted Staticman will send a pull request. Merging these in will approve the comment, close the issue, and automatically rebuild your site (if hosted on GitHub Pages).
 
@@ -464,7 +450,7 @@ To skip this moderation step simply set `moderation: false`.
 
 ![pull-request webhook]({{ "/assets/images/mm-staticman-pr-webhook.jpg" | relative_url }})
 
-##### reCAPTCHA Support (v2 only)
+##### reCAPTCHA support (v2 only)
 
 To enable Google's reCAPTCHA to aid in spam detection you'll need to:
 
@@ -478,11 +464,11 @@ reCaptcha:
   secret: # "PznnZGu3P6eTHRPLORniSq+J61YEf+A9zmColXDM5icqF49gbunH51B8+h+i2IvewpuxtA9TFoK68TuhUp/X3YKmmqhXasegHYabY50fqF9nJh9npWNhvITdkQHeaOqnFXUIwxfiEeUt49Yoa2waRR7a5LdRAP3SVM8hz0KIBT4="
 ```
 
-#### Other Comment Providers
+#### Other comment providers
 
 To use another provider not included with the theme set `provider: "custom"` then add their embed code to `_includes/comments-providers/custom.html`.
 
-### Custom Feed URL
+### Custom feed URL
 
 By default the theme links to `feed.xml` generated in the root of your site by the **jekyll-feed** plugin. To link to an externally hosted feed update `atom_feed` in `_config.yml` like so:
 
@@ -494,7 +480,7 @@ atom_feed:
 **Note:** By default the site feed is linked in two locations: inside the [`<head>` element](https://github.com/mmistakes/minimal-mistakes/blob/master/_includes/head.html) and at the bottom of every page in the [site footer](https://github.com/mmistakes/minimal-mistakes/blob/master/_includes/footer.html).
 {: .notice--info}
 
-### Site Search
+### Site search
 
 To enable site-wide search add `search: true` to your `_config.yml`.
 
@@ -584,7 +570,7 @@ Add a Google search box to your site.
 **Note:** If your site is new and hasn't been indexed by Google yet, search will be incomplete and won't provide accurate results.
 {: .notice--info}
 
-### SEO, Social Sharing, and Analytics Settings
+### SEO, social sharing, and analytics settings
 
 All optional, but a good idea to take the time setting up to improve SEO and links shared from the site.
 
@@ -645,7 +631,7 @@ yandex_site_verification: "2132801JL"
 
 To improve the appearance of links shared from your site to social networks like Twitter and Facebook be sure to configure the following.
 
-##### Site Twitter Username
+##### Site Twitter username
 
 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.
 
@@ -681,7 +667,7 @@ facebook:
 **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.
 {: .notice--info}
 
-##### Open Graph Default Image
+##### Open Graph default image
 
 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 your logo, icon, avatar or something else that is meaningful. Just make sure it is place in the `/assets/images/` folder, a minimum size of 120px by 120px, and less than 1MB in file size.
 
@@ -749,7 +735,7 @@ To use another provider not included with the theme set `provider: "custom"` the
 `JEKYLL_ENV=production` to [force the environment](http://jekyllrb.com/docs/configuration/#specifying-a-jekyll-environment-at-build-time) to production.
 {: .notice--info}
 
-## Site Author
+## Site author
 
 Used as the defaults for defining what appears in the author sidebar.
 
@@ -797,7 +783,7 @@ author:
 
 To customize the author sidebar, read the full [layout documentation]({{ "/docs/layouts/#author-profile" | relative_url }}).
 
-## Site Footer
+## Site footer
 
 Footer links can be added under the `footer.links` array.
 
@@ -826,11 +812,11 @@ footer:
 
 To change "Follow:" text that precedes footer links, edit the `follow_label` key in `_data/ui-text.yml`.
 
-## Reading Files
+## Reading files
 
 Nothing out of the ordinary here. `include` and `exclude` may be the only things you need to alter.
 
-## Conversion and Markdown Processing
+## 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. Change them if you need to.
 
@@ -940,7 +926,7 @@ If you're hosting elsewhere then you don't really have to worry about what is wh
 **Note:** The [jekyll-include-cache](https://github.com/benbalter/jekyll-include-cache) plugin needs to be installed in your `Gemfile` and added to the `plugins` array of `_config.yml`. Otherwise you'll throw `Unknown tag 'include_cached'` errors at build.
 {: .notice--warning}
 
-## Archive Settings
+## Archive settings
 
 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.
 
@@ -1001,7 +987,7 @@ jekyll-archives:
 **Note:** The `archive-taxonomy` layout used by jekyll-archives is provided with the theme and can be found in the `_layouts` folder.
 {: .notice--info}
 
-## HTML Compression
+## HTML compression
 
 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.
 

docs/_docs/07-navigation.md

@@ -6,6 +6,8 @@ last_modified_at: 2018-03-20T15:59:40-04:00
 toc: true
 ---
 
+Customize site navigational links through a Jekyll data file.
+
 ## Masthead
 
 The masthead links use a "priority plus" design pattern. Meaning, show as many navigation items that will fit horizontally with a toggle to reveal the rest.
@@ -39,7 +41,7 @@ Optionally, you can add a `description` key per title in the `main` key. This `d
 **ProTip:** Put the most important links first so they're always visible and not hidden behind the **menu toggle**.
 {: .notice--info}
 
-## Breadcrumbs (Beta)
+## Breadcrumbs (beta)
 
 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:
 
@@ -66,6 +68,6 @@ breadcrumb_home_label : "Start"
 breadcrumb_separator  : ">"
 ```
 
-## Custom Sidebar Navigation Menu
+## Custom sidebar navigation menu
 
 See the [**sidebars** documentation]({{ "/docs/layouts/#custom-sidebar-navigation-menu" | relative_url }}) for information on setting up a custom navigation menu.

docs/_docs/10-layouts.md

@@ -7,7 +7,7 @@ single_layout_gallery:
     alt: "single layout with header example"
   - image_path: /assets/images/mm-layout-single-meta.png
     alt: "single layout with comments and related posts"
-last_modified_at: 2018-11-13T09:29:44-05:00
+last_modified_at: 2018-11-25T19:45:55-05:00
 toc: true
 toc_label: "Included Layouts"
 toc_icon: "columns"
@@ -15,7 +15,7 @@ toc_icon: "columns"
 
 The bread and butter of any theme. Below you'll find the layouts included with Minimal Mistakes, what they look like and the type of content they've been built for.
 
-## Default Layout
+## Default layout
 
 The base layout all other layouts inherit from. There's not much to this layout apart from pulling in several `_includes`:
 
@@ -28,7 +28,7 @@ The base layout all other layouts inherit from. There's not much to this layout
 **Note:** You won't ever assign this layout directly to a post or page. Instead all other layouts will build off of it by setting `layout: default` in their YAML Front Matter.
 {: .notice--warning}
 
-### Layout Based and User-Defined Classes
+### Layout based and user-defined classes
 
 Class names corresponding to each layout are automatically added to the `<body>` element eg. `<body class="layout--single">`.
 
@@ -65,7 +65,7 @@ Outputs:
 <body class="layout--splash landing dark-theme">
 ```
 
-## Compress Layout
+## Compress layout
 
 A Jekyll layout that compresses HTML in pure Liquid. To enable add `layout: compress` to `_layouts/default.html`.
 
@@ -74,7 +74,7 @@ A Jekyll layout that compresses HTML in pure Liquid. To enable add `layout: comp
 
 * [Documentation](http://jch.penibelst.de/)
 
-## Single Layout
+## Single layout
 
 The layout you'll likely use the most --- sidebar and main content combo.
 
@@ -91,7 +91,7 @@ The layout you'll likely use the most --- sidebar and main content combo.
 
 Assign with `layout: single` , or better yet apply as a [Front Matter default]({{ "/docs/configuration/#front-matter-defaults" | relative_url }}) in `_config.yml`.
 
-### Wide Page
+### Wide page
 
 To expand the main content to the right, filling the space of what is normally occupied by the table of contents. Add the following to a post or page's YAML Front Matter:
 
@@ -102,7 +102,7 @@ classes: wide
 **Note:** If the page contains a table of contents, it will no longer appear to the right. Instead it will be forced into the main content container directly following the page's title.
 {: .notice--info}
 
-### Table of Contents
+### Table of contents
 
 Auto-generated table of contents list for your posts and pages can be enabled by adding `toc: true` to the YAML Front Matter.
 
@@ -124,7 +124,7 @@ toc_icon: "cog"
 ---
 ```
 
-## Archive Layout
+## Archive layout
 
 Essentially the same as `single` with markup adjustments and some modules removed.
 
@@ -159,7 +159,7 @@ Post and page excerpts are auto-generated by Jekyll which grabs the first paragr
 excerpt: "A unique line of text to describe this post that will display in an archive listing and meta description with SEO benefits."
 ```
 
-### Wide Page
+### Wide page
 
 To expand the main content to the right, filling the space of what is normally occupied by the table of contents. Add the following to a post or page's YAML Front Matter:
 
@@ -167,7 +167,7 @@ To expand the main content to the right, filling the space of what is normally o
 classes: wide
 ```
 
-### Grid View
+### Grid view
 
 Adding `type=grid` to the `archive-single` helper will display archive posts in a 4 column grid. For example to create an archive displaying all documents in the portfolio collection:
 
@@ -193,7 +193,7 @@ header:
 **Note:** More information on using this `_include` can be found under [**Helpers**]({{ "/docs/helpers/" | relative_url }}).
 {: .notice--info}
 
-## Taxonomy Archives
+## Taxonomy archives
 
 If you have the luxury of using Jekyll plugins, the creation of category and tag archives is greatly simplified. Simply enable support for the [`jekyll-archives`](https://github.com/jekyll/jekyll-archives) plugin with a few `_config.yml` settings as noted in the [**Configuration**]({{ "/docs/configuration/#archive-settings" | relative_url }}) section and you're good to go.
 
@@ -284,7 +284,7 @@ permalink: /tags/foo-bar/
 taxonomy: foo bar
 ```
 
-## Home Page Layout
+## Home page layout
 
 A derivative archive page layout to be used as a simple home page. It is built to show a paginated list of recent posts based off of the [pagination settings]({{ "/docs/configuration/#paginate" | relative_url }}) in `_config.yml`.
 
@@ -321,7 +321,7 @@ paginate_path: /blog/page:num
 **Note:** Jekyll can only paginate a single `index.html` file. If you'd like to paginate more pages (e.g. category indexes) you'll need the help of a custom plugin. For more pagination related settings check the [**Configuration**]({{ "/docs/configuration/#paginate" | relative_url }}) section.
 {: .notice--info}
 
-## Splash Page Layout
+## Splash page layout
 
 For full-width landing pages that need a little something extra add `layout: splash` to the YAML Front Matter.
 
@@ -335,7 +335,7 @@ For full-width landing pages that need a little something extra add `layout: spl
 
 Feature blocks can be assigned and aligned to the `left`, `right`, or `center` with a sprinkling of YAML. For full details on how to use the `feature_row` helper check the [**Content**]({{ "/docs/helpers/" | relative_url }}) section or review a [sample splash page](https://github.com/{{ site.repository }}/blob/master/docs/_pages/splash-page.md).
 
-## Search Page Layout
+## Search page layout
 
 A page with a search form. Add `layout: search` to the YAML Front Matter similar to [this example](https://github.com/mmistakes/minimal-mistakes/blob/master/test/_pages/search.md) on the test site.
 
@@ -401,7 +401,7 @@ header:
 **ProTip:** Captions written in Markdown are supported, so feel free to add links, or style text. Just be sure to wrap it in quotes.
 {: .notice--info}
 
-### Header Overlay
+### Header overlay
 
 To overlay text on top of a header image you have a few more options:
 
@@ -485,7 +485,7 @@ header:
       url: "#bar"
 ```
 
-### OpenGraph & Twitter Card Images
+### Open Graph & Twitter Card images
 
 By default the large page header or overlay images are used for sharing previews. If you'd like to set this image to something else use `page.header.og_image` like:
 
@@ -504,7 +504,7 @@ header:
 
 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
+### Author profile
 
 Add `author_profile: true` to a post or page's YAML Front Matter.
 
@@ -563,7 +563,7 @@ For example, to color a Reddit icon, simply add a `color` declaration and the co
 
 ![Reddit link in author profile with color]({{ "/assets/images/mm-author-profile-reddit-color.png" | relative_url }})
 
-### Custom Sidebar Content
+### Custom sidebar content
 
 Blocks of content can be added by using the following under `sidebar`:
 
@@ -594,7 +594,7 @@ sidebar:
 **Note:** Custom sidebar content added to a post or page's YAML Front Matter will appear below the author profile if enabled with `author_profile: true`.
 {: .notice--info}
 
-### Custom Sidebar Navigation Menu
+### Custom sidebar navigation menu
 
 To create a sidebar menu[^sidebar-menu] similar to the one found in the theme's documentation pages you'll need to modify a `_data` file and some YAML Front Matter.
 
@@ -683,7 +683,7 @@ defaults:
 
 ---
 
-## Social Sharing Links
+## Social sharing links
 
 The `single` layout has an option to enable social links at the bottom of posts for sharing on Twitter, Facebook, Google+, and LinkedIn. Similar to the links found in the author sidebar, the theme ships with defaults for the most common social networks.
 

docs/_docs/14-helpers.md

@@ -30,7 +30,7 @@ feature_row:
   - image_path: /assets/images/unsplash-gallery-image-3-th.jpg
     title: "Placeholder 3"
     excerpt: "This is some sample content that goes here with **Markdown** formatting."
-last_modified_at: 2018-06-11T07:56:49-04:00
+last_modified_at: 2018-11-25T19:46:11-05:00
 toc: true
 toc_label: "Helpers"
 toc_icon: "cogs"
@@ -38,7 +38,7 @@ toc_icon: "cogs"
 
 You can think of these Jekyll helpers as little shortcuts. Since GitHub Pages doesn't allow most plugins --- [custom tags](https://jekyllrb.com/docs/plugins/#tags) are out. Instead the theme leverages [**includes**](https://jekyllrb.com/docs/templates/#includes) to do something similar.
 
-## Group by Array
+## Group by array
 
 [Jekyll Group-By-Array](https://github.com/mushishi78/jekyll-group-by-array) by Max White.
 
@@ -120,7 +120,7 @@ And then drop-in the gallery include in the body where you'd like it to appear.
 **More Gallery Goodness:** A few more examples and [source code](https://github.com/{{ site.repository }}/blob/master/docs/\_posts/2010-09-09-post-gallery.md) can be seen in [this sample gallery post]({{ "" | relative_url }}{% post_url 2010-09-09-post-gallery %}).
 {: .notice--info}
 
-## Feature Row
+## Feature row
 
 Designed to compliment the [`splash`]({{ "/docs/layouts/#splash-page-layout" | relative_url }}) page layout as a way of arranging and aligning "feature blocks" containing text or image.
 
@@ -171,7 +171,7 @@ And then drop-in the feature row include in the body where you'd like it to appe
 **More Feature Row Goodness:** A [few more examples]({{ "/splash-page/" | relative_url }}) and [source code](https://github.com/{{ site.repository }}/blob/master/docs/\_pages/splash-page.md) can be seen in the demo site.
 {: .notice--info}
 
-## Responsive Video Embed
+## Responsive video embed
 
 Embed a video from YouTube or Vimeo that responsively sizes to fit the width of its parent. To help with GDPR compliance, the theme is using the privacy enhanced version of both providers out of the box.
 
@@ -218,7 +218,7 @@ header:
     provider: vimeo
 ```
 
-## Table of Contents
+## Table of contents
 
 Auto-generated table of contents list for your posts and pages can be enabled using two methods.
 
@@ -273,7 +273,7 @@ To include a Kramdown [auto-generated table of contents](https://kramdown.gettal
 {% raw %}{% include toc icon="cog" title="My Table of Contents" %}{% endraw %}
 ```
 
-## Navigation List
+## Navigation list
 
 Include an unordered list of links to be used as sidebar navigation with the `nav_list` helper.
 

docs/_docs/15-utility-classes.md

@@ -2,7 +2,7 @@
 title: "Utility Classes"
 permalink: /docs/utility-classes/
 excerpt: "CSS classes for aligning text/image, styling buttons and notices, and more."
-last_modified_at: 2018-08-15T09:53:10-04:00
+last_modified_at: 2018-11-25T19:46:43-05:00
 toc: true
 toc_label: "Utility Classes"
 toc_icon: "cogs"
@@ -13,7 +13,7 @@ Using the Kramdown Markdown renderer with Jekyll allows you to add [block](http:
 **Jekyll 3:** Kramdown is the default for `jekyll new` sites and those hosted on GitHub Pages. Not using Kramdown? That's OK. The following classes are still available when used with standard HTML.
 {: .notice--warning}
 
-## Text Alignment
+## Text alignment
 
 Align text blocks with the following classes.
 
@@ -65,7 +65,7 @@ No wrap text.
 {: .text-nowrap}
 ```
 
-## Image Alignment
+## Image alignment
 
 Position images with the following classes.
 

docs/_docs/16-stylesheets.md

@@ -2,7 +2,7 @@
 title: "Stylesheets"
 permalink: /docs/stylesheets/
 excerpt: "Instructions for customizing and building the theme's stylesheets."
-last_modified_at: 2018-03-20T16:00:22-04:00
+last_modified_at: 2018-11-25T19:47:43-05:00
 toc: true
 ---
 
@@ -71,7 +71,7 @@ $link-color: red;
 
 Before any `@import` lines.
 
-### Paragraph Indention 
+### 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` indents are added to each sibling and the margin below each paragraph is removed.
 
@@ -82,7 +82,7 @@ To mimic the look of type set in a printed book or manuscript you may want to en
 
 The size of the indent can also be customized by changing the value of `$indent-var`.
 
-### Font Stacks
+### 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 by default.
 
@@ -98,7 +98,7 @@ Sans-serif fonts have been used for most of the type, with serifs reserved for c
 **ProTip:** To use webfonts from services like [Adobe TypeKit](https://typekit.com/) or [Google Fonts](https://www.google.com/fonts) simply update the font stacks and then add their scripts to `_includes/head/custom.html`.
 {: .notice--info}
 
-#### Typography from Older Versions
+#### Typography from older versions
 
 Not a fan of the refreshed typography of the theme and want to revert back an older version? Easy enough.
 
@@ -118,7 +118,7 @@ $global-font-family : $serif;
 $header-font-family : $sans-serif-narrow;
 ```
 
-### Type Scale
+### Type scale
 
 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. 
 
@@ -149,7 +149,7 @@ $type-size-8 : 0.625em;  // ~10px
 
 Change the mood of your site by altering a few color variables. `$body-color`, `$background-color`, `$text-color`, `$link-color`, and `$masthead-link-color` will have the most affect when changed.
 
-#### Syntax Highlighting
+#### Syntax highlighting
 
 To make customizing the colors used in code highlighted blocks, a base of sixteen colors ([Base16](http://chriskempson.com/projects/base16/)) have been used.
 
@@ -179,7 +179,7 @@ $base0e: #c792ea;
 $base0f: #ff5370;
 ```
 
-##### Solarized Light
+##### Solarized light
 
 ![solarized-light-code-block]({{ '/assets/images/solarized-light-code-block.jpg' | relative_url }})
 
@@ -347,7 +347,7 @@ $base0e: #b294bb;
 $base0f: #a3685a;
 ```  
 
-### Breakpoints and Grid Stuff
+### Breakpoints and grid stuff
 
 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.
 
@@ -358,7 +358,7 @@ And `$susy` is used for setting [the grid](http://susy.oddbird.net/) the theme u
   <figcaption>Susy grid debug overlay enabled.</figcaption>
 </figure>
 
-### Disabling Animations
+### Disabling animations
 
 You can disable either the fade-in intro animation, element transition animations, or both by overriding the corresponding variables. For example if you wanted to disable all animations you could include the following lines:
 

docs/_docs/17-javascript.md

@@ -46,7 +46,7 @@ footer_scripts:
 
 ---
 
-## Build Process
+## Build process
 
 In an effort to reduce dependencies a set of [**npm scripts**](https://css-tricks.com/why-npm-scripts/) are used to build `main.min.js` instead of task runners like [Gulp](http://gulpjs.com/) or [Grunt](http://gruntjs.com/). If those tools are more your style then by all means use them instead :wink:.
 

docs/_docs/19-contributing.md

@@ -11,7 +11,7 @@ Minimal Mistakes has been designed as a base for you to customize and fit your s
 
 This goes for author sidebar links and "share button" additions -- I have no intention of merging in every possibly option, the essentials are there to get you started :smile:.
 
-## Pull Requests
+## Pull requests
 
 When submitting a pull request: