TOC sidebar

[fwilson-603]

It would be great to have a sidebar containing the table of contents of a page when we wind up with pages with a lot of content. Generating a TOC in kramdown is pretty straightforward, but for the life of me, but setting things up in a sidebar (esp. a floating sidebar) is not supported in kramdown alone. So the TOC just sits up at the top of the document, where it's not super useful. It looks like both html/css or bootstrap (using scrollspy) have this functionality, but for the life of me, every tutorial I try for setting that up fails miserably.

[gadanidis]

To be honest, I'm not a big fan of floating sidebars or floating elements in general (I like the more minimal design where everything just stays in one place). We would also have to think about how to make it mobile friendly (sidebars don't work well on portrait displays). An alternate option would be to have a back-to-top-of-page link after each major section heading, so that the TOC is easily accessible and you can jump back up to it instead of scrolling back manually. This would be possible using JS.

If we do want to do a floating sidebar, it should totally be possible with CSS though. We would want to create a new CSS file defining how the sidebar looks (in a new /css folder) and then reference it in a new layout file (e.g., toc-page in a /_layouts folder, copying in this HTML file and referencing the CSS file from it).

[fwilson-603]

Back-to-top links seem like they would solve the problem elegantly. The potential mobile-friendliness issue had occurred to me, but I couldn't picture an alternative.

On a related note, have you bumped into any guides/documentation on how to use other coding languages within markdown files? It seems like "use css/js/bootstrap" is the prototypical response to any issue markdown isn't equipped for out of the box, but all discussion thereof assumes you already know how to incorporate the different code :/

[gadanidis]

You can't really use other languages within markdown since the markdown files are meant to just be for content (not for advanced layout stuff like navigation bars etc.). The style information is specified in layout files which are written in HTML. For example, this is what's in the default 'page' layout:

---
layout: default
---
<article class="post">

  <header class="post-header">
    <h1 class="post-title">{{ page.title | escape }}</h1>
  </header>

  <div class="post-content">
    {{ content }}
  </div>

</article>

When you make a markdown file and tell it to use the 'page' layout, Jekyll outputs an html file containing the text above, with the markdown content (converted to HTML) appearing where the {{ content }} tag is. So to do JS or CSS stuff that you want on every page that uses the 'page' layout (e.g., changing the background colour, adding back-to-top links, etc.) you can put them into that layout file.

If you want to use custom JS or CSS on just one page within the 'content' section, rather than in a layout file, you can actually write the page in HTML instead, still specifying the front matter as normal — test.html:

---
layout: page
title: Test
permalink: /test/
---

<em>Hello</em>

This inserts the italicized 'Hello' text into where the {{ content }} block is in the 'page' layout. Because the file is written directly in HTML rather than markdown converted to HTML, you can now add <script> and <style> tags to load JS or CSS to do stuff you want.

[fwilson-603]

Thanks for the previous comment btw. I forgot to reply, but it helps to clarify how things work.