3 ms·
I like how the project name is formatted as code. It's missing a TOC though, scrolling through it doesn't give an overview what it contains.
by Sujan 9y ago
I like how the project name is formatted as code.
It's missing a TOC though, scrolling through it doesn't give an overview what it contains.
- voltagex_ 9y agoIs there an easy way to generate a TOC from an existing Markdown file?
- Sujan 9y agoDepends on where you are rendering the Markdown. In Jekyll with kramdown you can use {.toc} to get an automatically generated table of contents. On Github this doesn't exist, so you have to use an external tool like https://ecotrust-canada.github.io/markdown-toc/ https://ecotrust-canada.github.io/markdown-toc/ (Google "markdown generate TOC" for alternatives)
- jehna1 9y agoDocuments like README have a tendency of getting out of date really quickly — especially if you add dependencies between different content inside the file. I think anyone using Confluence (or similar wiki-style space) can agree. Including table of contents in your README is pretty big overhead if you cannot generate it automatically. This template is meant to be a good starting point for any size of project, so it was a conscious decision to leave table of contents out of it.
- Sujan 9y agoI actually replied to the wrong top comment here, this was meant for https://news.ycombinator.com/item?id=15561356 https://news.ycombinator.com/item?id=15561356. This links to https://github.com/mcohen01/amazonica https://github.com/mcohen01/amazonica which is 25 pages printed - and then you definitely should have a TOC just to be able to learn what the content is all about. If you are doing TOC manually in Confluence you are doing it wrong by the way: Both TOC or links to subpages can be done automatically.