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:

### 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 

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.