generateTOC

Automatically generate a clean Table of Contents for your markdown files, with universal links to respective sections.

This project was created to extend the functionality of simple markdown editors (specifically Joplin) which don't natively support the "[TOC]" shorthand.

I plan to contribute to Joplin once I polish and refine the code.

Parameters

Parameter	Flags	Desc.	Default
filename	-f --file	path to file	none
output	-o --output	output filename	out.md
directory	-d --dir	output directory	./
write_title	-t --title	Write title to first line rather than in TOC?
clipboard	-c --clipboard	Replace selected text from clipboard

Notes

• Clipboard parameter takes text from the X11 clipboard and sets the clipboard contents to the previous text with TOC prepended.
• --clipboard requires Pyperclip

Examples

• Overwrite your existing file by setting the output to the input file.

  python gentoc.py -f myfile.md -o myfile.md
  

• Generate a TOC for each file in a directory

  ls | grep .md | while read -r line; do
  	python gentoc.py -f $line -o $line
  done
  	

• Add a TOC to current selected markdown text

  xdotool key --clearmodifiers "ctrl+x"
  python /path/to/gentoc.py --clipboard
  xdotool key --clearmodifiers "ctrl+v"

---

Todo

• Implement filesystem validation
• Strengthen illegal character handling
• Give more CLI feedback
• Remove Pyperclip dependency