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 diff

Answer 1

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.

Answer 2

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!

Answer 3

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

Answer 4

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

Answer 5

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 -

Answer 6

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