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

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