How to add a Table of Contents to the side bar (in default.html)

89 views
Skip to first unread message

jane...@gmail.com

unread,
Nov 20, 2019, 2:29:01 PM11/20/19
to nanoc
Hello,

I am trying to create a static documentation site using Nanoc + Kramdown  in gitlab.  I have the default template from here:  https://gitlab.com/pages/nanoc.
Our documentation can be a bit long where I work, so rather than scrolling down through the page, I would like page navigation to be in the sidebar, rather than inline in the document the way it is working now.  (after I get this working, my plan is to make the sidebar floating, so it is always on the page and doesn't scroll away...but that is an iteration for another day.)



My ultimate goal is to change the default.html sidebar section to include page navigation that is generated by kramdown, but I cannot get the code to render.  What is your best advice for how to make this work?



You can see my test project here if you would like to see all the files and the output I see:  
(I have uploaded my project from my onprem gitlab where you would not have had access)



details:


My default.html looks like this:

<!DOCTYPE HTML>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>A Brand New Nanoc Site - <%= @item[:title] %></title>
    <link rel="stylesheet" href="stylesheet.css">

    <!-- you don't need to keep this, but it's cool for stats! -->
    <meta name="generator" content="Nanoc <%= Nanoc::VERSION %>">
  </head>
  <body>
    <div id="main">
      <%= yield %>
    </div>
    <div id="sidebar">

      <%= render '/toc.*' %>

    </div>
  </body>
</html>

my toc.md looks like this:

---
description: Table of Contents
---

## On this page
{:.no_toc .hidden-md .hidden-lg}

- TOC
{:toc .hidden-md .hidden-lg}


(Note:  this md code works fine in my index.md file when it is rendered.)





Denis Defreyne

unread,
Dec 26, 2019, 5:25:27 AM12/26/19
to na...@googlegroups.com

Hello,

I realised I never responded to this — but hopefully better late than never!

The approach that the Nanoc web site uses is a placeholder in the layout. You can see {{TOC}} here:

This isn’t Mustache or Handlebars, but something that a filter can pick up. In the case of Nanoc’s web site, an add_toc filter:

Items are first laid out, and then the add_toc filter is applied:

I like this approach as it gives me flexibility to put the TOC where I want it to be, and gives me the flexibility to mark it up the way I would like.

(Bonus: The Nanoc web site has a second table of contents hierarchy: the documentation pages have a sidebar with a ToC that lists all documentation pages, not just the current page. The doc_toc helper (https://github.com/nanoc/nanoc.ws/blob/master/lib/helpers/toc.rb) is generating that one. Note that this also generates the {{TOC}} placeholder, for the currently-selected item.)

Hope this helps,

Denis

--
You received this message because you are subscribed to the Google Groups "nanoc" group.
To unsubscribe from this group and stop receiving emails from it, send an email to nanoc+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/nanoc/70c35eab-8e75-4b8a-bee0-05dd3273416e%40googlegroups.com.


--

Dave Everitt

unread,
Feb 8, 2020, 2:27:37 PM2/8/20
to nanoc
I just found out that Kramdown generates a TOC with the following:

- TOC
{:toc}

so worth knowing :-)

Tom Cloyd

unread,
Aug 2, 2020, 4:32:28 PM8/2/20
to nanoc
I just caught this. Agree - so worth knowing, and not at all obvious. I NEED this. Thanks for leaving a trail here so I could find it!

~ t.
Reply all
Reply to author
Forward
0 new messages