Toggle table of contents via front matter (mmistakes#1310)

* Add jekyll-toc include
* Reduce whitespace generated by comments
* Add table of contents include to `single` layout
* Replace `toc` include with jekyll-toc enabled YAML Front Matter
* Update README
* Update table of contents documentation
  - Revise `toc` helper include to mention that it will be deprecated in the next major version.
  - Add documentation to `single` layout explaining how to enable table of contents on those pages.
* Update CHANGELOG and history
* Update LICENSE

Close mmistakes#1222

Author: mmistakes

CHANGELOG.md

@@ -11,6 +11,7 @@
 - Add Naver Webmaster Tools verification. [#1286](https://github.com/mmistakes/minimal-mistakes/pull/1286)
 - Add support for Staticman v2 endpoint and reCAPTCHA.
 - Add Polish localized UI text strings. [#1304](https://github.com/mmistakes/minimal-mistakes/pull/1304)
+- Add toggleable table of contents via YAML Front Matter. Note: `toc` helper include will be deprecated in next major version. [#1222](https://github.com/mmistakes/minimal-mistakes/issues/1222) 
 
 ### Bug Fixes
 

README.md

@@ -22,7 +22,7 @@ Minimal Mistakes is a flexible two-column Jekyll theme. Perfect for hosting your
 - Several responsive layout options (single, archive index, splash, and paginated home page).
 - Optimized for search engines with support for [Twitter Cards](https://dev.twitter.com/cards/overview) and [Open Graph](http://ogp.me/) data
 - Optional [header images](https://mmistakes.github.io/minimal-mistakes/docs/layouts/#headers), [custom sidebars](https://mmistakes.github.io/minimal-mistakes/docs/layouts/#sidebars), [table of contents](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#table-of-contents), [galleries](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#gallery), related posts, [breadcrumb links](https://mmistakes.github.io/minimal-mistakes/docs/configuration/#breadcrumb-navigation-beta), [navigation lists](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#navigation-list), and more.
-- Commenting support (powered by [Disqus](https://disqus.com/), [Facebook](https://developers.facebook.com/docs/plugins/comments), Google+, [Discourse](https://www.discourse.org/), static-based via [Staticman v1](https://staticman.net/), and custom).
+- Commenting support (powered by [Disqus](https://disqus.com/), [Facebook](https://developers.facebook.com/docs/plugins/comments), Google+, [Discourse](https://www.discourse.org/), static-based via [Staticman v1 and v2](https://staticman.net/), and custom).
 - [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, Indonesian, Italian (Italiano), Korean, Nepali (Nepalese), Polish, Russian, Spanish (Español), Swedish, Turkish (Türkçe), and Vietnamese.
 
@@ -206,4 +206,8 @@ GreedyNav.js is distributed under the terms of the [MIT License](http://opensour
 
 Minimal Mistakes incorporates [Jekyll Group-By-Array](https://github.com/mushishi78/jekyll-group-by-array),
 Copyright (c) 2015 Max White <mushishi78@gmail.com>.
-Jekyll Group-By-Array is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+Jekyll Group-By-Array is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+Minimal Mistakes incorporates [@allejo's Pure Liquid Jekyll Table of Contents](https://allejo.io/blog/a-jekyll-toc-in-liquid-only/),
+Copyright (c) 2017 Vladimir Jimenez.
+Pure Liquid Jekyll Table of Contents is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).

_includes/toc.html

@@ -0,0 +1,73 @@
+{% capture tocWorkspace %}
+    {%- comment -%}
+        "...like all things liquid - where there's a will, and ~36 hours to spare, there's usually a/some way" ~jaybe
+
+        Usage:
+            {% include toc.html html=content sanitize=true class="inline_toc" id="my_toc" h_min=2 h_max=3 %}
+
+        Parameters:
+            * html     (string) - the HTML of compiled markdown generated by kramdown in Jekyll
+
+        Optional Parameters:
+            * sanitize (bool)   : false  - when set to true, the headers will be stripped of any HTML in the TOC
+            * class    (string) :   ''   - a CSS class assigned to the TOC
+            * id       (string) :   ''   - an ID to assigned to the TOC
+            * h_min    (int)    :   1    - the minimum TOC header level to use; any header lower than this value will be ignored
+            * h_max    (int)    :   6    - the maximum TOC header level to use; any header greater than this value will be ignored
+
+        Output:
+            An unordered list representing the table of contents of a markdown block. This snippet will only generate the table of contents and will NOT output the markdown given to it
+    {%- endcomment -%}
+
+    {% capture my_toc %}{% endcapture %}
+    {% assign minHeader = include.h_min | default: 1 %}
+    {% assign maxHeader = include.h_max | default: 6 %}
+    {% assign nodes = include.html | split: '<h' %}
+    {% assign firstHeader = true %}
+
+    {% for node in nodes %}
+        {% if node == "" %}
+            {% continue %}
+        {% endif %}
+
+        {% assign headerLevel = node | replace: '"', '' | slice: 0, 1 | times: 1 %}
+
+        {% if headerLevel < minHeader or headerLevel > maxHeader %}
+            {% continue %}
+        {% endif %}
+
+        {% if firstHeader %}
+            {% assign firstHeader = false %}
+            {% assign minHeader = headerLevel %}
+        {% endif %}
+
+        {% assign indentAmount = headerLevel | minus: minHeader | add: 1 %}
+        {% assign _workspace = node | split: '</h' %}
+
+        {% assign _idWorkspace = _workspace[0] | split: '"' %}
+        {% assign html_id = _idWorkspace[1] %}
+
+        {% capture _hAttrToStrip %}{{ headerLevel }} id="{{ html_id }}">{% endcapture %}
+        {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}
+
+        {% assign space = '' %}
+        {% for i in (1..indentAmount) %}
+            {% assign space = space | prepend: '  ' %}
+        {% endfor %}
+
+        {% capture my_toc %}{{ my_toc }}
+{{ space }}- [{% if include.sanitize %}{{ header | strip_html }}{% else %}{{ header }}{% endif %}](#{{ html_id }}){% endcapture %}
+
+    {% endfor %}
+
+    {% if include.class %}
+        {% capture my_toc %}{:.{{ include.class }}}
+{{ my_toc | lstrip }}{% endcapture %}
+    {% endif %}
+
+    {% if include.id %}
+        {% capture my_toc %}{: #{{ include.id }}}
+{{ my_toc | lstrip }}{% endcapture %}
+    {% endif %}
+{% endcapture %}{% assign tocWorkspace = '' %}
+{{ my_toc | markdownify }}

_layouts/single.html

@@ -34,6 +34,14 @@
       {% endunless %}
 
       <section class="page__content" itemprop="text">
+        {% if page.toc %}
+          <aside class="sidebar__right">
+            <nav class="toc">
+              <header><h4 class="nav__title"><i class="fa fa-{{ page.toc_icon | default: 'file-text' }}"></i> {{ page.toc_label | default: site.data.ui-text[site.locale].toc_label }}</h4></header>
+              {% include toc.html sanitize=true html=content h_min=2 h_max=3 class="toc__menu" %}
+            </nav>
+          </aside>
+        {% endif %}
         {{ content }}
         {% if page.link %}<div><a href="{{ page.link }}" class="btn btn--primary">{{ site.data.ui-text[site.locale].ext_link_label | default: "Direct Link" }}</a></div>{% endif %}
       </section>

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

@@ -2,15 +2,14 @@
 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: 2017-09-21T16:24:15-04:00
+last_modified_at: 2017-10-20T12:34:04-04: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 a more involved installation process.
 
-{% include toc %}
-
 ## Installing the Theme
 
 If you're running Jekyll v3.5+ and self-hosting you can quickly install the theme as a Ruby gem. If you're hosting with GitHub Pages you'll have to use the old "repo fork" method or directly copy all of the theme files[^structure] into your site.

docs/_docs/03-installation.md

@@ -3,6 +3,7 @@ title: "Installation"
 permalink: /docs/installation/
 excerpt: "Instructions for installing the theme for new and existing Jekyll based sites."
 last_modified_at: 2017-08-04T12:38:01-04:00
+toc: true
 ---
 
 ## Install the Theme

docs/_docs/04-upgrading.md

@@ -3,6 +3,7 @@ title: "Upgrading"
 permalink: /docs/upgrading/
 excerpt: "Instructions and suggestions for upgrading the theme."
 last_modified_at: 2016-11-03T10:16:34-04:00
+toc: true
 ---
 
 If you're using the Ruby Gem version of the theme upgrading is fairly painless.

docs/_docs/05-configuration.md

@@ -2,13 +2,12 @@
 title: "Configuration"
 permalink: /docs/configuration/
 excerpt: "Settings for configuring and customizing the theme."
-last_modified_at: 2017-10-04T16:31:28-04:00
+last_modified_at: 2017-10-20T12:34:20-04:00
+toc: true
 ---
 
 Settings that affect your entire site can be changed in [Jekyll's configuration file](https://jekyllrb.com/docs/configuration/): `_config.yml`, found in the root of your project. If you don't have this file you'll need to copy or create one using the theme's [default `_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml) as a base.
 
-{% include toc %}
-
 **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}
 

docs/_docs/07-navigation.md

@@ -3,6 +3,7 @@ title: "Navigation"
 permalink: /docs/navigation/
 excerpt: "Instructions on how to customize the main navigation and enabling breadcrumb links."
 last_modified_at: 2016-11-03T10:50:03-04:00
+toc: true
 ---
 
 ## Masthead

docs/_docs/10-layouts.md

@@ -7,11 +7,12 @@ 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: 2017-07-05T15:41:36-04:00
+last_modified_at: 2017-10-20T14:26:10-04:00
+toc: true
+toc_label: "Included Layouts"
+toc_icon: "columns"
 ---
 
-{% include toc icon="columns" title="Included Layouts" %}
-
 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
@@ -83,6 +84,28 @@ 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" | absolute_url }}) in `_config.yml`.
 
+### 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.
+
+![table of contents example]({{ "/assets/images/mm-toc-helper-example.jpg" | absolute_url }})
+
+| Parameter   | Required | Description | Default |
+| ---------   | -------- | ----------- | ------- |
+| **toc**     | Optional | Show table of contents. (boolean) | `false` |
+| **toc_label** | Optional | Table of contents title. (string) | `toc_label` in UI Text data file. |
+| **toc_icon**  | Optional | Table of contents icon, displays before the title. (string) | [Font Awesome](https://fortawesome.github.io/Font-Awesome/icons/) <i class="fa fa-file-text"></i> **file-text** icon. Any other FA icon can be used instead. |
+
+**TOC example with custom title and icon**
+
+```yaml
+---
+toc: true
+toc_label: "My Table of Contents"
+toc_icon: "gear"
+---
+```
+
 ## Archive Layout
 
 Essentially the same as `single` with markup adjustments and some modules removed.

docs/_docs/14-helpers.md

@@ -30,11 +30,12 @@ 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: 2017-05-16T11:45:00-04:00
+last_modified_at: 2017-10-20T14:20:36-04:00
+toc: true
+toc_label: "Helpers"
+toc_icon: "gears"
 ---
 
-{% include toc icon="gears" title="Helpers" %}
-
 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.
 
 ## Base Path
@@ -238,18 +239,51 @@ header:
 
 ## Table of Contents
 
-To include an [auto-generated table of contents](https://kramdown.gettalong.org/converter/html.html#toc) for posts and pages, add the following helper before any actual content in your post or page.
+Auto-generated table of contents list for your posts and pages can be enabled using two methods.
+
+![table of contents example]({{ "/assets/images/mm-toc-helper-example.jpg" | absolute_url }})
+
+### Enabled via YAML Front Matter
+
+Add `toc: true` to the YAML Front Matter of any post or page.
+
+| Parameter   | Required | Description | Default |
+| ---------   | -------- | ----------- | ------- |
+| **toc**     | Optional | Show table of contents. (boolean) | `false` |
+| **toc_label** | Optional | Table of contents title. (string) | `toc_label` in UI Text data file. |
+| **toc_icon**  | Optional | Table of contents icon, displays before the title. (string) | [Font Awesome](https://fortawesome.github.io/Font-Awesome/icons/) <i class="fa fa-file-text"></i> **file-text** icon. Any other FA icon can be used instead. |
+
+**TOC example with custom title and icon**
+
+```yaml
+---
+toc: true
+toc_label: "My Table of Contents"
+toc_icon: "gear"
+---
+```
+
+**Note:** using both methods will have unintended results. Be sure to remove `{% raw %}{% include toc %}{% endraw %}` placed table of contents from your content when using `toc: true`.
+{: .notice--warning }
+
+### Enabled via `toc` include (deprecated)
+
+To include a Kramdown [auto-generated table of contents](https://kramdown.gettalong.org/converter/html.html#toc) for posts and pages, add the following helper to your content.
 
 ```liquid
 {% raw %}{% include toc %}{% endraw %}
 ```
 
-![table of contents example]({{ "/assets/images/mm-toc-helper-example.jpg" | absolute_url }})
+**Note:** this method only works with Markdown files.
+{: .notice--warning}
+
+**Deprecated:** `toc` helper will be removed in the next major version of the theme. It is encouraged that you migrate to the YAML Front Matter method above.
+{: .notice--danger}
 
 | Parameter   | Required | Description | Default |
 | ---------   | -------- | ----------- | ------- |
-| **title**   | Optional | Table of contents title. | `toc_label` in UI Text data file. |
-| **icon**    | Optional | Table of contents icon (shows before the title). | [Font Awesome](https://fortawesome.github.io/Font-Awesome/icons/) <i class="fa fa-file-text"></i> **file-text** icon. Any other FA icon can be used instead. |
+| **title**   | Optional | Table of contents title. (string) | `toc_label` in UI Text data file. |
+| **icon**    | Optional | Table of contents icon, displays before the title. (string) | [Font Awesome](https://fortawesome.github.io/Font-Awesome/icons/) <i class="fa fa-file-text"></i> **file-text** icon. Any other FA icon can be used instead. |
 
 **TOC example with custom title and icon**
 

docs/_docs/15-utility-classes.md

@@ -2,11 +2,12 @@
 title: "Utility Classes"
 permalink: /docs/utility-classes/
 excerpt: "CSS classes for aligning text/image, styling buttons and notices, and more."
-last_modified_at: 2017-09-01T11:54:44-04:00
+last_modified_at: 2017-10-20T12:36:34-04:00
+toc: true
+toc_label: "Utility Classes"
+toc_icon: "gears"
 ---
 
-{% include toc icon="gears" title="Utility Classes" %}
-
 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.
 
 **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.

docs/_docs/18-history.md

@@ -4,7 +4,8 @@ permalink: /docs/history/
 excerpt: "Change log of enhancements and bug fixes made to the theme."
 sidebar:
   nav: docs
-last_modified_at: 2017-10-16T12:40:54-04:00
+last_modified_at: 2017-10-20T14:22:30-04:00
+toc: true
 ---
 
 ## Unreleased
@@ -20,6 +21,7 @@ last_modified_at: 2017-10-16T12:40:54-04:00
 - Add Naver Webmaster Tools verification. [#1286](https://github.com/mmistakes/minimal-mistakes/pull/1286)
 - Add support for Staticman v2 endpoint and reCAPTCHA.
 - Add Polish localized UI text strings. [#1304](https://github.com/mmistakes/minimal-mistakes/pull/1304)
+- Add toggleable table of contents via YAML Front Matter. Note: `toc` helper include will be deprecated in next major version. [#1222](https://github.com/mmistakes/minimal-mistakes/issues/1222) 
 
 ### Bug Fixes
 

docs/_docs/20-docs-2-2.md

@@ -2,11 +2,10 @@
 title: "2.2 Documentation"
 permalink: /docs/docs-2-2/
 excerpt: "Setup and installation instructions for Minimal Mistakes 2.2 (deprecated)."
-last_modified_at: 2016-04-13T15:54:02-04:00
+last_modified_at: 2017-10-20T12:37:11-04:00
+toc: true
 ---
 
-{% include toc %}
-
 ## Installation
 
 Minimal Mistakes now requires [Jekyll](http://jekyllrb.com/) 3.0. Make sure to run `bundle update` if you aren't on the latest version to update all gem dependencies.

docs/_docs/21-license.md

@@ -2,7 +2,7 @@
 title: "License"
 permalink: /docs/license/
 excerpt: "License for Minimal Mistakes Jekyll Theme."
-last_modified_at: 2017-10-16T15:51:24-04:00
+last_modified_at: 2017-10-20T14:44:38-04:00
 ---
 
 The MIT License (MIT)
@@ -63,4 +63,8 @@ GreedyNav.js is distributed under the terms of the [MIT License](http://opensour
 
 Minimal Mistakes incorporates [Jekyll Group-By-Array](https://github.com/mushishi78/jekyll-group-by-array),
 Copyright (c) 2015 Max White <mushishi78@gmail.com>.
-Jekyll Group-By-Array is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+Jekyll Group-By-Array is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+Minimal Mistakes incorporates [@allejo's Pure Liquid Jekyll Table of Contents](https://allejo.io/blog/a-jekyll-toc-in-liquid-only/),
+Copyright (c) 2017 Vladimir Jimenez.
+Pure Liquid Jekyll Table of Contents is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).

docs/_includes/toc.html

@@ -0,0 +1,73 @@
+{% capture tocWorkspace %}
+    {%- comment -%}
+        "...like all things liquid - where there's a will, and ~36 hours to spare, there's usually a/some way" ~jaybe
+
+        Usage:
+            {% include toc.html html=content sanitize=true class="inline_toc" id="my_toc" h_min=2 h_max=3 %}
+
+        Parameters:
+            * html     (string) - the HTML of compiled markdown generated by kramdown in Jekyll
+
+        Optional Parameters:
+            * sanitize (bool)   : false  - when set to true, the headers will be stripped of any HTML in the TOC
+            * class    (string) :   ''   - a CSS class assigned to the TOC
+            * id       (string) :   ''   - an ID to assigned to the TOC
+            * h_min    (int)    :   1    - the minimum TOC header level to use; any header lower than this value will be ignored
+            * h_max    (int)    :   6    - the maximum TOC header level to use; any header greater than this value will be ignored
+
+        Output:
+            An unordered list representing the table of contents of a markdown block. This snippet will only generate the table of contents and will NOT output the markdown given to it
+    {%- endcomment -%}
+
+    {% capture my_toc %}{% endcapture %}
+    {% assign minHeader = include.h_min | default: 1 %}
+    {% assign maxHeader = include.h_max | default: 6 %}
+    {% assign nodes = include.html | split: '<h' %}
+    {% assign firstHeader = true %}
+
+    {% for node in nodes %}
+        {% if node == "" %}
+            {% continue %}
+        {% endif %}
+
+        {% assign headerLevel = node | replace: '"', '' | slice: 0, 1 | times: 1 %}
+
+        {% if headerLevel < minHeader or headerLevel > maxHeader %}
+            {% continue %}
+        {% endif %}
+
+        {% if firstHeader %}
+            {% assign firstHeader = false %}
+            {% assign minHeader = headerLevel %}
+        {% endif %}
+
+        {% assign indentAmount = headerLevel | minus: minHeader | add: 1 %}
+        {% assign _workspace = node | split: '</h' %}
+
+        {% assign _idWorkspace = _workspace[0] | split: '"' %}
+        {% assign html_id = _idWorkspace[1] %}
+
+        {% capture _hAttrToStrip %}{{ headerLevel }} id="{{ html_id }}">{% endcapture %}
+        {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}
+
+        {% assign space = '' %}
+        {% for i in (1..indentAmount) %}
+            {% assign space = space | prepend: '  ' %}
+        {% endfor %}
+
+        {% capture my_toc %}{{ my_toc }}
+{{ space }}- [{% if include.sanitize %}{{ header | strip_html }}{% else %}{{ header }}{% endif %}](#{{ html_id }}){% endcapture %}
+
+    {% endfor %}
+
+    {% if include.class %}
+        {% capture my_toc %}{:.{{ include.class }}}
+{{ my_toc | lstrip }}{% endcapture %}
+    {% endif %}
+
+    {% if include.id %}
+        {% capture my_toc %}{: #{{ include.id }}}
+{{ my_toc | lstrip }}{% endcapture %}
+    {% endif %}
+{% endcapture %}{% assign tocWorkspace = '' %}
+{{ my_toc | markdownify }}

docs/_layouts/single.html

@@ -34,6 +34,14 @@
       {% endunless %}
 
       <section class="page__content" itemprop="text">
+        {% if page.toc %}
+          <aside class="sidebar__right">
+            <nav class="toc">
+              <header><h4 class="nav__title"><i class="fa fa-{{ page.toc_icon | default: 'file-text' }}"></i> {{ page.toc_label | default: site.data.ui-text[site.locale].toc_label }}</h4></header>
+              {% include toc.html sanitize=true html=content h_min=2 h_max=3 class="toc__menu" %}
+            </nav>
+          </aside>
+        {% endif %}
         {{ content }}
         {% if page.link %}<div><a href="{{ page.link }}" class="btn btn--primary">{{ site.data.ui-text[site.locale].ext_link_label | default: "Direct Link" }}</a></div>{% endif %}
       </section>

docs/_pages/about.md

@@ -12,7 +12,8 @@ layouts_gallery:
   - url: /assets/images/mm-layout-archive.png
     image_path: /assets/images/mm-layout-archive.png
     alt: "archive layout example"
-last_modified_at: 2017-10-16T12:43:05-04:00
+last_modified_at: 2017-10-20T12:43:30-04:00
+toc: true
 ---
 
 Minimal Mistakes is a flexible two-column Jekyll theme. Perfect for hosting your personal site, blog, or portfolio on GitHub or self-hosting on your own server. As the name implies --- styling is purposely minimalistic to be enhanced and customized by you :smile:.
@@ -23,12 +24,14 @@ Minimal Mistakes is a flexible two-column Jekyll theme. Perfect for hosting your
 
 ## Notable Features
 
-- Compatible with Jekyll 3.x and GitHub Pages
-- Support for Jekyll's built-in Sass/SCSS preprocessor
-- Several responsive layout options (single, archive index, splash, and paginated home page)
-- SEO optimized with support for [Twitter Cards](https://dev.twitter.com/cards/overview) and [Open Graph](http://ogp.me/) data
+- Bundled as a "theme gem" for easier install/upgrading.
+- Compatible with GitHub Pages.
+- Support for Jekyll's built-in Sass/SCSS preprocessor.
+- Seven different skins (color variations).
+- Several responsive layout options (single, archive index, splash, and paginated home page).
+- Optimized for search engines with support for [Twitter Cards](https://dev.twitter.com/cards/overview) and [Open Graph](http://ogp.me/) data
 - Optional [header images](https://mmistakes.github.io/minimal-mistakes/docs/layouts/#headers), [custom sidebars](https://mmistakes.github.io/minimal-mistakes/docs/layouts/#sidebars), [table of contents](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#table-of-contents), [galleries](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#gallery), related posts, [breadcrumb links](https://mmistakes.github.io/minimal-mistakes/docs/configuration/#breadcrumb-navigation-beta), [navigation lists](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#navigation-list), and more.
-- Commenting support (powered by [Disqus](https://disqus.com/), [Facebook](https://developers.facebook.com/docs/plugins/comments), Google+, [Discourse](https://www.discourse.org/), static-based via [Staticman](https://staticman.net/), and custom).
+- Commenting support (powered by [Disqus](https://disqus.com/), [Facebook](https://developers.facebook.com/docs/plugins/comments), Google+, [Discourse](https://www.discourse.org/), static-based via [Staticman v1 and v2](https://staticman.net/), and custom).
 - [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, Indonesian, Italian (Italiano), Korean, Nepali (Nepalese), Polish, Russian, Spanish (Español), Swedish, Turkish (Türkçe), and Vietnamese.
 

docs/_pages/terms.md

@@ -1,11 +1,10 @@
 ---
 permalink: /terms/
 title: "Terms and Privacy Policy"
-last_modified_at: 2016-11-03T11:57:46-04:00
+last_modified_at: 2017-10-20T12:42:38-04:00
+toc: true
 ---
 
-{% include toc %}
-
 ## Privacy Policy
 
 The privacy of my visitors is extremely important. This Privacy Policy outlines the types of personal information that is received and collected and how it is used.

docs/_posts/2012-01-03-layout-table-of-contents-bottom-post.md

@@ -5,27 +5,25 @@ header:
   caption: "Photo credit: [**Unsplash**](https://unsplash.com)"
 tags:
   - table of contents
+toc: true
+toc_label: "Unique Title"
+toc_icon: "heart"
 ---
 
-{% include toc title="Unique Title" icon="file-text" %}
+Enable table of contents on post or page by adding `toc: true` to its YAML Front Matter. The title and icon can also be changed with:
 
-Testing Kramdown auto-generated table of contents with unique title and icon assigned in the include like so:
-
-```liquid
-{% raw %}{% include toc title="Unique Title" icon="file-text" %}{% endraw %}
+```yaml
+---
+toc: true
+toc_label: "Unique Title"
+toc_icon: "heart"  # corresponding Font Awesome icon name (without fa prefix)
+---
 ```
 
 ## HTML Elements
 
 Below is just about everything you'll need to style in the theme. Check the source code to see the many embedded elements within paragraphs.
 
-<h1>Heading 1</h1>
-<h2>Heading 2</h2>
-<h3>Heading 3</h3>
-<h4>Heading 4</h4>
-<h5>Heading 5</h5>
-<h6>Heading 6</h6>
-
 ## Body text
 
 Lorem ipsum dolor sit amet, test link adipiscing elit. **This is strong**. Nullam dignissim convallis est. Quisque aliquam.

docs/_posts/2012-01-03-layout-table-of-contents-post.md

@@ -10,12 +10,11 @@ tags:
   - formatting
   - html
   - markup
+toc: true
 ---
 
 A variety of common markup showing how the theme styles them.
 
-# Header one
-
 ## Header two
 
 ### Header three
@@ -121,7 +120,8 @@ Make any link standout more when applying the `.btn` class.
 <a href="#" class="btn--success">Success Button</a>
 ```
 
-[Primary Button](#){: .btn}
+[Default Button](#){: .btn}
+[Primary Button](#){: .btn .btn--primary}
 [Success Button](#){: .btn .btn--success}
 [Warning Button](#){: .btn .btn--warning}
 [Danger Button](#){: .btn .btn--danger}
@@ -130,7 +130,8 @@ Make any link standout more when applying the `.btn` class.
 [Light Outline Button](#){: .btn .btn--light-outline}
 
 ```markdown
-[Primary Button Text](#link){: .btn}
+[Default Button Text](#link){: .btn}
+[Primary Button Text](#link){: .btn .btn--primary}
 [Success Button Text](#link){: .btn .btn--success}
 [Warning Button Text](#link){: .btn .btn--warning}
 [Danger Button Text](#link){: .btn .btn--danger}
@@ -139,23 +140,38 @@ Make any link standout more when applying the `.btn` class.
 [Light Outline Button](#link){: .btn .btn--light-outline}
 ```
 
-[X-Large Button](#){: .btn .btn--x-large}
-[Large Button](#){: .btn .btn--large}
-[Default Button](#){: .btn}
-[Small Button](#){: .btn .btn--small}
+[X-Large Button](#){: .btn .btn--primary .btn--x-large}
+[Large Button](#){: .btn .btn--primary .btn--large}
+[Default Button](#){: .btn .btn--primary }
+[Small Button](#){: .btn .btn--primary .btn--small}
 
 ```markdown
-[X-Large Button](#link){: .btn .btn--x-large}
-[Large Button](#link){: .btn .btn--large}
-[Default Button](#link){: .btn}
-[Small Button](#link){: .btn .btn--small}
+[X-Large Button](#link){: .btn .btn--primary .btn--x-large}
+[Large Button](#link){: .btn .btn--primary .btn--large}
+[Default Button](#link){: .btn .btn--primary }
+[Small Button](#link){: .btn .btn--primary .btn--small}
 ```
 
 ## Notices
 
-**Watch out!** You can also add notices by appending `{: .notice}` to a paragraph.
+**Watch out!** This paragraph of text has been [emphasized](#) with the `{: .notice}` class.
 {: .notice}
 
+**Watch out!** This paragraph of text has been [emphasized](#) with the `{: .notice--primary}` class.
+{: .notice--primary}
+
+**Watch out!** This paragraph of text has been [emphasized](#) with the `{: .notice--info}` class.
+{: .notice--info}
+
+**Watch out!** This paragraph of text has been [emphasized](#) with the `{: .notice--warning}` class.
+{: .notice--warning}
+
+**Watch out!** This paragraph of text has been [emphasized](#) with the `{: .notice--success}` class.
+{: .notice--success}
+
+**Watch out!** This paragraph of text has been [emphasized](#) with the `{: .notice--danger}` class.
+{: .notice--danger}
+
 ## HTML Tags
 
 ### Address Tag
@@ -226,8 +242,8 @@ Getting our science styling on with H<sub>2</sub>O, which should push the "2" do
 
 ### Superscript Tag
 
-Still sticking with science and Albert Einstein's E = MC<sup>2</sup>, which should lift the 2 up.
+Still sticking with science and Isaac Newton's E = MC<sup>2</sup>, which should lift the 2 up.
 
 ### Variable Tag
 
-This allows you to denote <var>variables</var>.
+This allows you to denote <var>variables</var>.

docs/_posts/2013-01-11-markup-html-tags-and-formatting.md

@@ -1,12 +1,13 @@
 ---
 title: "Markup: Syntax Highlighting"
 excerpt: "Post displaying the various ways of highlighting code in Markdown."
-last_modified_at: 2017-07-07T15:32:43-04:00
+last_modified_at: 2017-10-20T12:23:00-04:00
 header:
   teaser: "assets/images/markup-syntax-highlighting-teaser.jpg"
 tags: 
   - code
   - syntax highlighting
+toc: true
 ---
 
 Syntax highlighting is a feature that displays source code, in different colors and fonts according to the category of terms. This feature facilitates writing in a structured language such as a programming language or a markup language as both structures and syntax errors are visually distinct. Highlighting does not affect the meaning of the text itself; it is intended only for human readers.[^1]
@@ -98,4 +99,4 @@ Indentation matters. Be sure the indent of the code block aligns with the first
 
 An example of a Gist embed below.
 
-<script src="https://gist.github.com/mmistakes/77c68fbb07731a456805a7b473f47841.js"></script>
+<script src="https://gist.github.com/mmistakes/77c68fbb07731a456805a7b473f47841.js"></script>

docs/_posts/2013-08-16-markup-syntax-highlighting.md

@@ -1,16 +1,16 @@
 ---
 title:  "Gemified Theme -- Alpha Release"
-last_modified_at: 2016-11-03T11:46:00-04:00
+last_modified_at: 2017-10-20T12:29:34-04:00
 categories: 
   - Jekyll
 tags:
   - update
+toc: true
+toc_label: "Getting Started"
 ---
 
 Jekyll [themes distributed as Ruby gems](http://jekyllrb.com/docs/themes/) are finally here to make installing and upgrading much easier. Gone are the days of forking a repo just to "install it". Or dealing with merge conflicts when pulling in upstream commits to "upgrade it".
 
-{% include toc title="Getting Started" %}
-
 If you're interested in testing out Minimal Mistakes as a gemified theme read on. There are a few caveats though:
 
 1. Support for a theme `assets` folder was recently [added to Jekyll core](https://github.com/jekyll/jekyll/pull/5364), but has yet to be released or rolled into the `github-pages` gem. Meaning you can't use Minimal Mistakes as a Ruby gem there just yet... locally served or self-hosted installs should be fine if you don't mind using a pre-release version of Jekyll. 

docs/_posts/2016-09-21-gemified-theme-alpha.md

@@ -1,16 +1,16 @@
 ---
 title:  "Gemified Theme -- Beta Release"
-last_modified_at: 2016-11-03T11:45:04-04:00
+last_modified_at: 2017-10-20T12:29:16-04:00
 categories: 
   - Jekyll
 tags:
   - update
+toc: true
+toc_label: "Getting Started"
 ---
 
 Hot on the heels of Jekyll v3.3.0 is a beta release of Minimal Mistakes... as a gemified theme.
 
-{% include toc title="Getting Started" %}
-
 [`minimal-mistakes-jekyll`](https://rubygems.org/gems/minimal-mistakes-jekyll) can only be used with Jekyll proper. If you're hosting on GitHub Pages or using that gem the theme won't work. 3rd party themes haven't been white-listed so it's a no go for now.
 
 Fine with all that? Great. Let's continue.

docs/_posts/2016-10-06-gemified-theme-beta.md

@@ -5,27 +5,25 @@ header:
   caption: "Photo credit: [**Unsplash**](https://unsplash.com)"
 tags:
   - table of contents
+toc: true
+toc_label: "Unique Title"
+toc_icon: "heart"
 ---
 
-{% include toc title="Unique Title" icon="file-text" %}
+Enable table of contents on post or page by adding `toc: true` to its YAML Front Matter. The title and icon can also be changed with:
 
-Testing Kramdown auto-generated table of contents with unique title and icon assigned in the include like so:
-
-```liquid
-{% raw %}{% include toc title="Unique Title" icon="file-text" %}{% endraw %}
+```yaml
+---
+toc: true
+toc_label: "Unique Title"
+toc_icon: "heart"  # corresponding Font Awesome icon name (without fa prefix)
+---
 ```
 
 ## HTML Elements
 
 Below is just about everything you'll need to style in the theme. Check the source code to see the many embedded elements within paragraphs.
 
-<h1>Heading 1</h1>
-<h2>Heading 2</h2>
-<h3>Heading 3</h3>
-<h4>Heading 4</h4>
-<h5>Heading 5</h5>
-<h6>Heading 6</h6>
-
 ## Body text
 
 Lorem ipsum dolor sit amet, test link adipiscing elit. **This is strong**. Nullam dignissim convallis est. Quisque aliquam.

test/_posts/2012-01-03-layout-table-of-contents-bottom-post.md

@@ -10,12 +10,11 @@ tags:
   - formatting
   - html
   - markup
+toc: true
 ---
 
 A variety of common markup showing how the theme styles them.
 
-# Header one
-
 ## Header two
 
 ### Header three

test/_posts/2012-01-03-layout-table-of-contents-post.md

@@ -1,12 +1,13 @@
 ---
 title: "Markup: Syntax Highlighting"
 excerpt: "Post displaying the various ways of highlighting code in Markdown."
-last_modified_at: 2016-09-09T09:55:10-04:00
+last_modified_at: 2017-10-20T12:23:00-04:00
 header:
   teaser: "assets/images/markup-syntax-highlighting-teaser.jpg"
 tags: 
   - code
   - syntax highlighting
+toc: true
 ---
 
 Syntax highlighting is a feature that displays source code, in different colors and fonts according to the category of terms. This feature facilitates writing in a structured language such as a programming language or a markup language as both structures and syntax errors are visually distinct. Highlighting does not affect the meaning of the text itself; it is intended only for human readers.[^1]