Add TOC

[tyeeman]

I'm still really enjoying hindsite! Up to now I haven't needed this feature but would it be not to hard to add an option (in config) that enables the Table Of Contents to be generated at the top of each file, say from Heading1 to Heading3, during the html generation?

I do a newsletter for a club and they like the TOC at the top.

[srackham]

Thanks for the feedback. My suggestion, regards a TOC, would be to generate the TOC dynamically with JavaScript. This is how the Hindsite documentation is generated (see https://srackham.github.io/hindsite/).

The Hindsite documentation is built using Hindsite. It's in the project docs directory and is built with the hindsite build docs command (see the project Makefile).

I used Rimu markup instead of Markdown for the written content because Rimu, among other things, generates H1, H2 and H3 IDs automatically. You can stick to Rimu's Markdown compatible subset if you want your source content to remain Markdown compatible. Just remember to use the .rmu extension to ensure Hindsite processes content files using Rimu.

[tyeeman]

Thanks. The thing is I have to send the newsletter via email also. I have hindsite set up currently with a nice web template but for email I have found a template using tables which is how they have to be in emails. I would like to now use that template with these new newsletters. I re-read your docs today but I'm still a little unclear where to put a new content folder in my site and use this new template with it. I'm sure it's super easy but please explain the easiest method.

So....if I have to email my newsletter also with a toc, would it be not too hard to say have a meta option of "toc:true/false" for any markdown file we need a toc for? I would add it for just these new newsletters. The old ones don't need it. Currently I tried this using Pandoc but it's a pain compared to just let Hindsite build the site in an instant.

[srackham]

Regards modifying the newsletter to accommodate a table layout: edit the newsletter layout.html template and embed the {{.body}} inside the HTML table.

Regards a TOC option, you could do this by conditionally including/excluding TOC specific template markup with a custom user configuration parameter (see https://srackham.github.io/hindsite/#configuration-parameters).

[tyeeman]

So let me get this straight -

1. In site/template/ add a config.toml file like this -

# TOML
[user]
toc: 
-   [**Introduction**](#introduction)
-   [**Membership Renewal**](#membership-renewal)
-   [**Upcoming Events**](#upcoming-events)
    -   [Picnic - Saturday June 6th 9am-3pm](#picnic---saturday-june-6th-9am-3pm)
-   [**More Events**](#more-events)

Then use .user.toc in my template where I want it to appear?

I used Pandoc again to generate that above toc.

Update - I tried creating the toc with Pandoc again by running Pandoc on my markdown file (input markdown, output markdown), then let Hindsite build. Hindsite converted the links just fine, but there is a problem. The links don't work. When Pandoc adds toc to a markdown file it does not add id's to the headings (#) so the browser can't jump there. When I run Pandoc on an html file though, it does add id's to each heading so the toc links work. So maybe I just have to stick to running my html file through Pandoc to get the proper toc links working. I doubt golang can do this automatically??

[srackham]

Customise the HTML templates. Start by looking at the Hindsite documentation site templates and the Hindsite built-in blog site templates (the Hindsite Reference explains how it all works):

• https://github.com/srackham/hindsite/tree/master/docs/template
• https://github.com/srackham/hindsite/tree/master/cmd/hindsite/builtin/blog/template

Hindsite uses Go templates (just like Hugo) so you will also need to be familiar with Go templating and HTML.

See also Introduction to Hugo Templating.