Hacker News Reader

Comment by jasoneckert | Hacker News Reader

These features are all sage advice for any blog in my opinion, and this blog is a good example of one that is easy to follow as a result.

Regarding the Table of Contents feature, however, I believe this makes a big difference in larger blogs, but for medium sized or smaller blogs, it can be a distractor. I use Hugo as well for compositing my site, and find that using ample first level headings (e.g., # Heading name) for major components alongside a solid flow that contains visual graphics placed shortly after the heading offers an attractive and easy-to-navigate browsing experience.

View on HN

> Regarding the Table of Contents feature, however, I believe this makes a big difference in larger blogs, but for medium sized or smaller blogs, it can be a distractor.

Ah. That resonates. Thank you for breaking it down like that. I've pondered adding ToC, but now realize it's only for a small subset of pages that it adds value, rather than distracts.

Tables of contents are tricky. My publishing logic is rather flexible in how I use them, so I used to put them into the margins of longer articles[1] and sometimes even shorter ones[2] although I wasn't great at always remembering to do it[3].

But the problem for me is that good headlines, that give a fair summary of the section they are for, make for really wide tables of contents which don't fit neatly into the margins[4], so sometimes the table of content has to occupy space in the main section[5] which seems to me like it distracts a bit from the actual content.

[1]: https://two-wrongs.com/markov-chains-for-queueing-systems.ht...

[2]: https://two-wrongs.com/verifiable-software-development-estim...

[3]: https://two-wrongs.com/event-sourcing-and-microservices-unix...

[4]: https://two-wrongs.com/word-embeddings-in-perl.html

[5]: https://two-wrongs.com/what-is-probability.html

A ToC might be more distracting with a style that benefits less from a clear structure, like a personal essay. It can be important in a more technical-procedural style of writing, though.

Doing a direct mapping from Markdown Headings to Table of contents+Anchors via Eleventy [1] is what I went with for my blog [2], simple setup, works perfectly.

[1] https://github.com/FrostKiwi/treasurechest/blob/4d96694a912e...

[2] https://blog.frost.kiwi

I think Notion has nailed it with the new design of their table of contents [1]. The problem with the current general approach is that if a blog post is very long and you are in the middle of it, you might forget what the content was. However, having a very small item on the right that you can quickly peek at is awesome.

[1] Example https://www.notion.so/notion/Table-of-contents-50de58f824bf4...

Reply on news.ycombinator.com