DEV Community

Finally a clean and easy way to add Table of Contents to dev.to articles 🤩

Lucy Linder on January 02, 2023

Contrary to other platforms, dev.to doesn't have built-in support for Table of Contents (TOCs). Many articles describe tricks to generate TOCs, but...

Read full post

Michael Tharrington • Jan 2 '23

Rock on! Awesome work, Lucy! 🙌

This actually came up in discussion last week in @szabgab's post here:

View (Markdown) Source button on DEV

Gabor Szabo ・ Dec 30 '22 ・ 1 min read

#productivity #discuss #beginners #dev

The post is about more than just ToCs, but Gabor illustrates his point with an example saying it'd be cool to have the option to see the raw MD of a post to see how folks are creating interesting things in MD, like a ToC.

Anywho, it's just really cool to see this come to fruition a week after that convo. Really appreciate ya adding DEV support to this tool!

Lucy Linder • Jan 2 '23

Thanks for the kind words and the share !
Good timing indeed 😄 I am all for the "show source" button, it would be an awesome addition to dev.to. Markdown is so easy and yet so complex at times!

Lucy Linder • Jan 2 '23 • Edited

UPDATE: I just discovered dev.to DOES create anchors (GitLab style - with space concatenation). I just updated BitDownToc online and the article to match this finding!

Vincent A. Cicirello • Jan 2 '23

Cool approach to generating TOCs for DEV posts.

Your explanation of how to manually add a TOC on DEV isn't entirely correct. You don't actually need to create the anchors yourself. DEV automatically creates anchors for every section just like GitHub does in READMEs.

The anchor is formed by dropping any symbols from the section heading, lowercasing the section heading, and replacing spaces with dashes. For example, the following section heading:

## Section Heading + Hyphenated-Word

Will get an anchor by removing the + and -, lowercasing everything and replacing spaces with -. So you can link to it with:

[Link Text](#section-heading-hyphenatedword)

Lucy Linder • Jan 2 '23 • Edited

Yeah, I just saw... I feel stupid having missed that... I updated BitDownToc online to match this finding and changed part of the article, thank you !!

Vincent A. Cicirello • Jan 2 '23

No reason to feel stupid. It is more of an example of the importance of your TOC tool. It seems every site's markdown processor is a little different. Your TOC tool looks very useful especially because of that. With your tool, there is no reason to remember the differences in how anchors are formed. Very cool. Maybe there's a way to integrate it directly with DEV's editor.

Fabien Arcellier • Jan 3 '23

It's excellent. I love that it's idempotent and at any point in writing I can generate the table of contents again. Thank you :)

Serena • Aug 16 '23

Very useful and quick!! Thanks so much, I didn't think such a tool would exist :o

Benoit COUETIL 💫 • Mar 30 '23 • Edited

Thank you, very useful 🙏

May I suggest 2 things :

Adding a comment saying where it is generated, then I would not have to remember :

<!-- TOC generated with https://derlin.github.io/bitdowntoc/ -->

TOC start/end should be one empty line away from actual TOC, because IDEs like VSCode want to add one before TOC start and want to indent TOC end with last section, forcing me to edit before saving.

{%- # TOC start -%}

- [Introduction](#introduction)
  - [S3 specific outputs](#s3-specific-outputs)
- [Conclusion](#conclusion)

{%- # TOC end -%}

Lucy Linder • Mar 30 '23

Very good suggestions indeed! Can you create issues on github so I don't forget them? Thank you for your valuable input

Benoit COUETIL 💫 • Mar 30 '23

done 😊

zankyr • Feb 8 '23

Awesome!
I have always been very comfortable with the IntelliJ feature to generate a TOC: a simple key combination et voilà, the TOC is created.
But I realized that the format used is not understood by everyone : for example Visual Studio Code and dev.to do not digest very well the  tags generated by IJ (the closing tag is always displayed in the generated markdown).
Also, I found that some particular headers are not well managed. For example this anchor
[Delete all local branches not matching the provided name(s)](#delete-all-local-branches-not-matching-the-provided-name--s-) doesn't work in dev.to. The same anchor, generated by bitdowntoc, works just fine: [Delete all local branches not matching the provided name(s)](#delete-all-local-branches-not-matching-the-provided-names)

Lucy Linder • Feb 8 '23

So happy you liked it!
dev.to anchor generation is a mess... It took me a while to figure out how to reproduce the algorithm using Kotlin Multiplatform. I am planning on writing an article about it, stay tuned!

Ting • Mar 26 • Edited

Welp, I guess this is kind of a clickbait title. 🤷‍♂️ There have been many Markdown TOC tools available, and I only decide to give this a read because I thought dev.to is gonna support TOC natively, just like GitHub markdown. If I need to copy paste my content back and forth just to generate TOC, then I probably gonna mess up the formatting at some point.

Lucy Linder • Mar 27

Did you give bitdowntoc a try before writing this comment?

I would be interested in your advices to make the experience more streamlined. Currently you copy from dev.to, paste to bitdowntoc, click, click, paste again on dev.to. This makes it difficult to "mess up".

The only better approach would be a chrome extension integrating bitdowntoc, but I unfortunately don't have time for that right now.

Ting • Mar 27

Thanks for your response. I tried the tool and it works as explained. My complaint was only about the title "Finally a clean and easy way to add Table of Contents to dev.to articles" - I was hoping to see Dev.to adding this functionality natively, but apparently they don't bother doing this.
Using online editor might be easy for edit-what-you-see workflow, but when it comes to managing separately hosted images, copy-paste get a a bit tricky. Thus I hope they'll have a native TOC button online, or I have to stick to the local editor with plugin.

Lucy Linder • Mar 27

+1 for a built-in tool!