Feature proposal: Add support for TOC in markdown pages

[stevegeek]

This feature proposal is about adding support for autogenerated table of contents on pages that are from markdown docs.

Lookbook has support for splitting large pages into sections using tabs, but this adds an alternate sub-navigation option leveraging the existing support for TOCs in Redcarpet.

The proposal

Adding toc: true to the front matter of a Markdown page will render a TOC at the top of the page using Redcarpet::HTML_TOC renderer

Implementation

I used the existing MarkdownRenderer and page specs as a guide and extended to add a renderer for markdown TOCs and one that renders both the TOC and page content and merges them.

Why?

I'm currently moving a number of large documents into lookbook in our project and splitting them up into parts would be quite a bit of work. Allowing some useful navigation in the form of a TOC seems like a useful addition.

---

Thanks for all the work on lookbook, its invaluable to us now!

Let me know if this feature request is of interest and any suggestion for changes/improvements

[netlify]

✅ Deploy Preview for lookbook-docs canceled.

Name	Link
🔨 Latest commit	725c1c2
🔍 Latest deploy log	https://app.netlify.com/sites/lookbook-docs/deploys/64b99b35e7c3a500088cf6b3

[stevegeek]

Right, I see this won't work at the moment as the lookbook JS creates a popstate event handler and calls handleNavigation which seems to prevent the document from scrolling to the referenced element

Update: have a hacky solution to this, but its sidestepping Alpine.js basically. Will need to read up on Alpine to find a better solution

[allmarkedup]

Hey @stevegeek :) This sounds like a great addition and definitely one that will be useful to other people (including me!) as well I'm sure.

Life has been a bit crazy recently so I've not had much Lookbook time but I'll try to take a look at this in more detail as soon as I can - apologies if I am a little slow with replies etc in the meantime. And I'm sure I can help clean up the link/navigation handling too if you need a hand with that.

Making the markdown docs feature a bit more feature-rich and flexible is definitely something I think about a lot so it's great to get PR's to help move things in that direction, thank you 😊

[stevegeek]

@allmarkedup thanks, thats all ok, no rush! I got a solution working on the navigation that handles all the various situations I could throw at it but it seems hacky and surely is not properly utilising Alpine. Therefore if you do ever find any time then some help on that frontend part would be helpful!

[allmarkedup]

hey again @stevegeek - just wanted to let you know that I've pulled this down and have been playing with it and it's looking great :)

I'm just working on cleaning up the JS and a couple of other tweaks - when they are ready are you happy for me to append them to this PR?

[stevegeek]

@allmarkedup Yeah sure, that sounds great!