New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Insert automatically generated table of contents TOC on rendered markdown files like README.md. #215

Open
cirosantilli opened this Issue Jun 21, 2014 · 392 comments

Comments

Projects
None yet
@cirosantilli
Collaborator

cirosantilli commented Jun 21, 2014

When I see a manually generated table of contents, it makes me sad.

When I see a huge README that is impossible to navigate without it, it makes me even sadder.

LaTeX has it. Gollum has it. Pandoc has it. So why not GFM?

There are some tools that automate the generation, but they're just an ugly hack:

  • require a Make before pushes
  • add output to version control
  • modify our dear source code for us

Now the bitter part: what syntax to use?

Whatever is chosen, it should be a standard way to extend Markdown, so that other extensions can be added later on.

One possibility is to use Kramdown extension syntax and insert the TOC with {:toc max_level=3 }.

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

Same for GitLab: http://feedback.gitlab.com/forums/176466-general/suggestions/5790538-extension-for-inserting-a-table-of-contents-toc

StackOverflow: 66 upvotes as of 2014-06: http://stackoverflow.com/questions/9721944/automatic-toc-in-github-flavoured-markdown

There is an issue for the library GitHub uses to render markdown at: github/markup#904

Steven! Ragnarök replied with the neutral:

Thanks for the suggestion and links. I'll add it to our internal feature request list for the team to see.

Asciidoc

I got tired of waiting and started using Asciidoc. I recommend it, the format is really good. Just look at the typographical beauty of this: https://github.com/cirosantilli/linux-kernel-module-cheat/blob/7d9102373d60bd159920abfe96d636420afedd67/README.adoc

@cirosantilli cirosantilli changed the title from Allow to insert a table of contents TOC on rendered markdown files like README.md. to Insert automatically generated table of contents TOC on rendered markdown files like README.md. Jun 21, 2014

@captn3m0

This comment has been minimized.

Show comment
Hide comment
@captn3m0

captn3m0 Jun 22, 2014

You can automatically generate TOC via http://doctoc.herokuapp.com/. There is also an npm package available here to do it on the command line.

But yes, these are ultimately just manual methods because you need to manually copy and paste the TOC into the markdown. But one benefit of it is that the toc is maintained everwhere, even across apps that don't use GFM for rendering.

captn3m0 commented Jun 22, 2014

You can automatically generate TOC via http://doctoc.herokuapp.com/. There is also an npm package available here to do it on the command line.

But yes, these are ultimately just manual methods because you need to manually copy and paste the TOC into the markdown. But one benefit of it is that the toc is maintained everwhere, even across apps that don't use GFM for rendering.

@cirosantilli

This comment has been minimized.

Show comment
Hide comment
@cirosantilli

cirosantilli Jun 22, 2014

Collaborator

I hope GitHub fix some standard extension syntax, possibly backing up Kramdown's, and potentially settle the existing extension mess with it's influence.

Collaborator

cirosantilli commented Jun 22, 2014

I hope GitHub fix some standard extension syntax, possibly backing up Kramdown's, and potentially settle the existing extension mess with it's influence.

@ekalinin

This comment has been minimized.

Show comment
Hide comment
@ekalinin

ekalinin Sep 2, 2014

Here's my try to solve this issue without any addional software (on linux) — github-markdown-toc

ekalinin commented Sep 2, 2014

Here's my try to solve this issue without any addional software (on linux) — github-markdown-toc

@quasipedia

This comment has been minimized.

Show comment
Hide comment
@quasipedia

quasipedia commented Oct 22, 2014

👍

@ezequielgarcia

This comment has been minimized.

Show comment
Hide comment
@ezequielgarcia

ezequielgarcia commented Dec 9, 2014

+1

@robbyoconnor

This comment has been minimized.

Show comment
Hide comment
@robbyoconnor

robbyoconnor commented Dec 16, 2014

+1

@maxlinc

This comment has been minimized.

Show comment
Hide comment
@maxlinc

maxlinc Dec 16, 2014

Another workaround...

Although I'd like to see TOC support in GFM, if you want TOC's rendered by GitHub today than you could switch to asciidoc. Asciidoc has built-in support for TOC, and with the right options it will be rendered by GitHub.

I'm a fan of Markdown so I'm hesitant to asciidoc, but the article on Living the Future of Technical Writing by GitHub's @schacon, which talks about switching from Markdown to Asciidoc, has made willing to consider the jump. There's also several other features other features in asciidoc-samples - besides TOC - that don't seem to have working GFM equivalents. Footnotes, for example.

If you want give asciidoc a shot, you can use pandoc to convert your existing markdown:

pandoc -t asciidoc -f markdown README.md > README.asciidoc

maxlinc commented Dec 16, 2014

Another workaround...

Although I'd like to see TOC support in GFM, if you want TOC's rendered by GitHub today than you could switch to asciidoc. Asciidoc has built-in support for TOC, and with the right options it will be rendered by GitHub.

I'm a fan of Markdown so I'm hesitant to asciidoc, but the article on Living the Future of Technical Writing by GitHub's @schacon, which talks about switching from Markdown to Asciidoc, has made willing to consider the jump. There's also several other features other features in asciidoc-samples - besides TOC - that don't seem to have working GFM equivalents. Footnotes, for example.

If you want give asciidoc a shot, you can use pandoc to convert your existing markdown:

pandoc -t asciidoc -f markdown README.md > README.asciidoc
@cirosantilli

This comment has been minimized.

Show comment
Hide comment
@cirosantilli

cirosantilli Dec 16, 2014

Collaborator

@maxlinc thanks a lot for the schacon link! I was really curious to why he used Asciidoc on Pro Git 2.

Collaborator

cirosantilli commented Dec 16, 2014

@maxlinc thanks a lot for the schacon link! I was really curious to why he used Asciidoc on Pro Git 2.

@quasipedia

This comment has been minimized.

Show comment
Hide comment
@quasipedia

quasipedia Dec 17, 2014

@maxlinc - I subscribe the thanksgiving by cirosantilli! 👍

quasipedia commented Dec 17, 2014

@maxlinc - I subscribe the thanksgiving by cirosantilli! 👍

@mikecharles

This comment has been minimized.

Show comment
Hide comment
@mikecharles

mikecharles Dec 17, 2014

@ekalinin I suppose this won't work for private repos?

mikecharles commented Dec 17, 2014

@ekalinin I suppose this won't work for private repos?

@ekalinin

This comment has been minimized.

Show comment
Hide comment
@ekalinin

ekalinin Dec 18, 2014

@ekalinin I suppose this won't work for private repos?

@mike-charles yes, unfortunately github-markdown-toc won't work for private repos

ekalinin commented Dec 18, 2014

@ekalinin I suppose this won't work for private repos?

@mike-charles yes, unfortunately github-markdown-toc won't work for private repos

@sv3ndk

This comment has been minimized.

Show comment
Hide comment
@sv3ndk

sv3ndk commented Dec 28, 2014

+1

@mockitoguy

This comment has been minimized.

Show comment
Hide comment
@mockitoguy

mockitoguy commented Jan 4, 2015

+1

@Manuzor

This comment has been minimized.

Show comment
Hide comment
@Manuzor

Manuzor commented Jan 8, 2015

+1

@joeyu

This comment has been minimized.

Show comment
Hide comment
@joeyu

joeyu Jan 9, 2015

+1
No offline approaches are preferred than the GH online dynamic generation of TOC, as all offline approaches will be a burden and hard to maintain the TOC correctly.

joeyu commented Jan 9, 2015

+1
No offline approaches are preferred than the GH online dynamic generation of TOC, as all offline approaches will be a burden and hard to maintain the TOC correctly.

@ErikMHummel

This comment has been minimized.

Show comment
Hide comment
@ErikMHummel

ErikMHummel commented Jan 9, 2015

+1

@MikeyBurkman

This comment has been minimized.

Show comment
Hide comment
@MikeyBurkman

MikeyBurkman Jan 12, 2015

Why does a solution have to extend markdown?

@ekalinin's code can already create a ToC markdown file, so GH could just generate a new ToC on every change to readme.md, and display that file on the project's homepage above the real readme.md. Everyone gets a ToC for free with their readme.md files (and presumably can opt-in/out if they wish) without changing a single line of code.

MikeyBurkman commented Jan 12, 2015

Why does a solution have to extend markdown?

@ekalinin's code can already create a ToC markdown file, so GH could just generate a new ToC on every change to readme.md, and display that file on the project's homepage above the real readme.md. Everyone gets a ToC for free with their readme.md files (and presumably can opt-in/out if they wish) without changing a single line of code.

@quasipedia

This comment has been minimized.

Show comment
Hide comment
@quasipedia

quasipedia Jan 12, 2015

Why does a solution have to extend markdown?

@MikeyBurkman - It does not need to, but if it did it, it would become part of the specification, and all libraries that works against that specification would support it (e.g.: github-markdown preview of the readme file in your IDE/editor of choice).

Preview of the TOC is important: on large documents is easy to get the levels wrong, for example.

quasipedia commented Jan 12, 2015

Why does a solution have to extend markdown?

@MikeyBurkman - It does not need to, but if it did it, it would become part of the specification, and all libraries that works against that specification would support it (e.g.: github-markdown preview of the readme file in your IDE/editor of choice).

Preview of the TOC is important: on large documents is easy to get the levels wrong, for example.

@guillaume-alvarez

This comment has been minimized.

Show comment
Hide comment
@guillaume-alvarez

guillaume-alvarez commented Jan 12, 2015

+1

@jon-hanson

This comment has been minimized.

Show comment
Hide comment
@jon-hanson

jon-hanson commented Jan 18, 2015

+1

@eidng8

This comment has been minimized.

Show comment
Hide comment
@eidng8

eidng8 commented Jan 19, 2015

+1

@MikeyBurkman

This comment has been minimized.

Show comment
Hide comment
@MikeyBurkman

MikeyBurkman Jan 19, 2015

@quasipedia Surely you aren't saying that the necessity of a preview tool is a good reason to change the MD spec! That's like saying that not having some MD tool installed on my computer means I can't edit MD. Github already have a MD preview tool... just extend it to also preview the TOC.

As for external tools: the script to generate TOC from MD is publicly available. They can integrate if and when they want, and that integration would not be much different than supporting another MD spec. Only now your tools have to adjust, not every single user.

MikeyBurkman commented Jan 19, 2015

@quasipedia Surely you aren't saying that the necessity of a preview tool is a good reason to change the MD spec! That's like saying that not having some MD tool installed on my computer means I can't edit MD. Github already have a MD preview tool... just extend it to also preview the TOC.

As for external tools: the script to generate TOC from MD is publicly available. They can integrate if and when they want, and that integration would not be much different than supporting another MD spec. Only now your tools have to adjust, not every single user.

@quasipedia

This comment has been minimized.

Show comment
Hide comment
@quasipedia

quasipedia Jan 19, 2015

@MikeyBurkman - Surely you aren't saying that improving on standards is bad! ;)

Seriously: I can't but repeat myself: the solution does not need to extentd MD. GitHub has a history of creating standards that are to all effects "forks" of previously existing ones (GFM, TOML...). Since GFM is already a different standard than MD, and since GitHub is its creator and maintainer, it wouldn't surprise me if they would implement the TOC as part if it...

...but if that doesn't happen, I am just fine! :)

quasipedia commented Jan 19, 2015

@MikeyBurkman - Surely you aren't saying that improving on standards is bad! ;)

Seriously: I can't but repeat myself: the solution does not need to extentd MD. GitHub has a history of creating standards that are to all effects "forks" of previously existing ones (GFM, TOML...). Since GFM is already a different standard than MD, and since GitHub is its creator and maintainer, it wouldn't surprise me if they would implement the TOC as part if it...

...but if that doesn't happen, I am just fine! :)

@adamjgrant

This comment has been minimized.

Show comment
Hide comment
@adamjgrant

adamjgrant commented Feb 2, 2015

+1

@dreamcat4

This comment has been minimized.

Show comment
Hide comment
@dreamcat4

dreamcat4 Feb 8, 2015

+1

Have tried MarkdownTOC for sublime text today. Which might have been a alternative but sadly it doesn't work nearly well enough. No links and seems broken as it doesn't parse my markdown headings correctly.

[EDIT] npm install -g doctor && doctoc . is good though not integrated into ST. Probably worth making a ST command entry for it.

dreamcat4 commented Feb 8, 2015

+1

Have tried MarkdownTOC for sublime text today. Which might have been a alternative but sadly it doesn't work nearly well enough. No links and seems broken as it doesn't parse my markdown headings correctly.

[EDIT] npm install -g doctor && doctoc . is good though not integrated into ST. Probably worth making a ST command entry for it.

@adamjgrant

This comment has been minimized.

Show comment
Hide comment
@adamjgrant

adamjgrant Feb 8, 2015

FWIW, I made this. https://github.com/ajkochanowicz/Smooth-ToCer

Obviously, it won't work with github readme files, but for any other markdown content that needs a TOC and can run JS...

adamjgrant commented Feb 8, 2015

FWIW, I made this. https://github.com/ajkochanowicz/Smooth-ToCer

Obviously, it won't work with github readme files, but for any other markdown content that needs a TOC and can run JS...

@bumbu

This comment has been minimized.

Show comment
Hide comment
@bumbu

bumbu commented Feb 11, 2015

+1

@robsterlini

This comment has been minimized.

Show comment
Hide comment
@robsterlini

robsterlini commented Feb 11, 2015

+1

@martinheidegger

This comment has been minimized.

Show comment
Hide comment
@martinheidegger

martinheidegger commented Feb 12, 2015

+1

@sherdeadlock

This comment has been minimized.

Show comment
Hide comment
@sherdeadlock

sherdeadlock commented Feb 13, 2015

+1

@wilsonmar

This comment has been minimized.

Show comment
Hide comment
@wilsonmar

wilsonmar commented Feb 16, 2015

+1

@apjanke

This comment has been minimized.

Show comment
Hide comment
@apjanke

apjanke commented Feb 17, 2015

+1

@AndyWendt

This comment has been minimized.

Show comment
Hide comment
@AndyWendt

AndyWendt commented Feb 19, 2015

👍

@v0lkan

This comment has been minimized.

Show comment
Hide comment
@v0lkan

v0lkan Feb 21, 2015

Bump 👍

v0lkan commented Feb 21, 2015

Bump 👍

@idelvall

This comment has been minimized.

Show comment
Hide comment
@idelvall

idelvall commented Feb 25, 2015

+1

@dreamcat4

This comment has been minimized.

Show comment
Hide comment
@dreamcat4

dreamcat4 Feb 25, 2015

Just going to repeat myself here, and say that github should adopt the doctoc tool for auto-generating TOCs in markdown files. It's the best one available out there.

dreamcat4 commented Feb 25, 2015

Just going to repeat myself here, and say that github should adopt the doctoc tool for auto-generating TOCs in markdown files. It's the best one available out there.

@AndyWendt

This comment has been minimized.

Show comment
Hide comment
@AndyWendt

AndyWendt commented Feb 25, 2015

@dreamcat4 ditto here

@sc0ttkclark

This comment has been minimized.

Show comment
Hide comment
@sc0ttkclark

sc0ttkclark commented Mar 3, 2015

yas

@jsaz

This comment has been minimized.

Show comment
Hide comment
@jsaz

jsaz commented Mar 5, 2015

+1

@raychenon

This comment has been minimized.

Show comment
Hide comment
@raychenon

raychenon Jul 27, 2017

My online table of contents generator http://tableofcontent.eu/
You don't have to install anything

raychenon commented Jul 27, 2017

My online table of contents generator http://tableofcontent.eu/
You don't have to install anything

@a-i-joe

This comment has been minimized.

Show comment
Hide comment
@a-i-joe

a-i-joe commented Oct 5, 2017

+1

@jasonkuhrt

This comment has been minimized.

Show comment
Hide comment
@jasonkuhrt

jasonkuhrt Oct 13, 2017

This wasn't obvious to me so maybe its not obvious to others but Github supports AsciiDoc which in turn supports great TOC functionality. Its kind of hard to find docs on this so here's an example of what your readme would need to contain:

:toc: macro
:toc-title:
:toclevels: 9

# Title

## A

### A2

## B

### B2

Here is an example in one of my own repos: https://github.com/littlebits/react-popover/blob/master/README.adoc

There are lots of nice little things about AsciiDoc but only its good TOC functionality for me typically warrants the change to another markup language. I'd love to be able to stay with markdown and win from the great tool/editor support etc.. For now though AsciiDoc has been working well for me.

jasonkuhrt commented Oct 13, 2017

This wasn't obvious to me so maybe its not obvious to others but Github supports AsciiDoc which in turn supports great TOC functionality. Its kind of hard to find docs on this so here's an example of what your readme would need to contain:

:toc: macro
:toc-title:
:toclevels: 9

# Title

## A

### A2

## B

### B2

Here is an example in one of my own repos: https://github.com/littlebits/react-popover/blob/master/README.adoc

There are lots of nice little things about AsciiDoc but only its good TOC functionality for me typically warrants the change to another markup language. I'd love to be able to stay with markdown and win from the great tool/editor support etc.. For now though AsciiDoc has been working well for me.

@holvonixAdvay

This comment has been minimized.

Show comment
Hide comment
@holvonixAdvay

holvonixAdvay Nov 10, 2017

@jasonkuhrt - Frankly 'use AsciiDoc' was the best advice I've seen here - thanks. So much more powerful than markdown, and not sure if anyone realizes GitHub supports it...

holvonixAdvay commented Nov 10, 2017

@jasonkuhrt - Frankly 'use AsciiDoc' was the best advice I've seen here - thanks. So much more powerful than markdown, and not sure if anyone realizes GitHub supports it...

@jasonkuhrt

This comment has been minimized.

Show comment
Hide comment
@jasonkuhrt

jasonkuhrt Nov 10, 2017

@holvonixAdvay Super happy to have helped!! 👍

jasonkuhrt commented Nov 10, 2017

@holvonixAdvay Super happy to have helped!! 👍

@pedro-mass

This comment has been minimized.

Show comment
Hide comment
@pedro-mass

pedro-mass Nov 22, 2017

@jasonkuhrt - is there anything special you need to do to get that toc macro to work? Can it be used with markdown in other parts of the page?

pedro-mass commented Nov 22, 2017

@jasonkuhrt - is there anything special you need to do to get that toc macro to work? Can it be used with markdown in other parts of the page?

@jasonkuhrt

This comment has been minimized.

Show comment
Hide comment
@jasonkuhrt

jasonkuhrt Nov 22, 2017

@pedro-mass Its an AsciiDoc only feature. You can place the TOC macro wherever you want. I think it will only show titles that appear below where you use the macro.

jasonkuhrt commented Nov 22, 2017

@pedro-mass Its an AsciiDoc only feature. You can place the TOC macro wherever you want. I think it will only show titles that appear below where you use the macro.

pierre referenced this issue in killbill/killbill-cloud Nov 28, 2017

kpm: switch to adoc format to generate a TOC
Signed-off-by: Pierre-Alexandre Meyer <pierre@mouraf.org>
@danehrlich1

This comment has been minimized.

Show comment
Hide comment
@danehrlich1

danehrlich1 Nov 30, 2017

+1 If GitHub made this is would make the world such a better place. There would be better documentation, and therefore less screw-ups and just generally happier people.

danehrlich1 commented Nov 30, 2017

+1 If GitHub made this is would make the world such a better place. There would be better documentation, and therefore less screw-ups and just generally happier people.

@brazilbean

This comment has been minimized.

Show comment
Hide comment
@brazilbean

brazilbean Dec 1, 2017

We've been wanting to move our software documentation out of Confluence and into GitHub. The biggest gain to be had is that the documentation will be versioned with the source (+++1). We're wary though that markdown lacks all of basic essentials, such as TOC support. (-1).

In the end, we'll still give markdown a try, but having TOC support would sure be nice. :)

brazilbean commented Dec 1, 2017

We've been wanting to move our software documentation out of Confluence and into GitHub. The biggest gain to be had is that the documentation will be versioned with the source (+++1). We're wary though that markdown lacks all of basic essentials, such as TOC support. (-1).

In the end, we'll still give markdown a try, but having TOC support would sure be nice. :)

@genio

This comment has been minimized.

Show comment
Hide comment
@genio

genio Jan 5, 2018

I hate to pile on here, GitHub. But, it's now 2018. Can we please have a way to auto-generate TOCs?

genio commented Jan 5, 2018

I hate to pile on here, GitHub. But, it's now 2018. Can we please have a way to auto-generate TOCs?

@mckaygerhard

This comment has been minimized.

Show comment
Hide comment
@mckaygerhard

mckaygerhard Jan 5, 2018

github its a crap, take a look to a real open source model development, the TOC generation on the gambas wiki logic are great, event generated from the title words, are using tags based on order

at leas gitlab have more enphasis..

mckaygerhard commented Jan 5, 2018

github its a crap, take a look to a real open source model development, the TOC generation on the gambas wiki logic are great, event generated from the title words, are using tags based on order

at leas gitlab have more enphasis..

@gtaifu

This comment has been minimized.

Show comment
Hide comment
@gtaifu

gtaifu Jan 9, 2018

After looking around for the tool to generate the gfm TOC, I found the tool [github-markdown-toc]((https://github.com/ekalinin/github-markdown-toc) by @ekalinin . Though the code is simply, it runs in Bash originally targets Linux.

Another tool is markdown-toc by @jonschlinkert, but it depends on remarkable.

I would like to have a snippet running locally also at Windows, which would be independent of a specific OS. So, I created a small project gfm_toc_generator based on Python3. (I wish I did not recreated the wheel.)

I will make it importable from Python and also a Sublime package later.

Hope this would be helpful to you.

gtaifu commented Jan 9, 2018

After looking around for the tool to generate the gfm TOC, I found the tool [github-markdown-toc]((https://github.com/ekalinin/github-markdown-toc) by @ekalinin . Though the code is simply, it runs in Bash originally targets Linux.

Another tool is markdown-toc by @jonschlinkert, but it depends on remarkable.

I would like to have a snippet running locally also at Windows, which would be independent of a specific OS. So, I created a small project gfm_toc_generator based on Python3. (I wish I did not recreated the wheel.)

I will make it importable from Python and also a Sublime package later.

Hope this would be helpful to you.

@mckaygerhard

This comment has been minimized.

Show comment
Hide comment
@mckaygerhard

mckaygerhard Jan 9, 2018

the project from @ekalinin are better, python3 its a messe up of complicated dependences that changes on every api upgrade.. also i do not use a poor level operatin system like guindows

mckaygerhard commented Jan 9, 2018

the project from @ekalinin are better, python3 its a messe up of complicated dependences that changes on every api upgrade.. also i do not use a poor level operatin system like guindows

@angelcervera

This comment has been minimized.

Show comment
Hide comment
@angelcervera

angelcervera Jan 10, 2018

I don't like any of the listed solutions. As @cirosantilli said, It must be a feature included in GitHub markdown. It is a basic feature to write readable documentation! The rest of options listed are not solutions, are workarounds.

angelcervera commented Jan 10, 2018

I don't like any of the listed solutions. As @cirosantilli said, It must be a feature included in GitHub markdown. It is a basic feature to write readable documentation! The rest of options listed are not solutions, are workarounds.

@mckaygerhard

This comment has been minimized.

Show comment
Hide comment
@mckaygerhard

mckaygerhard Jan 10, 2018

all are workaround due some want ruindows-like solutions compatible, and well @angelcervera github are deployed in unix-like, and almost all wiki-based software are develop in a unix-like in mind..

a web-based solution are not provided wuickly due this main reason, the second are due github has a terrible error, the anchors are based on the titles, and not on the marks.. like i suggested was made for the gambas-wiki software a good made software (of course only works well on unix-like)

mckaygerhard commented Jan 10, 2018

all are workaround due some want ruindows-like solutions compatible, and well @angelcervera github are deployed in unix-like, and almost all wiki-based software are develop in a unix-like in mind..

a web-based solution are not provided wuickly due this main reason, the second are due github has a terrible error, the anchors are based on the titles, and not on the marks.. like i suggested was made for the gambas-wiki software a good made software (of course only works well on unix-like)

@eeholmes

This comment has been minimized.

Show comment
Hide comment
@eeholmes

eeholmes Jan 23, 2018

I just wanted an autogenerated toc on my ReadMe file on my GitHub repositories which have long README's. I used @jasonkuhrt suggestion to use AsciiDoc.

  1. I renamed my README file from README.md to README.adoc
  2. I added this to the top of my README file
:toc: macro
:toc-title:
:toclevels: 99

# Table of Contents
toc::[]

30 seconds and presto -- TOC at the top of my READMEs. My readme files are simple. Headings, code. This solution required no installation of anything, just renamed the file and added the toc lines at top.

I work in RStudio and it quickly annoyed me to not be able to preview my AsciiDoc README file. I didn't feel like installing AsciiDoc just to be able to preview. So I made a dummy Rmd file with the README.adoc file included. Then I added readme-test.Rmd and readme-test.html to my .gitignore file. This way I can use RStudio's preview button on readme-test.Rmd to check my README file .

readme-test.Rmd

---
output: html_document
---

```{r child='README.adoc'}
```

eeholmes commented Jan 23, 2018

I just wanted an autogenerated toc on my ReadMe file on my GitHub repositories which have long README's. I used @jasonkuhrt suggestion to use AsciiDoc.

  1. I renamed my README file from README.md to README.adoc
  2. I added this to the top of my README file
:toc: macro
:toc-title:
:toclevels: 99

# Table of Contents
toc::[]

30 seconds and presto -- TOC at the top of my READMEs. My readme files are simple. Headings, code. This solution required no installation of anything, just renamed the file and added the toc lines at top.

I work in RStudio and it quickly annoyed me to not be able to preview my AsciiDoc README file. I didn't feel like installing AsciiDoc just to be able to preview. So I made a dummy Rmd file with the README.adoc file included. Then I added readme-test.Rmd and readme-test.html to my .gitignore file. This way I can use RStudio's preview button on readme-test.Rmd to check my README file .

readme-test.Rmd

---
output: html_document
---

```{r child='README.adoc'}
```
@jasonkuhrt

This comment has been minimized.

Show comment
Hide comment
@jasonkuhrt

jasonkuhrt Jan 30, 2018

If you are using Atom editor and if Asciidoc is undesirable (team setting, have to learn new things, not in standards, etc.) I have found that using an editor plugin can help a lot. I'm using https://github.com/t9md/atom-markdown-toc-auto.

One downside is that collaborators need to be synced with you on the editor/plugin choice.

jasonkuhrt commented Jan 30, 2018

If you are using Atom editor and if Asciidoc is undesirable (team setting, have to learn new things, not in standards, etc.) I have found that using an editor plugin can help a lot. I'm using https://github.com/t9md/atom-markdown-toc-auto.

One downside is that collaborators need to be synced with you on the editor/plugin choice.

@dbkaplun

This comment has been minimized.

Show comment
Hide comment
@dbkaplun

dbkaplun Feb 6, 2018

I wrote an extension to do this for Chrome a while ago: dbkaplun/github-markdown-outline-extension

(It won't appear on every markdown page, because it is smart about when it makes an outline. Here's a test page it will outline.)

Cheers! 🍺

dbkaplun commented Feb 6, 2018

I wrote an extension to do this for Chrome a while ago: dbkaplun/github-markdown-outline-extension

(It won't appear on every markdown page, because it is smart about when it makes an outline. Here's a test page it will outline.)

Cheers! 🍺

@AndyWendt

This comment has been minimized.

Show comment
Hide comment
@AndyWendt

AndyWendt Mar 21, 2018

I first upvoted this over three years ago (before upvotes were a thing lol)... I'm getting the vibe that this isn't a high priority haha

AndyWendt commented Mar 21, 2018

I first upvoted this over three years ago (before upvotes were a thing lol)... I'm getting the vibe that this isn't a high priority haha

@Jofairden

This comment has been minimized.

Show comment
Hide comment
@Jofairden

Jofairden May 12, 2018

It would be really nice to have __TOC__ support for Markdown

Jofairden commented May 12, 2018

It would be really nice to have __TOC__ support for Markdown

@ArtSabintsev

This comment has been minimized.

Show comment
Hide comment
@ArtSabintsev

ArtSabintsev Jun 14, 2018

Just adding my +1

ArtSabintsev commented Jun 14, 2018

Just adding my +1

@davidrdark

This comment has been minimized.

Show comment
Hide comment
@davidrdark

davidrdark commented Jul 24, 2018

+1

@kalbasit

This comment has been minimized.

Show comment
Hide comment
@kalbasit

kalbasit Jul 24, 2018

Please stop adding your +1 comments!! @isaacs can you please lock this conversation? Thank you!

kalbasit commented Jul 24, 2018

Please stop adding your +1 comments!! @isaacs can you please lock this conversation? Thank you!

@jujumo

This comment has been minimized.

Show comment
Hide comment
@jujumo

jujumo Jul 24, 2018

Anyway, I moved to Asciidoc, because github implements the TOC on it. I do not regret it,

jujumo commented Jul 24, 2018

Anyway, I moved to Asciidoc, because github implements the TOC on it. I do not regret it,

@textractor

This comment has been minimized.

Show comment
Hide comment
@textractor

textractor Aug 14, 2018

Is Macrosoft reading this? Please just change all of this to Office so we can all go home.

textractor commented Aug 14, 2018

Is Macrosoft reading this? Please just change all of this to Office so we can all go home.

@YingmingHu

This comment has been minimized.

Show comment
Hide comment
@YingmingHu

YingmingHu commented Aug 23, 2018

+1

@mckaygerhard

This comment has been minimized.

Show comment
Hide comment
@mckaygerhard

mckaygerhard Sep 3, 2018

in any case! now i use only gitlab!

mckaygerhard commented Sep 3, 2018

in any case! now i use only gitlab!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment