Markdown to create pages and table of contents?

Question

I started to use markdown to take notes.

I use marked to view my markdown notes and its beautiful.

But as my notes get longer I find it difficult to find what I want.

I know markdown can create tables, but is it able to create table of contents, that jumps to sections, or define page sections in markdown?

Alternatively, are there markdown readers/editors that could do such things. Search would be good feature to have too.

In short, I want to make it my awesome note taking tool and functions much like writing a book etc.

@jonschlinkert You should submit that as an answer! Currently, the answers only suggest tools that are either not free or Python. Not really a great set of choices. — Domi, Aug 02 '14 at 13:36
I should maybe mention that in _LaTeX_ this is achieved with `\tableofcontents`. If the wheel is going to be reinvented, it would be preferable to copy the good parts. — Eero Aaltonen, Dec 03 '15 at 16:10
GitHub markdown: http://stackoverflow.com/questions/9721944/automatic-toc-in-github-flavoured-markdown — Ciro Santilli OurBigBook.com, Jan 05 '17 at 10:21
Similarly reStructuredText has a built-in directive for [table of contents](http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents) which in simplest form looks like just `.. contents::`. — saaj, May 07 '19 at 15:17

score 670 · Answer 1 · edited Jun 23 '19 at 22:56

670

You can give this a try.

# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)
4. [Fourth Example](#fourth-examplehttpwwwfourthexamplecom)


## Example
## Example2
## Third Example
## [Fourth Example](http://www.fourthexample.com)

edited Jun 23 '19 at 22:56

bora.oren

3,439
3
33
31

answered Jan 14 '15 at 22:22

Rick

12,606
2
43
41

31

The 3rd example above does not work. `## Example ## "Example2" ## Third Example` is the only way I could get it to swallow spaces so far. Surely the 3rd tag would be interpreted as - `#Third` - followed by a space - then the word Example - in your snippet above? Hyphens do not work at all. Thanks – twobob Jul 09 '16 at 16:41
The example is there to serve as an example for more than one word. All words are broken down to no caps lock, and no spaces. – Rick Jul 09 '16 at 17:46
`#third_example` works in my Markdown implementation ([Cryogen](https://github.com/cryogen-project/cryogen-markdown)). – user2609980 Aug 12 '16 at 18:09
10

Works fine in RStudio. Just want to add that the German umlauts e.g. ü need to be written without umlaut in the anchor i.e. `1. [Einführung](#einfuhrung)` – steinbock Sep 23 '16 at 12:44
11

Anchors are not automatically created for headings in Bitbucket v4.5.2 – Rylander Oct 07 '16 at 16:36
Works perfectly with gitlabs markdown implementation in wikis and such – sebisnow Aug 01 '18 at 07:58
Only way I got it working with VS Code Preview is to use `id` instead of `name`. Also it's useful to put the anchor above your heading so that heading is also visible when you navigate. ` ## Third Example` – Rair Aug 19 '18 at 16:54
1

That fourth example is what I was looking for. Thanks! – kenecaswell Sep 04 '19 at 21:52
@MikeRylander or others wondering about BitBucket, see [this answer](https://stackoverflow.com/a/29194441/404931). It appears that Bitbucket adds a prefix of `markdown-header-` to the header names so you instead have to do something like: `3. [Third Example](#markdown-header-third-example)`. – John Pancoast Jul 28 '21 at 16:39
Can this approach show page numbers in a pdf format? – nilon Aug 10 '22 at 15:11

score 425 · Answer 2 · edited Mar 15 '23 at 17:19

425

Here's a useful method which should produce clickable references in any MarkDown editor:

At the end of each header, add an empty anchor with a chosen name — e.g. <a name="foo"></a>.
At the start of the document, list the headers with a link to their anchors — e.g. [Foo](#foo).

So this:

# Table of contents
1. [Introduction](#introduction)
2. [Some paragraph](#paragraph1)
    1. [Sub paragraph](#subparagraph1)
3. [Another paragraph](#paragraph2)

## This is the introduction <a name="introduction"></a>
Some introduction text, formatted in heading 2 style

## Some paragraph <a name="paragraph1"></a>
The first paragraph text

### Sub paragraph <a name="subparagraph1"></a>
This is a sub paragraph, formatted in heading 3 style

## Another paragraph <a name="paragraph2"></a>
The second paragraph text

Produces this:

Table of contents

Introduction

Some paragraph

Sub paragraph

Another paragraph

This is the introduction

Some introduction text, formatted in heading 2 style

Some paragraph

The first paragraph text

Sub paragraph

This is a sub paragraph, formatted in heading 3 style

Another paragraph

The second paragraph text

edited Mar 15 '23 at 17:19

ANeves

6,219
3
39
63

answered Oct 30 '15 at 09:53

Tum

6,937
2
25
23

42

I like to put the anchor tag on the line above the heading so when the link is clicked the heading shows up on the page. – mgarey Apr 05 '17 at 00:27
9

This was the only useful one for me. With long titles, it's impossible to do it without anchor tags. – Matt Fletcher Dec 12 '17 at 12:53
This is really nice. I started placing a Table of Contents in all of my Jupyter notebooks to quickly navigate between sections. – jackdbd Jan 25 '20 at 16:08
2

@mgarey Just put the anchor first: `## Foo` – tobias_k Mar 02 '20 at 11:14
2

Does not work in Bitbucket, there it displays `` as part of the heading text. – Igor Brejc Jun 22 '20 at 04:21
14

In my case I needed to use "id" instead of "name". – Lucas Brito Oct 15 '21 at 03:05
2

@LucasBrito in GitLab `name` attr works, but in VS Code - `id`. So I've added both. – Winand Jul 04 '23 at 13:28

score 158 · Answer 3 · edited Nov 21 '22 at 23:07

158

For the Visual Studio Code users the best option to use today (2020) is the Markdown All in One plugin (extension).

To install it, launch the VS Code Quick Open (Control/⌘+P), paste the following command, and press enter.

ext install yzhang.markdown-all-in-one

And to generate the TOC, open the command palette (Control/⌘+Shift+P) and select the Select Markdown: Create Table of Contentsoption.

Another option is the Markdown TOC plugin.

To install it, launch the VS Code Quick Open (Control/⌘+P), paste the following command, and press enter.

ext install markdown-toc

And to generate the TOC, open the command palette (Control/⌘+Shift+P) and select the Markdown TOC:Insert/Update option or use Control/⌘+MT.

edited Nov 21 '22 at 23:07

Thomas David Kehoe

10,040
14
61
100

answered May 10 '17 at 18:50

valdeci

13,962
6
55
80

11

Note: I just found that using stock VSCode you can make markdown links to headers: `[Section Foo](#foo-header-title)`, and it even works outside of preview mode (i.e. in the plain markdown). – kitsu.eb Jul 10 '17 at 15:26
5

another alternative for VSCode is [vscode-markdown](https://github.com/neilsustc/vscode-markdown) which has multiple features, ToC included – Ciprian Tomoiagă Oct 26 '18 at 12:23
1

That **MarkdownTOC** plugin for Sublime Text is **excellent**! I just figured out how to use it and wrote about it in my answer I just added here: https://stackoverflow.com/a/64656967/4561887. I auto-updates when you save, too, which is wonderful. I also show how to make the ToC expandable/collapsible. – Gabriel Staples Nov 03 '20 at 04:54

mxro · Accepted Answer · 2018-02-04T20:24:40.797

47

MultiMarkdown Composer does seem to generate a table of contents to assist while editing.

There might also be the one or the other library, who can generate TOCs: see Python Markdown TOC Extension.

edited Feb 04 '18 at 20:24

answered Aug 19 '12 at 23:38

mxro

6,588
4
35
38

29

MultiMarkdown Composer is MacOS only – chmike Aug 19 '15 at 08:46
2

Working Python Markdown TOC link: https://python-markdown.github.io/extensions/toc/ – John Feb 04 '18 at 15:01
2

The app isn't available in the UK region. – kenorb Jul 03 '19 at 13:29
The TOC extension produces HTML tocs, not Markdown. It is remarkable that this is hard. – rjurney Sep 29 '19 at 22:05

Luca Davanzo · Answer 5 · 2015-04-03T13:36:50.760

43

There are 2 way to create your TOC (summary) in your markdown document.

1. Manually

# My Table of content
- [Section 1](#id-section1)
- [Section 2](#id-section2)

<div id='id-section1'/>
## Section 1
<div id='id-section2'/>
## Section 2

2. Programmatically

You can use for example a script that generate summary for you, take a look to my project on github - summarizeMD -

I've tried also other script/npm module (for example doctoc) but no one reproduce a TOC with working anchors.

edited Apr 03 '15 at 13:36

answered Apr 03 '15 at 13:28

Luca Davanzo

21,000
15
120
146

``
– chmike Aug 19 '15 at 08:40
Only works in the same folder, also does not work for setext headings. – gozzilli Aug 10 '16 at 13:59

score 31 · Answer 6 · edited Jul 04 '19 at 12:36

31

You could try this ruby script to generate the TOC from a markdown file.

 #!/usr/bin/env ruby

require 'uri'

fileName = ARGV[0]
fileName = "README.md" if !fileName

File.open(fileName, 'r') do |f|
  inside_code_snippet = false
  f.each_line do |line|
    forbidden_words = ['Table of contents', 'define', 'pragma']
    inside_code_snippet = !inside_code_snippet if line.start_with?('```')
    next if !line.start_with?("#") || forbidden_words.any? { |w| line =~ /#{w}/ } || inside_code_snippet

    title = line.gsub("#", "").strip
    href = URI::encode title.gsub(" ", "-").downcase
    puts "  " * (line.count("#")-1) + "* [#{title}](\##{href})"
  end
end

edited Jul 04 '19 at 12:36

tuoxie007

1,234
12
10

answered Mar 02 '14 at 17:45

albertodebortoli

1,768
2
16
20

Great! Just a note, may want to add `ifndef`, `include`, and `endif`, among other preprocessor directives, to the forbidden words list. Also, defining the list out of the scope of the loop avoids having to reinstantiate it with each iteration. Also, this will pick up comments of any language that uses `#` comment syntax, Ruby included, which is not good. I am willing to edit if you'd like. However this is a great start and worked well for my purposes. Thanks so much! – Jeff Klein Mar 16 '16 at 23:18
1

This only works with atx headings (i.e those that start with ``#``), not with setext ones (underlined). – gozzilli Aug 10 '16 at 13:49
thanks for this, if you are using this for redcarpet on rails, you should go with `title.parameterize` for the href, thanks! – Alexis Sep 11 '16 at 22:29
If you get a lot of warnings that `URI.escape is obsolete` change `URI::encode` to `URI::encode_www_form_component` – digitalronin Mar 28 '21 at 03:49

score 29 · Answer 7 · answered Sep 08 '17 at 22:09

# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)

## Example [](#){name=example}
## Example2 [](#){name=example2}
## [Third Example](#){name=third-example}

If you use markdown extra, don't forget you can add special attributes to links, headers, code fences, and images.
https://michelf.ca/projects/php-markdown/extra/#spe-attr

score 22 · Answer 8 · edited Oct 01 '22 at 17:50

22

You could also use pandoc, the "swiss-army knife" for converting "one markup format into another". It can automatically generate a table of content in the output document if you supply the --toc argument.

Hint: --toc requires -s (which generates a standalone document), otherwise the table of contents will not be generated.

Example shell command line:

./pandoc -s --toc input.md -o output.md

edited Oct 01 '22 at 17:50

wisbucky

33,218
10
150
101

answered Feb 15 '17 at 12:32

M. Geiger

373
3
5

2

Thanks. This worked for me. I needed the output in Markdown file. So used the following : `pandoc -s --toc input.md -o input_toc.md` [ Care has to be taken to make sure that output name is different from input file name ] – Sarfraaz Ahmed Jan 13 '21 at 16:16

tanius · Answer 9 · 2019-12-05T23:35:00.910

As mentioned in other answers, there are multiple ways to generate a table of contents automatically. Most are open source software and can be adapted to your needs.

What I was missing is, however, a visually attractive formatting for a table of contents, using the limited options that Markdown provides. We came up with the following:

Code

## Content

**[1. Markdown](#heading--1)**

  * [1.1. Markdown formatting cheatsheet](#heading--1-1)
  * [1.2. Markdown formatting details](#heading--1-2)

**[2. BBCode formatting](#heading--2)**

  * [2.1. Basic text formatting](#heading--2-1)

      * [2.1.1. Not so basic text formatting](#heading--2-1-1)

  * [2.2. Lists, Images, Code](#heading--2-2)
  * [2.3. Special features](#heading--2-3)

----

Inside your document, you would place the target subpart markers like this:

<div id="heading--1-1"/>
### 1.1. Markdown formatting cheatsheet

Depending on where and how you use Markdown, the following should also work, and provides nicer-looking Markdown code:

### 1.1. Markdown formatting cheatsheet <a name="heading--1-1"/>

Example rendering

Content

1. Markdown

1.1. Markdown formatting cheatsheet

1.2. Markdown formatting details

2. BBCode formatting

2.1. Basic text formatting

2.1.1. Not so basic text formatting

2.2. Lists, Images, Code

2.3. Special features

Advantages

You can add as many levels of chapters and sub-chapters as you need. In the Table of Contents, these would appear as nested unordered lists on deeper levels.
No use of ordered lists. These would create an indentation, would not link the number, and cannot be used to create decimal classification numbering like "1.1.".
No use of lists for the first level. Here, using an unordered list is possible, but not necessary: the indentation and bullet just add visual clutter and no function here, so we don't use a list for the first ToC level at all.
Visual emphasis on the first-level sections in the table of content by bold print.
Short, meaningful subpart markers that look "beautiful" in the browser's URL bar such as #heading--1-1 rather than markers containing transformed pieces of the actual heading.
The code uses H2 headings (## …) for sections, H3 headings (### …) for sub-headings etc.. This makes the source code easier to read because ## … provides a stronger visual clue when scrolling through compared to the case where sections would start with H1 headings (# …). It is still logically consistent as you use the H1 heading for the document title itself.
Finally, we add a nice horizontal rule to separate the table of contents from the actual content.

For more about this technique and how we use it inside the forum software Discourse, see here.

score 21 · Answer 10 · answered Oct 25 '16 at 04:57

Anchor tags generated by different Markdown parsers are not even.

If you are working with Markdown parsers GFM (GitHub Flavored Markdown) or Redcarpet, I wrote a Vim plugin to handle table of contents.

Features

Generate table of contents for Markdown files.

Supported Markdown parsers:
- GFM (GitHub Flavored Markdown)
- Redcarpet
Update existing table of contents.
Auto update existing table of contents on save.

Screenshots

vim-markdown-toc

Usage

Generate table of contents

Move the cursor to the line you want to append table of contents, then type a command below suit you. The command will generate headings after the cursor into table of contents.

:GenTocGFM

Generate table of contents in GFM link style.

This command is suitable for Markdown files in GitHub repositories, like README.md, and Markdown files for GitBook.
:GenTocRedcarpet

Generate table of contents in Redcarpet link style.

This command is suitable for Jekyll or anywhere else use Redcarpet as its Markdown parser.

You can view here to know differences between GFM and Redcarpet style toc links.

Update existing table of contents manually

Generally you don't need to do this, existing table of contents will auto update on save by default. If you want do it manually, just use :UpdateToc command.

Downloads and documents

https://github.com/mzlogin/vim-markdown-toc

Sweet. It would be nice if the fences didn't mention 'vim' as such. Then your fence marker could evolve to become a part of some TOC-supported-markdown flavour. — chtenb, Oct 28 '20 at 12:59
@ChieltenBrinke You can use the option `g:vmt_fence_text` and `g:vmt_fence_closing_text` to custom fence marker. — Zhuang Ma, Dec 21 '20 at 06:08

score 18 · Answer 11 · answered Feb 22 '19 at 14:34

18

On Gitlab, markdown supports this : [[_TOC_]]

answered Feb 22 '19 at 14:34

Nicolas Thery

2,319
4
26
36

1

This solution doesn't work anymore, probably since GitLab migrated from Redcarpet to kramdown, see also its TODO list: https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/108 – Amadeu Barbosa Aug 16 '19 at 01:39
Works in Gollum v5 too. – user2394284 Mar 26 '20 at 21:27
2

This worked for me (GitLab Enterprise Edition 13.6.1-ee) – Gagik Feb 25 '21 at 09:29
Works in Azure DevOps wiki, too. – Palec Apr 23 '21 at 02:00

Marco Lackovic · Answer 12 · 2023-03-20T09:06:28.923

18

In Visual Studio Code (VSCode) you can use the extension Markdown All in One.

Once installed, follow the steps below:

Press CTRL+SHIFT+P
Select Markdown: Create Table of Contents

EDIT: nowadays I use DocToc to generate the table of contents, see my other answer for details.

edited Mar 20 '23 at 09:06

answered Apr 25 '19 at 10:36

Marco Lackovic

6,077
7
55
56

MattTT · Answer 13 · 2023-05-12T06:42:05.837

As an alternative to hand-made link lists, let's give an overview of all available out-of-the-box solutions to insert a table of contents (please comment and extend to keep this up-to-date):

With Gollum v5, markdown supports this:

<!-- assure you have a blank line before -->
[[_TOC_]]

This works in Azure DevOps wiki, too.

Since Gitlab switched from Redcarpet to Kramdown as markdown engine, they now support the following syntax

- TOC
{:toc}

see https://about.gitlab.com/handbook/markdown-guide/#table-of-contents-toc

MultiMarkdown as of 4.7 has a the following macro:

{{TOC}}

according to Jannik's answer:
If your Markdown file is to be displayed in a repo on bitbucket.org, you can use the following at the location where you want your table of contents (more info here):

[TOC]

according to Paul Jurczak's aswer:
The Markdown editor Typora also generates a Table of Contents when you write [TOC] in your document.

Currently (05/23), none of these are supported by a Sharepoint Online Markdown webpart.

I am aware, that I'm a little late with this answer. However, I missed such an overview myself. And my Edit of Nicolas Thery's answer to extend it to an overview was rejected.

Per https://stackoverflow.com/a/55634775/772844 below, BitBucket supports the `[TOC]` notation. At the time of writing I believe GitLab also supports this, along with the alternative `[[_TOC_]]`. The wonderful thing about standards is that there are so many to choose from. It would be nice if one of them would win soon! — William Gallafent, Mar 14 '22 at 11:21
Thanks @WilliamGallafent. I added `[TOC]` for bitbucket.org and Typora. Once someone can confirm your theory about GitLab, we should add it too. — MattTT, Apr 19 '22 at 12:10
But these didn't work for Jupyter notebooks. I had to do like- 1. [Item1](#Item1) 2. [Item2](#Item2) — Rahul Dey, Apr 26 '22 at 13:38

score 11 · Answer 14 · answered Jul 26 '16 at 21:45

11

For the benefit of those of us making README.md files in Atom (how I found this thread):

apm install markdown-toc

https://atom.io/packages/markdown-toc

answered Jul 26 '16 at 21:45

msanford

11,803
11
66
93

score 11 · Answer 15 · answered Apr 12 '18 at 13:23

11

You can generate it using this bash one-liner. Assumes your markdown file is called FILE.md.

echo "## Contents" ; echo ; 
cat FILE.md | grep '^## ' | grep -v Contents | sed 's/^## //' | 
  while read -r title ; do 
    link=$(echo $title | tr 'A-Z ' 'a-z-') ; 
    echo "- [$title](#$link)" ; 
    done

answered Apr 12 '18 at 13:23

Asim Jalis

884
9
8

This is great. Would be worth rewriting it as a proper script with filename as argument, and maybe with handling of sub-sections. – MasterScrat Jul 25 '18 at 09:32

Gabriel Staples · Answer 16 · 2023-07-11T16:01:19.400

If using the Sublime Text editor, the MarkdownTOC plugin works beautifully! See:

Once installed, go to Preferences --> Package Settings --> MarkdownTOC --> Settings -- User, to customize your settings. Here are the options you can choose: https://github.com/naokazuterada/MarkdownTOC#configuration.

I recommend the following:

{
  "defaults": {
    "autoanchor": true,
    "autolink": true,
    "bracket": "round",
    "levels": [1,2,3,4,5,6],
    "indent": "\t",
    "remove_image": true,
    "link_prefix": "",
    "bullets": ["-"],
    "lowercase": "only_ascii",
    "style": "ordered",
    "uri_encoding": true,
    "markdown_preview": ""
  },
  "id_replacements": [
    {
      "pattern": "\\s+",
      "replacement": "-"
    },
    {
      "pattern": "&lt;|&gt;|&amp;|&apos;|&quot;|&#60;|&#62;|&#38;|&#39;|&#34;|!|#|$|&|'|\\(|\\)|\\*|\\+|,|/|:|;|=|\\?|@|\\[|\\]|`|\"|\\.|\\\\|<|>|{|}|™|®|©|%",
      "replacement": ""
    }
  ],
  "logging": false
}

To insert a table of contents, simply click at the top of the document where you'd like to insert the table of contents, then go to Tools --> Markdown TOC --> Insert TOC.

It will insert something like this:

<!-- MarkdownTOC -->

1. [Helpful Links:](#helpful-links)
1. [Sublime Text Settings:](#sublime-text-settings)
1. [Packages to install](#packages-to-install)

<!-- /MarkdownTOC -->

Note the  HTML comments it inserts for you. These are special markers that help the program know where the ToC is so that it can automatically update it for you every time you save! So, leave these intact.

To get extra fancy, add some <details> and <summary> HTML tags around it to make the ToC collapsible/expandable, like this:

<details>
<summary><b>Table of Contents</b> (click to open)</summary>
<!-- MarkdownTOC -->

1. [Helpful Links:](#helpful-links)
1. [Sublime Text Settings:](#sublime-text-settings)
1. [Packages to install](#packages-to-install)

<!-- /MarkdownTOC -->
</details>

Now, you get this super cool effect, as shown below. See it in action in my main eRCaGuy_dotfiles readme here, or in my Sublime_Text_editor readme here.

Collapsed:
Expanded:

For extra information about its usage and limitations, be sure to read my notes about the MarkdownTOC plugin in that readme too.

sdaau · Answer 17 · 2015-06-07T22:59:03.120

I just coded an extension for python-markdown, which uses its parser to retrieve headings, and outputs a TOC as Markdown-formatted unordered list with local links. The file is

md_toc.py (was ~~md_toc.py~~)

... and it should be placed in markdown/extensions/ directory in the markdown installation. Then, all you have to do, is type anchor <a> tags with an id="..." attribute as a reference - so for an input text like this:

$ cat test.md 
Hello
=====

## <a id="sect one"></a>SECTION ONE ##

something here

### <a id='sect two'>eh</a>SECTION TWO ###

something else

#### SECTION THREE

nothing here

### <a id="four"></a>SECTION FOUR

also...

... the extension can be called like this:

$ python -m markdown -x md_toc test.md 
* Hello
    * [SECTION ONE](#sect one)
        * [SECTION TWO](#sect two)
            * SECTION THREE
        * [SECTION FOUR](#four)

... and then you can paste back this toc in your markdown document (or have a shortcut in your text editor, that calls the script on the currently open document, and then inserts the resulting TOC in the same document).

Note that older versions of python-markdown don't have a __main__.py module, and as such, the command line call as above will not work for those versions.

score 7 · Answer 18 · answered Oct 07 '16 at 11:27

7

Typora generates Table of Content by adding [TOC] to your document.

answered Oct 07 '16 at 11:27

Paul Jurczak

7,008
3
47
72

Thanks a lot! Here's link to the readme as well: http://support.typora.io/Markdown-Reference/#table-of-contents-toc – Onni Hakala Jan 22 '17 at 08:38

Antonio Maiorano · Answer 19 · 2015-06-05T12:52:28.867

6

I wrote a python script that parses a markdown file and outputs a table of contents as a markdown list: md-to-toc

Unlike other scripts I've found, md-to-toc correctly supports duplicate titles. It also doesn't require an internet connection, so it works on any md file, not just those available from a public repo.

edited Jun 05 '15 at 12:52

answered Jun 05 '15 at 04:31

Antonio Maiorano

461
5
6

Micah Elliott · Answer 20 · 2019-12-05T19:00:09.810

Just use your text editor with a plugin.

Your editor quite possibly has a package/plugin to handle this for you. For example, in Emacs, you can install markdown-toc TOC generator. Then as you edit, just repeatedly call M-x markdown-toc-generate-or-refresh-toc. That's worth a key binding if you want to do it often. It's good at generating a simple TOC without polluting your doc with HTML anchors.

Other editors have similar plugins, so the popular list is something like:

Emacs: markdown-toc
Vim: markdown-toc
Atom: markdown-toc
VSCode: markdown-toc

score 5 · Answer 21 · answered Nov 12 '14 at 05:39

5

I just started doing the same thing (take notes in Markdown). I use Sublime Text 2 with the MarkdownPreview plugin. The built-in markdown parser supports [TOC].

answered Nov 12 '14 at 05:39

Martin

168
2
11

3

Sublime text 3 also has a plugin for generating toc: https://packagecontrol.io/packages/MarkdownTOC – fangda Dec 26 '17 at 07:57
@fangda, that's a great plugin! I just installed it, figured out how to use it, and wrote about it in my answer here: https://stackoverflow.com/a/64656967/4561887. – Gabriel Staples Nov 03 '20 at 04:53

score 4 · Answer 22 · answered Apr 11 '19 at 14:21

If your Markdown file is to be displayed in a repo on bitbucket.org, you should add [TOC] at the location where you want your table of contents. It will then be auto-generated. More info here:

https://confluence.atlassian.com/bitbucket/add-a-table-of-contents-to-a-wiki-221451163.html

score 4 · Answer 23 · answered Feb 12 '21 at 15:09

Here is a simple bash script to generate Table of Contents. Requires no special dependencies, but bash.

https://github.com/Lirt/markdown-toc-bash

It handles well special symbols inside of headings, markdown links in headings and ignores code blocks.

score 3 · Answer 24 · answered Feb 13 '16 at 12:37

Based on albertodebortoli answer created the function with additional checks and substitution of punctuation marks.

# @fn       def generate_table_of_contents markdown # {{{
# @brief    Generates table of contents for given markdown text
#
# @param    [String]  markdown Markdown string e.g. File.read('README.md')
#
# @return   [String]  Table of content in markdown format.
#
def generate_table_of_contents markdown
  table_of_contents = ""
  i_section = 0
  # to track markdown code sections, because e.g. ruby comments also start with #
  inside_code_section = false
  markdown.each_line do |line|
    inside_code_section = !inside_code_section if line.start_with?('```')

    forbidden_words = ['Table of contents', 'define', 'pragma']
    next if !line.start_with?('#') || inside_code_section || forbidden_words.any? { |w| line =~ /#{w}/ }

    title = line.gsub("#", "").strip
    href = title.gsub(/(^[!.?:\(\)]+|[!.?:\(\)]+$)/, '').gsub(/[!.,?:; \(\)-]+/, "-").downcase

    bullet = line.count("#") > 1 ? " *" : "#{i_section += 1}."
    table_of_contents << "  " * (line.count("#") - 1) + "#{bullet} [#{title}](\##{href})\n"
  end
  table_of_contents
end

dosmanak · Answer 25 · 2020-11-16T09:58:00.873

I am not sure, what is the official documentation for markdown. Cross-Reference can be written just in brackets [Heading], or with empty brackets [Heading][].

Both works using pandoc. So I created a quick bash script, that will replace $__TOC__ in md file with its TOC. (You will need envsubst, that might not be part of your distro)

#!/bin/bash
filename=$1
__TOC__=$(grep "^##" $filename | sed -e 's/ /1. /;s/^##//;s/#/   /g;s/\. \(.*\)$/. [\1][]/')
export __TOC__
envsubst '$__TOC__' < $filename

score 3 · Answer 26 · answered Nov 16 '16 at 01:05

3

MultiMarkdown 4.7 has a {{TOC}} macro that inserts a table of contents.

answered Nov 16 '16 at 01:05

Michael R

375
2
6

Alex Harvey · Answer 27 · 2020-02-18T02:50:06.837

There is a Ruby script called mdtoc.rb that can auto-generate a GFM Markdown Table of Contents, and it is similar but slightly different to some other scripts posted here.

Given an input Markdown file like:

# Lorem Ipsum

Lorem ipsum dolor sit amet, mei alienum adipiscing te, has no possit delicata. Te nominavi suavitate sed, quis alia cum no, has an malis dictas explicari. At mel nonumes eloquentiam, eos ea dicat nullam. Sed eirmod gubergren scripserit ne, mei timeam nonumes te. Qui ut tale sonet consul, vix integre oportere an. Duis ullum at ius.

## Et cum

Et cum affert dolorem habemus. Sale malis at mel. Te pri copiosae hendrerit. Cu nec agam iracundia necessitatibus, tibique corpora adipisci qui cu. Et vix causae consetetur deterruisset, ius ea inermis quaerendum.

### His ut

His ut feugait consectetuer, id mollis nominati has, in usu insolens tractatos. Nemore viderer torquatos qui ei, corpora adipiscing ex nec. Debet vivendum ne nec, ipsum zril choro ex sed. Doming probatus euripidis vim cu, habeo apeirian et nec. Ludus pertinacia an pro, in accusam menandri reformidans nam, sed in tantas semper impedit.

### Doctus voluptua

Doctus voluptua his eu, cu ius mazim invidunt incorrupte. Ad maiorum sensibus mea. Eius posse sonet no vim, te paulo postulant salutatus ius, augue persequeris eum cu. Pro omnesque salutandi evertitur ea, an mea fugit gloriatur. Pro ne menandri intellegam, in vis clita recusabo sensibus. Usu atqui scaevola an.

## Id scripta

Id scripta alterum pri, nam audiam labitur reprehendunt at. No alia putent est. Eos diam bonorum oportere ad. Sit ad admodum constituto, vide democritum id eum. Ex singulis laboramus vis, ius no minim libris deleniti, euismod sadipscing vix id.

It generates this table of contents:

$ mdtoc.rb FILE.md 
#### Table of contents

1. [Et cum](#et-cum)
    * [His ut](#his-ut)
    * [Doctus voluptua](#doctus-voluptua)
2. [Id scripta](#id-scripta)

Title

Heading 1

Sub-Title

Heading 2

Sub-Sub-Title

Heading 3

Sub-Sub-Sub-Title

Heading 4

score 2 · Answer 29 · answered Jul 04 '20 at 13:22

2

You can use DocToc to generate the table of contents from command line with:

doctoc /path/to/file

To make links compatible with anchors generated by Bitbucket, run it with the --bitbucket argument.

answered Jul 04 '20 at 13:22

Marco Lackovic

6,077
7
55
56

score 2 · Answer 30 · answered Nov 16 '22 at 23:50

2

If IntelliJ user do: , command n or control n gives option to create or update the table of contents. Reference: read here

answered Nov 16 '22 at 23:50

Alferd Nobel

3,185
2
30
35

score 1 · Answer 31 · answered Sep 23 '14 at 13:59

Depending on your workflow, you might want to look at strapdown

That's a fork of the original one (http://strapdownjs.com) that adds the generation of the table of content.

There's an apache config file on the repo (might not be properly updated yet) to wrap plain markdown on the fly, if you prefer not writing in html files.

score 1 · Answer 32 · answered Feb 06 '17 at 09:53

If you happen to use Eclipse you can use the Ctrl+O (outline) shortcut, this will show the equivalent of the table of contents and allow to search in section titles (autocomplete).

You can also open the Outline view (Window -> Show View -> Outline) but it has no autocomplete search.

score 1 · Answer 33 · answered Aug 29 '18 at 19:24

1

Use toc.py which is a tiny python script which generates a table-of-contents for your markdown.

Usage:

In your Markdown file add <toc> where you want the table of contents to be placed.
$python toc.py README.md (Use your markdown filename instead of README.md)

Cheers!

answered Aug 29 '18 at 19:24

Dhruv Batheja

2,140
1
18
16

You script is nice but it doesn't create an anchor before each title. Necessary at least in bitbucket. – Paul Rougieux Mar 19 '19 at 10:36

score 1 · Answer 34 · answered Jan 24 '19 at 19:05

I have used https://github.com/ekalinin/github-markdown-toc which provides a command line utility that auto-generates the table of contents from a markdown document.

No plugins, or macros or other dependencies. After installing the utility, just paste the output of the utility to the location in the document where you want your table of contents. Very simple to use.

$ cat README.md | ./gh-md-toc -

score 0 · Answer 35 · answered Dec 15 '17 at 19:27

0

You can use the [TOC] at the first line and then on the bottom, the only thing you need to do is making sure that the titles are in the same bigger font. The table of content would come out automatically. ( But this only appear in some markdown editors, I didn't try all)

answered Dec 15 '17 at 19:27

Cecilé

11
2

This is true for Typora Markdown. Possibly others? – Alex Harvey Sep 01 '18 at 09:48

score 0 · Answer 36 · answered Oct 16 '18 at 12:17

0

Just add the number of slide ! it work with markdown ioslides and revealjs presentation

## Table of Contents

 1. [introduction](#3)
 2. [section one](#5)

answered Oct 16 '18 at 12:17

Abdelali Amghar

53
8

score 0 · Answer 37 · answered Sep 11 '19 at 14:24

Here is a short PHP code I use to generate the TOC, and enrich any headings with anchor:

$toc = []; //initialize the toc to an empty array
$markdown = "... your mardown content here...";

$markdown = preg_replace_callback("/(#+)\s*([^\n]+)/",function($matches) use (&$toc){
    static $section = [];
    $h = strlen($matches[1]);

    @$section[$h-1]++;
    $i = $h;
    while(isset($section[$i])) unset($section[$i++]);

    $anchor = preg_replace('/\s+/','-', strtolower(trim($matches[2])));

    $toc[] = str_repeat('  ',$h-1)."* [".implode('.',$section).". {$matches[2]}](#$anchor)";
    return str_repeat('#',$h)." <strong>".implode('.',$section).".</strong> ".$matches[2]."\n<a name=\"$anchor\"></a>\n";
}, $markdown);

You can then print the processed markdown and toc:

   print(implode("\n",$toc));
   print("\n\n");
   print($markdown);

score 0 · Answer 38 · answered Mar 19 '21 at 14:05

0

I am using this website Markdown-TOC Creator where some can paste his whole markdown entry and the website is automtically creating all the required tags and TOC (table of content) so some can easily copy paste it into his own document.

answered Mar 19 '21 at 14:05

Panagiotis D.

41
9

gil.fernandes · Answer 39 · 2021-11-25T18:04:56.797

This is a small nodejs script which generates the table of contents and takes into account repeated titles:

const fs = require('fs')
const { mdToPdf } = require('md-to-pdf');

const stringtoreplace = '<toc/>'

const processTitleRepetitions = (contents, titleMap) => {
  for (const content of contents) {
    titleMap[content.link] = typeof titleMap[content.link] === 'undefined'
      ? 0
      : titleMap[content.link] + 1
    if (titleMap[content.link] > 0) {
      content.link = `${content.link}-${titleMap[content.link]}`
    }
  }
}

const convertContentToPdf = async (targetFile) => {
  const pdf = await mdToPdf({path: targetFile}).catch(console.error)
  if(pdf) {
    const pdfFile = `${targetFile.replace(/\.md/, '')}.pdf`
    fs.writeFileSync(pdfFile, pdf.content)
    return pdfFile
  }
  throw new Error("PDF generation failed.")
}

const generateTOC = (file, targetFile) => {
  // Extract headers
  const fileContent = fs.readFileSync(file, 'utf-8')
  const titleLine = /((?<=^)#+)\s(.+)/
  const contents = fileContent.split(/\r?\n/).
    map(line => line.match(titleLine)).
    filter(match => match).
    filter(match => match[1].length > 1).
    map(regExpMatchArray => {
      return {
        level: regExpMatchArray[1].length, text: regExpMatchArray[2],
        link: '#' + regExpMatchArray[2].replace(/(\s+|[.,\/#!$%^&*;:{}=\-_`~()]+)/g, '-').toLowerCase(),
      }
    })
  const titleMap = {}
  processTitleRepetitions(contents, titleMap)
  // Write content
  let toctext = '## Table of Contents\n'
  // Find the toplevel to adjust the level of the table of contents.
  const topLevel = contents.reduce((maxLevel, content) => Math.min(content['level'], maxLevel), 1000)
  levelCounter = {}
  contents.forEach(item => {
    let currentLevel = parseInt(item.level)
    levelCounter[currentLevel] = levelCounter[currentLevel] ? levelCounter[currentLevel] + 1 : 1
    Object.entries(levelCounter).forEach(e => {
      if(currentLevel < parseInt(e[0])) {
        levelCounter[e[0]] = 0
      }
    })
    const level = Array(currentLevel - topLevel).fill('\t').join('')
    const text = `${levelCounter[currentLevel]}. [${item['text']}](${item['link']}) \n`
    toctext += level + text
  })

  const updatedContent = fileContent.toString().replace(stringtoreplace, toctext)
  fs.writeFileSync(targetFile, updatedContent)
  convertContentToPdf(targetFile).then((pdfFile) => {
    console.info(`${pdfFile} has been generated.`)
  })
}

const args = process.argv.slice(2)

if(args.length < 2) {
  console.error("Please provide the name of the markdown file from which the headers should be extracted and the name of the file with the new table of contents")
  console.info("Example: node MD_TOC.js <source_md> <target_md>")
  process.exit(1)
}

const source_md = args[0]
const target_md = args[1]

generateTOC(source_md, target_md)

To use it you will need to inject <toc/> in your markdown file.

Here is how you can use it:

generateTOC('../README.md', '../README_toc.md')

The first argument is the source markdown file and the second one the file with the markdown.

score -1 · Answer 40 · answered Nov 04 '21 at 06:56

If you're using Discount markdown, enable a flag -ftoc to auto-generate and use -T to prepend a table of contents, e.g.:

markdown -T -ftoc <<EOT
#heading 1

content 1

##heading 2

content 2
EOT

will produce

<ul>
 <li><a href="#heading-1">heading 1</a>
 <ul>
  <li><a href="#heading-2">heading 2</a></li>
 </ul>
 </li>
</ul>
<a name="heading-1"></a>
<h1>heading 1</h1>
...

Apparently you can use markdown -toc as well, which the man does not mention, but the USAGE info does (trigger by illegal option like markdown -h).

It took me a while reading the source to figure this out, so I'm writing it down mostly for future me. I'm using discount markdown on Arch Linux, from the discount package. man doesn't really tell you it's discount, but mentions David Parsons under AUTHOR.

markdown --version
# markdown: discount 2.2.7

score -14 · Answer 41 · answered Jun 19 '13 at 18:31

-14

Um... use Markdown's headings!?

That is:

# This is the equivalent of < h1 >

## This is the equivalent of < h2>

### This is the equivalent of < h3>

Many editors will show you a TOC. You can also grep for the heading tags and create your own.

Hope that helps!

--JF

answered Jun 19 '13 at 18:31

user2502476

1

1

Seems like a duplicated answer to me. – ForceMagic Jun 19 '13 at 18:52

Markdown to create pages and table of contents?

41 Answers41

Table of contents

This is the introduction

Some paragraph

Sub paragraph

Another paragraph