steffen/website
1
0
Fork 0
Code Actions Packages Releases Activity

Toggle table of contents via front matter (#1310)

Browse Source 
* 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
This commit is contained in:
Michael Rose
2017-10-20 14:54:06 -04:00
committed by GitHub
parent 4b2487722c
commit 866fb17d9e
29 changed files with 332 additions and 286 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/_docs/01-quick-start-guide.md
View File

@@ -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.

1
docs/_docs/03-installation.md
View File

@@ -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

1
docs/_docs/04-upgrading.md
View File

@@ -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.

5
docs/_docs/05-configuration.md
View File

@@ -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}

1
docs/_docs/07-navigation.md
View File

@@ -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

29
docs/_docs/10-layouts.md
View File

@@ -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.

48
docs/_docs/14-helpers.md
View File

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

7
docs/_docs/15-utility-classes.md
View File

@@ -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.

4
docs/_docs/18-history.md
View File

@@ -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

5
docs/_docs/20-docs-2-2.md
View File

@@ -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.

8
docs/_docs/21-license.md
View File

@@ -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).