The granularity of blocks allows us to zoom in and filter out anything that’s irrelevant at the moment. But sometimes, you want to zoom all the way out and get a clear overview of a page’s contents.
Unless you create one manually, it’s impossible to easily add a table of contents to pages. That is, until you install Luis Thiam-Nye‘s roam-toc plugin. By creating a simple template, you can now easily add an always-up-to-date table of contents to your pages.
In this walkthrough I’ll show you how to set up and use this plugin. Prefer video? Scroll to the end of the page and I’ll teach you everything in 6 minutes.
Downloading and installing the plugin
Step 1—Enable user code.
From the Settings menu, make sure the User code option is enabled (slider is blue):
Step 2—Add the plugin code to your graph.
Copy the toc.cljs code from Luis’ Github page.
Next, go to the page roam/render in your graph (create if it doesn’t exist yet) and add a new parent block named Roam-TOC (not mandatory on this page, but useful for organization).
Then, create a child block, type /clojure and hit Enter. This creates a Clojure code block (the language Roam is written in).
Finally, paste the code you copied from Github into the code block:
Setting up the template
To make it effortless adding a table of contents to a page, we’ll set up a template to save ourselves some typing.
Step 1—Copy block ref of code block.
Before we go off and create our template, we need the block reference ID of the code block we’ve just created and filled.
Right-Click the bullet of the code block and copy the block reference:
Step 2—Create the template trigger.
Go to your roam/templates page (create if it doesn’t exist yet) and create a new parent block titled Add Table of Contents (TOC). This will be the trigger to quickly add a table of contents to a page.
Step 3—Add code to template.
Nested underneath the parent block you just created, add the following code: {{[[roam/render]]: }}
After the parenthesis, paste the block ref you just copied:
Using the template on pages
Now on to the fun part! Let’s add a table of contents to a page.
Step 1—Navigate to a page with headers.
The plugin works by scanning the page for any blocks that are headers. So, make sure you’re on a page that at least contains one H1, H2, or H3.
Step 2—Use the template in an empty block.
Now, from any empty block on the page (doesn’t have to be the top block), call the template by typing ;;toc:
Next, hit Enter and click away from the block to render the table of contents:
Step 3—Click to scroll.
That’s it! You now have an always-up-to-date table of contents of that page. Clicking a heading in the table of contents will take you to that position on the page.
Learn this process via video
Prefer video to learn? In this 6-minute video I take you through all the steps:
Join the conversation.