Anchors vs no anchors

[tyeeman]

Thanks for writing this. I spent hours trying to find some script to do this. No one seems to explain about requiring anchors, when and where. I just wanted to add a toc to my newsletter on the web, and without anchors I could not get anything to work. I got Pandoc to work if I converted my .md to .html but I could not get Pandoc to add anchors to my .md file. Please confirm anchors are required for a static site web page sitting anywhere??

[derlin]

Hello there! Glad you found it helpful. Yes, a table of contents needs anchors to work. Have a look at my article here https://blog.derlin.ch/add-a-table-of-contents-to-devto-articles#heading-how-do-tocs-work which better explains the whole process.

Essentially, you need either a link with a name (old browsers) or an ID (html5 compatible with modern browsers) that you can then reference in your TOC using a fragment link:

<!-- for old browser ... --->
<a name="section1">Section 1</a>
<!-- ... or for modern browser supporting HTML5 -->
<h2 id="section1">Section 1</h2>

Note that bitdowntoc can generate those anchors for you: use the bitbucket server profile, or ensure you check the "generate anchors" in "options". I suggest you try this and see if it works after pandoc conversion!

[tyeeman]

How can I get "ID (html5 compatible with modern browsers)"? I'm using the command line version in Windows and it's working well but I can't find a way to use "ID" for modern browsers??

[derlin]

Hello again! Just to clarify: bitdowntoc doesn't "get id's" : either they are generated by your markdown renderer (github, etc) or you ask bitdowntoc to generate them and in this case bitdowntoc uses the old way, which is currently supported my all browsers.

Can you tell me more about your use case? Aren't the old anchors working?

[tyeeman]

Yes, the old anchors are working fine. Just wondering if one day browsers won't support the old way, then I guess you will update bitdowntoc.

[derlin]

Exactly 😊