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

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 <[email protected]>.
-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 <[email protected]>.
-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).