{"action":"created","issue":{"url":"https://api.github.com/repos/isaacs/github/issues/215","repository_url":"https://api.github.com/repos/isaacs/github","labels_url":"https://api.github.com/repos/isaacs/github/issues/215/labels{/name}","comments_url":"https://api.github.com/repos/isaacs/github/issues/215/comments","events_url":"https://api.github.com/repos/isaacs/github/issues/215/events","html_url":"https://github.com/isaacs/github/issues/215","id":36227252,"number":215,"title":"Insert automatically generated table of contents TOC on rendered markdown files like README.md.","user":{"login":"cirosantilli","id":1429315,"avatar_url":"https://avatars.githubusercontent.com/u/1429315?v=3","gravatar_id":"","url":"https://api.github.com/users/cirosantilli","html_url":"https://github.com/cirosantilli","followers_url":"https://api.github.com/users/cirosantilli/followers","following_url":"https://api.github.com/users/cirosantilli/following{/other_user}","gists_url":"https://api.github.com/users/cirosantilli/gists{/gist_id}","starred_url":"https://api.github.com/users/cirosantilli/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cirosantilli/subscriptions","organizations_url":"https://api.github.com/users/cirosantilli/orgs","repos_url":"https://api.github.com/users/cirosantilli/repos","events_url":"https://api.github.com/users/cirosantilli/events{/privacy}","received_events_url":"https://api.github.com/users/cirosantilli/received_events","type":"User","site_admin":false},"labels":[{"id":42220796,"url":"https://api.github.com/repos/isaacs/github/labels/enhancement","name":"enhancement","color":"84b6eb","default":true},{"id":263964091,"url":"https://api.github.com/repos/isaacs/github/labels/markdown","name":"markdown","color":"d4c5f9","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":333,"created_at":"2014-06-21T16:34:27Z","updated_at":"2017-02-23T03:13:27Z","closed_at":null,"body":"When I see a manually generated table of contents, it makes me sad.\n\nWhen I see a huge README that is impossible to navigate without it, it makes me even sadder.\n\nLaTeX has it. Gollum has it. Pandoc has it. So why not GFM?\n\nThere are some tools that automate the generation, but they're just an ugly hack:\n- require a Make before pushes\n- add output to version control\n- modify our dear source code for us\n\nNow the bitter part: what syntax to use?\n\nWhatever is chosen, it should be a standard way to extend Markdown, so that other extensions can be added later on.\n\nOne possibility is to use Kramdown extension syntax and insert the TOC with `{:toc max_level=3 }`.\n\nRedcarpet already has a command that generates the TOC: `Redcarpet::Render::HTML_TOC`, but no way to insert it, and no standard way to extend markdown.\n\nSame for GitLab: http://feedback.gitlab.com/forums/176466-general/suggestions/5790538-extension-for-inserting-a-table-of-contents-toc\n\nStackOverflow: 66 upvotes as of 2014-06: http://stackoverflow.com/questions/9721944/automatic-toc-in-github-flavoured-markdown\n\nThere is an issue for the library GitHub uses to render markdown at: https://github.com/github/markup/issues/904\n\n---\n\n[Steven! Ragnarök](https://github.com/nuclearsandwich) replied with the neutral:\n\n> Thanks for the suggestion and links. I'll add it to our internal feature request list for the team to see.\n"},"comment":{"url":"https://api.github.com/repos/isaacs/github/issues/comments/281881051","html_url":"https://github.com/isaacs/github/issues/215#issuecomment-281881051","issue_url":"https://api.github.com/repos/isaacs/github/issues/215","id":281881051,"user":{"login":"jhabdas","id":440298,"avatar_url":"https://avatars.githubusercontent.com/u/440298?v=3","gravatar_id":"","url":"https://api.github.com/users/jhabdas","html_url":"https://github.com/jhabdas","followers_url":"https://api.github.com/users/jhabdas/followers","following_url":"https://api.github.com/users/jhabdas/following{/other_user}","gists_url":"https://api.github.com/users/jhabdas/gists{/gist_id}","starred_url":"https://api.github.com/users/jhabdas/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jhabdas/subscriptions","organizations_url":"https://api.github.com/users/jhabdas/orgs","repos_url":"https://api.github.com/users/jhabdas/repos","events_url":"https://api.github.com/users/jhabdas/events{/privacy}","received_events_url":"https://api.github.com/users/jhabdas/received_events","type":"User","site_admin":false},"created_at":"2017-02-23T03:13:27Z","updated_at":"2017-02-23T03:13:27Z","body":"Downvoted yesterday while offering a path forward to those who might land here and become frustrated this is still open like @AzizSaleh. That said, the real problem here seems more so to do with standardization than of semantics. And the more we press a technology to do things it wasn't designed to do the less interoperable it will likely become.\r\n\r\nFor example, when I go to StackOverflow these days my fenced code blocks (non-standard) look terrible, forcing me to relearn SO's particular syntactical desires, which seem to be changing.\r\n\r\nFWIW Markdown is beautiful because it solves a complex problem in a simple way, which clearly sets the boundaries for what it is and is not capable of (such as producing a TOC) and makes it incredibly fast and interoperable. Take that away and we'll have markdown soup. I already can't use Kramdown block attributes in my other processors, nice as they are, so I'm rather glad Hugo, for example, chose to solve this problem outside the proverbial \"kernel\"."}}
{"actor":{"display_login":"jhabdas"}}