Table of Figures

Figure 1: Table of Contents tags
Figure 2: Table of Contents generation example
Figure 3: Table of Figures tags

TOC-Generator

A table of contents generator for markdown, written in python. Inspired by many of the table-of-contents generators that already exist, particularly markdown-toc.

Origin

This project is a fork work initiated by Chris3606. The original repo can be found here. At time of initial alteration, it wasn't accepting PRs and seems abandoned. As such, this is now a maintained fork, mostly for my own uses but feel free to use it if it is of use.

Installation/Prerequisites

The system consists of a single python script, requiring >= Python v3.5 to run.

Dependencies include

click

These are all listed in setup.py

Usage

The Table of Contents

In all markdown files in your project that you want to generate tables of contents for, insert the following tags into the file, where you want the table of contents to be placed:

<!--ts-->
<!--end-->

Figure 1: Table of Contents tags

NOTE: Hyperlinks in headers are stripped before generation

When run, based on the formatting of the Markdown document, anything between these two labels will be replaced with the current table of contents. An example of this, drawn from the test files, is shown below

 <!-- ts -->
 * [This is the First heading](#this-is-the-first-heading)
     * [Para 2](#para-2)
         * [Para 3](#para-3)
     * [Para 4](#para-4)
     * [This is a second heading](#this-is-a-second-heading)
     * [Another heading](#another-heading)
 <!-- end -->

Figure 2: Table of Contents generation example

The Table of Figures

Just as the table of contents, a table of figures can be included with the following tag

<!--tfs-->
<!--end-->

Figure 3: Table of Figures tags

However, for inclusion within the table of figures we must add marker for our script to recognise. This takes the form

<!-- fig_x : <<<SOME DESCRIPTION>>> -->
<!-- end -->

Where the description entered for <<<SOME DESCRIPTION>>> will appear as a label for the figure.

Results

When the script is run, all text in between those two tags will be replaced with the table of contents. Furthermore, the tags themselves will (obviously) not appear in the markdown view on GitHub, as they are HTML comments.

Run the included python script, passing as a command-line argument the directory of your project. The script will automatically locate any markdown files (with .md extensions) within that folder and all sub-folders. It will scan them for the above tags. If found, it will generate the table of contents for them, and replace any text inside the tags with the new table of contents. Any file in which the tags can't be located will not be modified.

Excluding "Header" Elements

if you wish to exclude elements from the Table of Contents this can be done using the following tag

<!-- body-start -->

This will result in every tag prior to this in the file being excluded from the table of contents. Usually, this is done to allow the Table of Contents and Table of Figures to have their own titles yet to have those titles excluded from the table of contents itself.

When omitted, the entire file is considered for inclusion as part of the contents table.

fenryka/TOC-Generator

Table of Contents