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

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)

Gitlab Repository: https://gitlab.com/janetpost/doctest-nanoc

Pages view: https://janetpost.gitlab.io/doctest-nanoc/

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:

https://github.com/nanoc/nanoc.ws/blob/master/layouts/default.html.erb

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:

https://github.com/nanoc/nanoc.ws/blob/master/lib/filters/add_toc.rb

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

https://github.com/nanoc/nanoc.ws/blob/master/Rules#L114-L116

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.

--

Denis Defreyne

+49 1573 1969 173

de...@denis.ws