3 ms·

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 o

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.

breck 2y ago
> 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.
kqr 2y ago
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.html https://two-wrongs.com/markov-chains-for-queueing-systems.ht... [2]: https://two-wrongs.com/verifiable-software-development-estimations.html https://two-wrongs.com/verifiable-software-development-estim... [3]: https://two-wrongs.com/event-sourcing-and-microservices-unix-style.html https://two-wrongs.com/event-sourcing-and-microservices-unix... [4]: https://two-wrongs.com/word-embeddings-in-perl.html https://two-wrongs.com/word-embeddings-in-perl.html [5]: https://two-wrongs.com/what-is-probability.html https://two-wrongs.com/what-is-probability.html
FrostKiwi 2y ago
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/4d96694a912ec89e632cd5fa64009fa7337e6c5d/.eleventy.js#L21 https://github.com/FrostKiwi/treasurechest/blob/4d96694a912e... [2] https://blog.frost.kiwi https://blog.frost.kiwi
arberavdullahu 2y ago
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-50de58f824bf4100a4a9fa5b6f783c2b https://www.notion.so/notion/Table-of-contents-50de58f824bf4...
jmbwell 2y ago
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.

breck 2y ago

> 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.

kqr 2y ago

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.html https://two-wrongs.com/markov-chains-for-queueing-systems.ht... [2]: https://two-wrongs.com/verifiable-software-development-estimations.html https://two-wrongs.com/verifiable-software-development-estim... [3]: https://two-wrongs.com/event-sourcing-and-microservices-unix-style.html https://two-wrongs.com/event-sourcing-and-microservices-unix... [4]: https://two-wrongs.com/word-embeddings-in-perl.html https://two-wrongs.com/word-embeddings-in-perl.html [5]: https://two-wrongs.com/what-is-probability.html https://two-wrongs.com/what-is-probability.html

FrostKiwi 2y ago

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/4d96694a912ec89e632cd5fa64009fa7337e6c5d/.eleventy.js#L21 https://github.com/FrostKiwi/treasurechest/blob/4d96694a912e... [2] https://blog.frost.kiwi https://blog.frost.kiwi

arberavdullahu 2y ago

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-50de58f824bf4100a4a9fa5b6f783c2b https://www.notion.so/notion/Table-of-contents-50de58f824bf4...

jmbwell 2y ago

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.