New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Toggle table of contents via front matter #1222

Closed
vahid-dan opened this Issue Sep 4, 2017 · 9 comments

Comments

Projects
None yet
4 participants
@vahid-dan

vahid-dan commented Sep 4, 2017

  • 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

This comment has been minimized.

Show comment
Hide comment
@mmistakes

mmistakes Sep 4, 2017

Owner

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.

Owner

mmistakes commented Sep 4, 2017

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

This comment has been minimized.

Show comment
Hide comment
@allejo

allejo Sep 20, 2017

Contributor

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.

Contributor

allejo commented Sep 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@mmistakes

mmistakes Sep 20, 2017

Owner

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.

Owner

mmistakes commented Sep 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@allejo

allejo Sep 20, 2017

Contributor

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.

Contributor

allejo commented Sep 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@mmistakes

mmistakes Sep 20, 2017

Owner

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

Owner

mmistakes commented Sep 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@allejo

allejo Sep 20, 2017

Contributor

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

Contributor

allejo commented Sep 20, 2017

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

@mmistakes

This comment has been minimized.

Show comment
Hide comment
@mmistakes

mmistakes Sep 20, 2017

Owner

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.

Owner

mmistakes commented Sep 20, 2017

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.

@mmistakes mmistakes reopened this Sep 20, 2017

@mmistakes mmistakes changed the title from Automatically Adding Table of Contents to a Layout to Toggle table of contents via front matter Sep 20, 2017

@mmistakes mmistakes closed this in 866fb17 Oct 20, 2017

@mmistakes

This comment has been minimized.

Show comment
Hide comment
@mmistakes

mmistakes Oct 20, 2017

Owner

This feature has been added to the theme. Haven't pushed a new theme gem version yet, but the updates are all on master if you're using the fork method.

I've kept the old Kramdown based method in for now, but plan on removing that in the next version. To enable table of contents on pages using the single layout simply add toc: true to the front matter.

The icon and label title can both be changed per page just like with the old version.

---
toc: true
toc_label: "My Custom Table of Contents Label"
toc_icon: "gear"
---

TOC's can also be set globally for entire section of pages/posts using Front Matter defaults in _config.yml.

Owner

mmistakes commented Oct 20, 2017

This feature has been added to the theme. Haven't pushed a new theme gem version yet, but the updates are all on master if you're using the fork method.

I've kept the old Kramdown based method in for now, but plan on removing that in the next version. To enable table of contents on pages using the single layout simply add toc: true to the front matter.

The icon and label title can both be changed per page just like with the old version.

---
toc: true
toc_label: "My Custom Table of Contents Label"
toc_icon: "gear"
---

TOC's can also be set globally for entire section of pages/posts using Front Matter defaults in _config.yml.

@Bobinio

This comment has been minimized.

Show comment
Hide comment
@Bobinio

Bobinio May 5, 2018

Hopefully someone can assist...
I can generate the Table of Contents for a page which seems to pick up H2 tags etc.
This Table of content appears in the right column as expected. However, when I click on a link in the Table of contents nothing happens. In the source code it shows the href="#" for each link.
Obviously, this is no good. I expected it to create and use a name tag somehow and so make these clickable links useful.
What am I missing?
Many thanks.

Bobinio commented May 5, 2018

Hopefully someone can assist...
I can generate the Table of Contents for a page which seems to pick up H2 tags etc.
This Table of content appears in the right column as expected. However, when I click on a link in the Table of contents nothing happens. In the source code it shows the href="#" for each link.
Obviously, this is no good. I expected it to create and use a name tag somehow and so make these clickable links useful.
What am I missing?
Many thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment