Toggle table of contents via front matter

[vahid-dan]

• This is a question about using the theme.
• This is a feature request.
• I believe this to be a bug with the theme.
  • I have updated all gems with bundle update.
  • I have tested locally with bundle exec jekyll build.

---

Environment information

• Minimal Mistakes version: 4.51
• Jekyll version: 3.5.2
• GitHub Pages hosted: yes
• Operating system: Ubuntu 16.04

---

Expected behavior

I have imported GitHub wiki pages as a submodule into the Jekyll website. Now I want to automatically add "Table of Contents" to every wiki page without having to add {% include toc %} manually to every page. Wiki pages inside the website are in the wiki directory and have wiki.html layout.

[mmistakes]

I don't think there is any way to do this. The {% include toc %} is a shortcut to print out {:toc} which is used by Kramdown to auto-generate the table of contents based on the headlines of your Markdown file.

{:toc} has to live inside of said Markdown file to be parsed when Kramdown does it thing. There's no way for me to bake this logic into a layout because of this.

There's probably a Jekyll plugin you could leverage to do it, but that wouldn't happen at the theme level.

[allejo]

Might I recommend a solution like this? https://github.com/allejo/jekyll-toc This'll take the generated HTML from the markdown and generate a TOC from that and can be used from inside a layout. It's also written in Liquid, so it's compatible with GH pages since it's not a plug-in and doesn't require JS.

[mmistakes]

Good solution @allejo, I've recommended it before for those who want some more flexibility over what Kramdown's auto TOC or JS solutions provide.

Do you have any stats around the impact of using this include across a ton of post's? Have to think with it looping over all the content to pull out the headings there'll be a hit in jekyll build time.

[allejo]

Haven't really done any extensive testing for stats. Got any suggestions for tests I should do? The only stat I have is for the Docker docs site (through --profile) where the include is being used 813 times at about ~6.5 seconds.

Edit: Just ran --profile again on the current Docker site and it's at ~8 seconds for 1182 hits.

[mmistakes]

--profile is the only one I'm really aware of too. A few seconds doesn't seem too bad. I've used some pure-Liquid methods to do some things related to pagination that completely killed a build and pushed it into minutes/hours territory.

I have a fairly large site myself, when I get a chance I'll give it a test just to compare against.

[allejo]

Oh sweet, I'd definitely be interested in seeing how it performs on your site 👍

[mmistakes]

Did some quick tests using the sample posts in this theme and I didn't really see any impact on build time.

_includes/toc.html                                  |    94 |   29.43K | 0.413

Which is very encouraging. Seems like a valid replacement to me. There's probably a few second hit on a site with hundreds/thousands of posts, but I'm cool with that.

@vahid-dan Looks like what you want to do is something I can bake into the theme. Thinking something like toc: true on a post/page would activate the Liquid TOC. And with YAML Front Matter defaults you could easily set it true for all your posts without having to had any garbage to your .md files.

If I ditch the Kramdown auto-generated TOC it frees me up to move it somewhere more semantic in the HTML layouts too.