Skip to content

Commit 866fb17

Browse files
mmistakesmmistakes
authored
Toggle table of contents via front matter (#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 #1222
1 parent 4b24877 commit 866fb17

29 files changed

+332
-286
lines changed

‎CHANGELOG.md

+1
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
- Add Naver Webmaster Tools verification. [#1286](https://github.com/mmistakes/minimal-mistakes/pull/1286)
1212
- Add support for Staticman v2 endpoint and reCAPTCHA.
1313
- Add Polish localized UI text strings. [#1304](https://github.com/mmistakes/minimal-mistakes/pull/1304)
14+
- 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)
1415

1516
### Bug Fixes
1617

‎README.md

+6-2
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Minimal Mistakes is a flexible two-column Jekyll theme. Perfect for hosting your
2222
- Several responsive layout options (single, archive index, splash, and paginated home page).
2323
- Optimized for search engines with support for [Twitter Cards](https://dev.twitter.com/cards/overview) and [Open Graph](http://ogp.me/) data
2424
- 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.
25-
- 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).
25+
- 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).
2626
- [Google Analytics](https://www.google.com/analytics/) support.
2727
- 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.
2828

@@ -206,4 +206,8 @@ GreedyNav.js is distributed under the terms of the [MIT License](http://opensour
206206

207207
Minimal Mistakes incorporates [Jekyll Group-By-Array](https://github.com/mushishi78/jekyll-group-by-array),
208208
Copyright (c) 2015 Max White <[email protected]>.
209-
Jekyll Group-By-Array is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).
209+
Jekyll Group-By-Array is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).
210+
211+
Minimal Mistakes incorporates [@allejo's Pure Liquid Jekyll Table of Contents](https://allejo.io/blog/a-jekyll-toc-in-liquid-only/),
212+
Copyright (c) 2017 Vladimir Jimenez.
213+
Pure Liquid Jekyll Table of Contents is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).

‎_includes/toc.html

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
{% capture tocWorkspace %}
2+
{%- comment -%}
3+
"...like all things liquid - where there's a will, and ~36 hours to spare, there's usually a/some way" ~jaybe
4+
5+
Usage:
6+
{% include toc.html html=content sanitize=true class="inline_toc" id="my_toc" h_min=2 h_max=3 %}
7+
8+
Parameters:
9+
* html (string) - the HTML of compiled markdown generated by kramdown in Jekyll
10+
11+
Optional Parameters:
12+
* sanitize (bool) : false - when set to true, the headers will be stripped of any HTML in the TOC
13+
* class (string) : '' - a CSS class assigned to the TOC
14+
* id (string) : '' - an ID to assigned to the TOC
15+
* h_min (int) : 1 - the minimum TOC header level to use; any header lower than this value will be ignored
16+
* h_max (int) : 6 - the maximum TOC header level to use; any header greater than this value will be ignored
17+
18+
Output:
19+
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
20+
{%- endcomment -%}
21+
22+
{% capture my_toc %}{% endcapture %}
23+
{% assign minHeader = include.h_min | default: 1 %}
24+
{% assign maxHeader = include.h_max | default: 6 %}
25+
{% assign nodes = include.html | split: '<h' %}
26+
{% assign firstHeader = true %}
27+
28+
{% for node in nodes %}
29+
{% if node == "" %}
30+
{% continue %}
31+
{% endif %}
32+
33+
{% assign headerLevel = node | replace: '"', '' | slice: 0, 1 | times: 1 %}
34+
35+
{% if headerLevel < minHeader or headerLevel > maxHeader %}
36+
{% continue %}
37+
{% endif %}
38+
39+
{% if firstHeader %}
40+
{% assign firstHeader = false %}
41+
{% assign minHeader = headerLevel %}
42+
{% endif %}
43+
44+
{% assign indentAmount = headerLevel | minus: minHeader | add: 1 %}
45+
{% assign _workspace = node | split: '</h' %}
46+
47+
{% assign _idWorkspace = _workspace[0] | split: '"' %}
48+
{% assign html_id = _idWorkspace[1] %}
49+
50+
{% capture _hAttrToStrip %}{{ headerLevel }} id="{{ html_id }}">{% endcapture %}
51+
{% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}
52+
53+
{% assign space = '' %}
54+
{% for i in (1..indentAmount) %}
55+
{% assign space = space | prepend: ' ' %}
56+
{% endfor %}
57+
58+
{% capture my_toc %}{{ my_toc }}
59+
{{ space }}- [{% if include.sanitize %}{{ header | strip_html }}{% else %}{{ header }}{% endif %}](#{{ html_id }}){% endcapture %}
60+
61+
{% endfor %}
62+
63+
{% if include.class %}
64+
{% capture my_toc %}{:.{{ include.class }}}
65+
{{ my_toc | lstrip }}{% endcapture %}
66+
{% endif %}
67+
68+
{% if include.id %}
69+
{% capture my_toc %}{: #{{ include.id }}}
70+
{{ my_toc | lstrip }}{% endcapture %}
71+
{% endif %}
72+
{% endcapture %}{% assign tocWorkspace = '' %}
73+
{{ my_toc | markdownify }}

‎_layouts/single.html

+8
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,14 @@
3434
{% endunless %}
3535

3636
<section class="page__content" itemprop="text">
37+
{% if page.toc %}
38+
<aside class="sidebar__right">
39+
<nav class="toc">
40+
<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>
41+
{% include toc.html sanitize=true html=content h_min=2 h_max=3 class="toc__menu" %}
42+
</nav>
43+
</aside>
44+
{% endif %}
3745
{{ content }}
3846
{% 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 %}
3947
</section>

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

+2-3
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,14 @@
22
title: "Quick-Start Guide"
33
permalink: /docs/quick-start-guide/
44
excerpt: "How to quickly install and setup Minimal Mistakes for use with GitHub Pages."
5-
last_modified_at: 2017-09-21T16:24:15-04:00
5+
last_modified_at: 2017-10-20T12:34:04-04:00
66
redirect_from:
77
- /theme-setup/
8+
toc: true
89
---
910

1011
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.
1112

12-
{% include toc %}
13-
1413
## Installing the Theme
1514

1615
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

+1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ title: "Installation"
33
permalink: /docs/installation/
44
excerpt: "Instructions for installing the theme for new and existing Jekyll based sites."
55
last_modified_at: 2017-08-04T12:38:01-04:00
6+
toc: true
67
---
78

89
## Install the Theme

‎docs/_docs/04-upgrading.md

+1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ title: "Upgrading"
33
permalink: /docs/upgrading/
44
excerpt: "Instructions and suggestions for upgrading the theme."
55
last_modified_at: 2016-11-03T10:16:34-04:00
6+
toc: true
67
---
78

89
If you're using the Ruby Gem version of the theme upgrading is fairly painless.

‎docs/_docs/05-configuration.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,12 @@
22
title: "Configuration"
33
permalink: /docs/configuration/
44
excerpt: "Settings for configuring and customizing the theme."
5-
last_modified_at: 2017-10-04T16:31:28-04:00
5+
last_modified_at: 2017-10-20T12:34:20-04:00
6+
toc: true
67
---
78

89
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.
910

10-
{% include toc %}
11-
1211
**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.
1312
{: .notice--warning}
1413

‎docs/_docs/07-navigation.md

+1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ title: "Navigation"
33
permalink: /docs/navigation/
44
excerpt: "Instructions on how to customize the main navigation and enabling breadcrumb links."
55
last_modified_at: 2016-11-03T10:50:03-04:00
6+
toc: true
67
---
78

89
## Masthead

‎docs/_docs/10-layouts.md

+26-3
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,12 @@ single_layout_gallery:
77
alt: "single layout with header example"
88
- image_path: /assets/images/mm-layout-single-meta.png
99
alt: "single layout with comments and related posts"
10-
last_modified_at: 2017-07-05T15:41:36-04:00
10+
last_modified_at: 2017-10-20T14:26:10-04:00
11+
toc: true
12+
toc_label: "Included Layouts"
13+
toc_icon: "columns"
1114
---
1215

13-
{% include toc icon="columns" title="Included Layouts" %}
14-
1516
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.
1617

1718
## Default Layout
@@ -83,6 +84,28 @@ The layout you'll likely use the most --- sidebar and main content combo.
8384

8485
Assign with `layout: single`, or better yet apply as a [Front Matter default]({{ "/docs/configuration/#front-matter-defaults" | absolute_url }}) in `_config.yml`.
8586

87+
### Table of Contents
88+
89+
Auto-generated table of contents list for your posts and pages can be enabled by adding `toc: true` to the YAML Front Matter.
90+
91+
![table of contents example]({{ "/assets/images/mm-toc-helper-example.jpg" | absolute_url }})
92+
93+
| Parameter | Required | Description | Default |
94+
| --------- | -------- | ----------- | ------- |
95+
| **toc** | Optional | Show table of contents. (boolean) | `false` |
96+
| **toc_label** | Optional | Table of contents title. (string) | `toc_label` in UI Text data file. |
97+
| **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. |
98+
99+
**TOC example with custom title and icon**
100+
101+
```yaml
102+
---
103+
toc: true
104+
toc_label: "My Table of Contents"
105+
toc_icon: "gear"
106+
---
107+
```
108+
86109
## Archive Layout
87110

88111
Essentially the same as `single` with markup adjustments and some modules removed.

‎docs/_docs/14-helpers.md

+41-7
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,12 @@ feature_row:
3030
- image_path: /assets/images/unsplash-gallery-image-3-th.jpg
3131
title: "Placeholder 3"
3232
excerpt: "This is some sample content that goes here with **Markdown** formatting."
33-
last_modified_at: 2017-05-16T11:45:00-04:00
33+
last_modified_at: 2017-10-20T14:20:36-04:00
34+
toc: true
35+
toc_label: "Helpers"
36+
toc_icon: "gears"
3437
---
3538

36-
{% include toc icon="gears" title="Helpers" %}
37-
3839
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.
3940

4041
## Base Path
@@ -238,18 +239,51 @@ header:
238239

239240
## Table of Contents
240241

241-
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.
242+
Auto-generated table of contents list for your posts and pages can be enabled using two methods.
243+
244+
![table of contents example]({{ "/assets/images/mm-toc-helper-example.jpg" | absolute_url }})
245+
246+
### Enabled via YAML Front Matter
247+
248+
Add `toc: true` to the YAML Front Matter of any post or page.
249+
250+
| Parameter | Required | Description | Default |
251+
| --------- | -------- | ----------- | ------- |
252+
| **toc** | Optional | Show table of contents. (boolean) | `false` |
253+
| **toc_label** | Optional | Table of contents title. (string) | `toc_label` in UI Text data file. |
254+
| **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. |
255+
256+
**TOC example with custom title and icon**
257+
258+
```yaml
259+
---
260+
toc: true
261+
toc_label: "My Table of Contents"
262+
toc_icon: "gear"
263+
---
264+
```
265+
266+
**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`.
267+
{: .notice--warning }
268+
269+
### Enabled via `toc` include (deprecated)
270+
271+
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.
242272

243273
```liquid
244274
{% raw %}{% include toc %}{% endraw %}
245275
```
246276

247-
![table of contents example]({{ "/assets/images/mm-toc-helper-example.jpg" | absolute_url }})
277+
**Note:** this method only works with Markdown files.
278+
{: .notice--warning}
279+
280+
**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.
281+
{: .notice--danger}
248282

249283
| Parameter | Required | Description | Default |
250284
| --------- | -------- | ----------- | ------- |
251-
| **title** | Optional | Table of contents title. | `toc_label` in UI Text data file. |
252-
| **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. |
285+
| **title** | Optional | Table of contents title. (string) | `toc_label` in UI Text data file. |
286+
| **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. |
253287

254288
**TOC example with custom title and icon**
255289

‎docs/_docs/15-utility-classes.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@
22
title: "Utility Classes"
33
permalink: /docs/utility-classes/
44
excerpt: "CSS classes for aligning text/image, styling buttons and notices, and more."
5-
last_modified_at: 2017-09-01T11:54:44-04:00
5+
last_modified_at: 2017-10-20T12:36:34-04:00
6+
toc: true
7+
toc_label: "Utility Classes"
8+
toc_icon: "gears"
69
---
710

8-
{% include toc icon="gears" title="Utility Classes" %}
9-
1011
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.
1112

1213
**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

+3-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ permalink: /docs/history/
44
excerpt: "Change log of enhancements and bug fixes made to the theme."
55
sidebar:
66
nav: docs
7-
last_modified_at: 2017-10-16T12:40:54-04:00
7+
last_modified_at: 2017-10-20T14:22:30-04:00
8+
toc: true
89
---
910

1011
## Unreleased
@@ -20,6 +21,7 @@ last_modified_at: 2017-10-16T12:40:54-04:00
2021
- Add Naver Webmaster Tools verification. [#1286](https://github.com/mmistakes/minimal-mistakes/pull/1286)
2122
- Add support for Staticman v2 endpoint and reCAPTCHA.
2223
- Add Polish localized UI text strings. [#1304](https://github.com/mmistakes/minimal-mistakes/pull/1304)
24+
- 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)
2325

2426
### Bug Fixes
2527

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

+2-3
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,10 @@
22
title: "2.2 Documentation"
33
permalink: /docs/docs-2-2/
44
excerpt: "Setup and installation instructions for Minimal Mistakes 2.2 (deprecated)."
5-
last_modified_at: 2016-04-13T15:54:02-04:00
5+
last_modified_at: 2017-10-20T12:37:11-04:00
6+
toc: true
67
---
78

8-
{% include toc %}
9-
109
## Installation
1110

1211
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

+6-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: "License"
33
permalink: /docs/license/
44
excerpt: "License for Minimal Mistakes Jekyll Theme."
5-
last_modified_at: 2017-10-16T15:51:24-04:00
5+
last_modified_at: 2017-10-20T14:44:38-04:00
66
---
77

88
The MIT License (MIT)
@@ -63,4 +63,8 @@ GreedyNav.js is distributed under the terms of the [MIT License](http://opensour
6363

6464
Minimal Mistakes incorporates [Jekyll Group-By-Array](https://github.com/mushishi78/jekyll-group-by-array),
6565
Copyright (c) 2015 Max White <[email protected]>.
66-
Jekyll Group-By-Array is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).
66+
Jekyll Group-By-Array is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).
67+
68+
Minimal Mistakes incorporates [@allejo's Pure Liquid Jekyll Table of Contents](https://allejo.io/blog/a-jekyll-toc-in-liquid-only/),
69+
Copyright (c) 2017 Vladimir Jimenez.
70+
Pure Liquid Jekyll Table of Contents is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT).

0 commit comments

Comments
 (0)