How can I make a table of contents for a markdown document with Python/AWK/SED?

Question

I have the following markdown document:

Heading-a
==========

---text---

Heading-b
------------

--- text ---

Heading-c
----------

--- text---

Heading-d
=======

--- text----

Heading-e
---

...

I would like to make a clickable table of contents out of it, similar to the way LaTex does, but can't find a tool that does this, which suggests to me that we should build one.

The tool should collect 'H1' headings and 'H2' headings such that it assigns the number 1 to Heading-a and the number 1.1. to Heading-b, 1.2. to Heading-c, 2. to Heading-d, 2.1. to Heading-e and so on, such that we should get the following Table of contents:

  1. Heading-a
  1.1. Heading-b
  1.2. Heading-c
  2. Heading-d
  2.1. Heading-e

How can I do this with Python/AWK/SED?

Answer 1

The Markdown in Python implementation has support for extensions one of which includes Table of Contents generation. Additionally Pandoc (which is a Haskell markup->PDF has support for markdown (in addition to a bunch of other formats) and can output pretty HTML, LaTeX, PDFs, etc.

Answer 2

If you already have headings, you can try github-markdown-toc is able to process stdin, local and remote files, for example:

cat ~/projects/Dockerfile.vim/README.md | ./gh-md-toc -

or creating a local README.md:

./gh-md-toc ~/projects/Dockerfile.vim/README.md

Answer 3

See this article for a comparison of lightweight markup languages with some information on tables of contents that might lead you in the direction of a solution.