page toc does not work in shortcodes.

[shalzz]

Bug Report

The page.toc Array is empty when used in a shortcode but works in a template.

Environment

Linux

Zola version: 0.5.1

Expected Behavior

page.toc should not be empty inside a shortcode.

Current Behavior

page.toc is empty when used in a shortcode

Step to reproduce

• Create a shortcode with the html described here: https://www.getzola.org/documentation/content/table-of-contents/
• Use the shortcode in a markdown file in the content directory.

[Keats]

Shortcodes are rendered before the markdown is parsed so the toc isn't available yet.

[shalzz]

Is this something that can be added in a later version? Having the TOC generated by the template is not ideal since the position is always fixed whereas with a shortcode we can have content (introduction, updates, etc) before the TOC as well.
Perhaps this can be achieved by the markdown parser itself? Jekyll's kramdown has a tag {:toc} that automatically generates the toc.

[Keats]

Having it in a shortcode is unlikely to happen right now, it would require going through the markdown parser twice.
For the {:toc}, how can define a template to use for rendering in jekyll?

[shalzz]

The {:toc} is used like here: https://github.com/shalzz/shalzz.github.io/blob/jekyll/_posts/2019-01-12-vlc-dlna-support-2.md#content
The Jekyll templates themselves are defined in _layouts

[phil-opp]

You can work around this issue by using the replace filter in the template:

{{ page.content | safe | replace(from="<!-- toc -->", to=macros::toc(page=page))}}

Now you can put <!-- toc --> in the document where you want the table of contents.

[shalzz]

@phil-opp Thanks, that's a nice workaround.

[shalzz]

It seems the workaround is broken with zola v0.6.0
Zola seems to compile all macros before compiling the page template which is why I cannot find the page.toc variable
Here's the error I get:

Failed to build the site
Error: Failed to render page '/home/shalzz/dev/shalzz.github.io/content/blog/switching-blog-to-zola.md'
Reason: Failed to render 'butler/templates/page.html': error while rendering macro `macros::toc`
Reason: Variable `page.toc` not found in context while rendering 'butler/templates/macros.html'

[Keats]

The toc is now a root variable of the page context, not under page.toc.

From the changelog:

The table of content for a page/section is now only available as the toc variable when rendering it and not anymore on the page/section variable

[phil-opp]

@Keats Could you update this in the documentation at https://www.getzola.org/documentation/content/table-of-contents/?

[Keats]

Done, sorry about that!

[phil-opp]

That was quick, thanks!

[Keats]

@shalzz can this be closed?

[shalzz]

@Keats This still doesn't work with shortcodes so If you want to accept the workaround as a solution then sure, we can close this but this might need to be mentioned in the docs as yet another caveat, with a brief of the workaround?

[Keats]

let's update the docs, I don't believe the toc will be coming to shortcodes anytime soon.

[shalzz]

OK, closing issue.

[c-git]

Sorry to reply to such an old issue but I cannot find it in the docs. Can you add a link to where it is in the docs please?

[Keats]

https://www.getzola.org/documentation/content/shortcodes/#writing-a-shortcode in the last paragraph

[c-git]

Thanks, I thought the workaround was somewhere in the docs and I'd missed it. Will look into the tera docs for more on macros.

On another but related note, I've been thinking that a list of examples would be useful. Like an example of how to do the various things in the documentation (so I guess this work around wouldn't be in that list). But basically somewhere people can go to get an example rather than just trying to read and apply the documentation. It's not difficult to apply what you find in the documentation to be fair but it's also not trivial and takes longer than working from an example. I'd be happy to contribute examples for the ones I've used if that would be helpful. Or maybe the examples could all be on one "site" and use a different page in the site for each example IDK what's the best way but I think it would be helpful.

[Keats]

I'm planning to rewrite the documentation almost entirely as part of 0.17, and there will be a "how to" section. Don't expect that anytime soon though.

[c-git]

It's far from urgent, no worries. Let me know if I can help in that regard. I'm not the best at writing docs for things I understand (usually takes more effort because I forget what I didn't know when I started) but still pretty new to zola so hopefully I should be able to help. If possible try to include code snippets, I've realized the value in them over time. They really make the overview concrete and easy to test that you can get it to work so you can modify to see what effect it will have.

[c-git]

I'm planning to rewrite the documentation almost entirely as part of 0.17, and there will be a "how to" section. Don't expect that anytime soon though.

Do you have somewhere you are documenting things to modify during the rewrite?

I just remembered I wanted to make a pull request to update the documentation for resize_image as I had some issues when I started using it that were not captured in the documentation. I can look up the details if that's helpful, don't remember them off hand. As well as the documentation regarding setting up automated builds on github (it was something to do with secrets, based on my notes that I just saw).

[Keats]

Do you have somewhere you are documenting things to modify during the rewrite?

Not really, I'm hoping people will contribute to the "how to" section.

Please do send PR for documentation changes now, 0.17 is not happening anytime soon.

[c-git]

Ok thanks I'll leave it on my list of things to do. Want to write it up and make sure it's clear so I'll do it when I have a bit more time. And I'd be very happy to contribute to the how-to section

[mwcz]

You can work around this issue by using the replace filter in the template:

{{ page.content | safe | replace(from="<!-- toc -->", to=macros::toc(page=page))}}

Now you can put <!-- toc --> in the document where you want the table of contents.

This helped a lot, thank you. Instead of putting <!-- toc --> in my posts, I kept a {{ toc() }} shortcode which only outputs <!-- toc -->. Works like a charm.