/TOC-MD

Table of Contents for Markdown

Primary LanguagePrologThe UnlicenseUnlicense

TOC-MD - Table of Contents for Markdown

Contents

Description [TOC]

TOC-MD generates tables of contents for Markdown files. It's been tested successfully in GitHub READMEs and dev.to posts.

Usage

This basic program takes a single argument with the path of the file to process and print the result to the standard output. To store it in a file, you must redirect it.

This README.md, for example, had its table of contents generated with tocgen

$ ./tocgen README.in > README.md

Passing more or none arguments will print a usage message.

Features

  • A single line containing the label <toc> will be replaced by the actual Table of Contents of the file.

  • All first level headers (h1) will include a link to the Table of Contents.

  • It only takes into account the markdown headers made with #, so to make a section invisible you can use === or html tags.

    # Section one
This one is shown.

Section two
===
This one is hidden.

<h1>Section three</h1>

This one too.

Bugs

  • If the <toc> label is surrounded by any white spaces, it won't be replaced.

  • If the file doesn't end in a newline, the program will go on an infinite loop.

Build [TOC]

To build TOC-MD you need SWI-Prolog in your computer. The compilation using the provided Makefile is pretty straightforward.

$ make

This creates the tocgen executable in the root of the project.

To Do [TOC]

This is version is somewhat rudimentary, to say the least. There are a lot of things yet to be done:

  • Correct the bugs.
  • Section specific TOC.
  • Invisible sections.
  • TOC depth specified in the label.
  • Add flexibility via cli options or toc xml-like fields, like.
    • TOC depth.
    • Levels where the TOC link should be included.
  • Reinterpret levels.
    • For example, If you don't use level 2 but directly level 3, don't subscribe the bullets to an inexistent second level.

License

This software uses the Unlicense.