Automatic TOC in github-flavoured-markdown

问题:

Is it possible to generate an automatic Table of Contents using Github Flavoured Markdown?

回答1:

I created two options to generate a toc for github-flavored-markdown:

DocToc Command Line Tool (source) requires node.js

Installation:

npm install -g doctoc

Usage:

doctoc . to add table of contents to all markdown files in the current and all sub directories.

DocToc WebApp

If you want to try it online first, go to the doctoc site, paste the link of the markdown page and it will generate a table of content that you can insert at the top of your markdown file.

Github Wikis and Anchors

As Matthew Flaschen pointed out in the comments below, for its wiki pages GitHub previously didn't generate the anchors that doctoc depends on.

UPDATE: However, they fixed this issue.

回答2:

GitHub Pages (which is basically a wrapper for Jekyll) appears to use kramdown, which implements all of Maruku, and therefore has support for an automatically generated table of contents via atoc attribute:

* auto-gen TOC:
{:toc}

The first line just starts an unordered list and is actually thrown away.

This results in a nested set of unordered lists, using the headers in the document.

Note: this should work for GitHub Pages, not GitHub Flavored Markdown (GFM) as used in comments or wiki pages. AFAIK a solution doesn't exist for that.

回答3:

It's not automatic, but it uses Notepad++ regular expressions:

Replace all first by the second (removes all lines not having headers)

^##(#?)(#?)(.*?)$(.|\r|\n)*?(?=^##|\z)
-\1\2 [\3](#\3)\n

Then (converts headers III to spaces)

-##
        -

Then (converts headers II to spaces)

-#
    -

Then (remove unused chars at the beginning and at the end of link title)

\[ *((?:(?![ .:#!\?;]*\])[^#])*)[ #:!\?;]*\]
[\1]

Then (convert last tokens lowercase and dash instead of spaces)

\]([^ \r\n]*) ([^\r\n ]*)
]\L\1-\2

Remove unused final pounds and initial dashes:

(?:()[-:;!\?#]+$|(\]#)-)
\1\2

Remove useless chars in links:

(\].*?)(?:\(|\))
\1

And finally add parenthesis around final links:

\](?!\()(.*?)$
\]\(\1\)

And voilà! You can even put this in a global macro if you repeat it enough time.

回答4:

If you edit Markdown files with Vim, you can try this plugin vim-markdown-toc.

The usage is simple, just move your cursor to the place you want to append Table of Contents and run :GenTocGFM, done!

Screenshots:

Features:

1. Generate toc for Markdown files. (Support GitHub Flavored Markdown and Redcarpet)

2. Update existing toc.

3. Auto update toc on save.

回答5:

Github Flavored Markdown uses RedCarpet as their Markdown engine. From the RedCarpet repo:

:with_toc_data - add HTML anchors to each header in the output HTML, to allow linking to each section.

It seems in that you'd need to get at the renderer level to set this flag, which isn't possible on Github obviously. However, the latest update to Github Pages, it seems that automatic anchoring is turned on for headers, creating linkable headings. Not exactly what you want, but it might help you create a TOC for your doc a bit easier (albeit manually).

回答6:

It's not possible, except for the workarounds proposed.

I proposed Kramdown TOC extension and other possibilities to [e-mail] and Steven! Ragnarök replied with the usual:

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

Let's upvote this question until it happens.

Another (generally unacceptable) workaround is to use asciidoc instead of Markdown, which does render TOCs.

回答7:

It is possible to generate a webpage automatically with http://documentup.com/ from the README.md file. It's not creating a TOC, but for many it might solve the reason for wanting to create a TOC.

Another alternative to Documentup is Flatdoc: http://ricostacruz.com/flatdoc/

回答8:

Gitdown is a markdown preprocessor for Github.

Using Gitdown you can:

• Generate Table of Contents
• Find dead URLs and Fragment Identifiers
• Include variables
• Include files
• Get file size
• Generate Badges
• Print Date
• Print information about the repository itself

Gitdown streamlines common tasks associated with maintaining a documentation page for a GitHub repository.

Using it is straightforward:

var Gitdown = require('gitdown');

Gitdown
    // Gitdown flavored markdown.
    .read('.gitdown/README.md')
    // GitHub compatible markdown.
    .write('README.md');

You can either have it as a separate script or have it as part of the build script routine (such as Gulp).

回答9:

Use coryfklein/doctoc, a fork of thlorenz/doctoc that does not add "generated with DocToc" to every table of contents.

npm install -g coryfklein/doctoc

回答10:

A very convenient way to achieve a table of contents for a mardown file when working with Visual Studio Code is the extension Markdown-TOC.

It can add a toc to existing markdown files and even keep the toc up-to-date on saving.

回答11:

My colleague @schmiedc and I have created a GreaseMonkey script that installs a new TOC button left of the h1 button which uses the excellent markdown-js library to add/refresh a table of contents.

The advantage over solutions like doctoc is that it integrates into GitHub's wiki editor and does not need users to work on their command-line (and require users to install tools like node.js). In Chrome, it works by drag 'n dropping into the Extensions page, in Firefox you will need to install the GreaseMonkey extension.

It will work with plain markdown (i.e. it does not handle code blocks correctly, as that is a GitHub extension to markdown). Contributions welcome.

回答12:

This is a not a direct answer to this question as so many people have provided workarounds. I don't think generating a TOC has been officially supported by Github yet to-date. If you want GitHub to render a Table of Contents on their GFM preview pages automatically, please participate the discussion on the official feature request issue.

回答13:

Currently it's not possible using markdown syntax (see the ongoing discussion at GitHub), however you can use some external tools such as:

• Online Table Of Content Generator (raychenon/play-table-of-contents)
• arthurhammer/github-toc - browser extension that adds a table of contents to GitHub repos

---

Alternatively use AsciiDoc instead (e.g. README.adoc), e.g.

:toc: macro
:toc-title:
:toclevels: 99
# Title

## A

### A2

## B

### B2

as suggested in this comment. Check the demo here.

回答14:

For Github's Texteditor Atom check out this awesome plugin (or "package" in Atom-lingo), which generates "TOC (table of contents) of headlines from parsed markdown" files:

markdown-toc

Once installed as Atom-package you can use the shortcut ctrl-alt-c to insert a TOC based on your markdown-doc-structure at the current cursor position...

Screenshots:

Atom Keybindings

markdown-toc gives you the following default key-bindings to control the plugin in Atom:

• ctrl-alt-c => create TOC at cursor position
• ctrl-alt-u => update TOC
• ctrl-alt-r => delete TOC

Plugin Features (from the project's README)

• Auto linking via anchor tags, e.g. # A 1 → #a-1
• Depth control [1-6] with depthFrom:1 and depthTo:6
• Enable or disable links with withLinks:1
• Refresh list on save with updateOnSave:1
• Use ordered list (1. ..., 2. ...) with orderedList:0