A quick and easy tool to generate a Table of Contents for your markdown files with minimal effort!
The mdtoc
tool can be installed in two ways: as a standalone executable or as a Python script.
If you want to install the tool globally and easily, this is the best option for you.
Head over to the repository and download the mdtoc
executable file. 📥
Ensure the file is executable by running the following command in the directory where you've downloaded it:
chmod +x mdtoc
💡 Tip: You can check if the file is executable by running
mdtoc --help
To make the tool globally available on Linux, move it to a directory in your PATH (like /usr/bin):
sudo mv mdtoc /usr/bin
For other operating systems, check specific documentation on making a file executable globally. 🔍
If you prefer to use the generator as a Python script, follow these steps:
Download the mdtoc file from the repository and rename it to mdtoc.py. 📝
Remove the first line of the file (#!/usr/bin/env python3)
if it exists, as this is only needed for executables.
Using the tool is incredibly simple! Just follow these two steps to add a Table of Contents (ToC) to your markdown file.
In the markdown file where you want to generate the Table of Contents, insert the following placeholder text:
<!--START OF MDTOC-->
<!--END OF MDTOC-->
This is where the generator will place your beautiful ToC every time you run your code 🌟!
Once you've added the ToC placeholder, run the generator using one of these commands:
mdtoc <source_file> <dest_file>
python mdtoc.py <source_file> <dest_file>
Explanation:
source_file
→ The markdown file from which the Table of Contents should be generated.
dest_file
→ The markdown file where the ToC should be inserted.
💡 Both
source_file
anddest_file
can be the same if you want to insert the ToC into the same file.*
Let's say you want to generate a ToC for this very README.md file. First, you would mark the location with the MDTOC
comments like this:
# Project Documentation
<!--START OF MDTOC-->
<!--END OF MDTOC-->
## Section 1: Introduction
...
After running the generator, it will automatically generate the Table of Contents based on your file's headers:
# Project Documentation
<!--START OF MDTOC-->
- [Section 1: Introduction](#section-1-introduction)
- [Section 2: Installation](#section-2-installation)
<!--END OF MDTOC-->
...
## Section 1: Introduction
...
And voilà! 🎉 You now have a neatly organized and clickable ToC!
Supported Markdown Headers: The generator will include headers from # to ###### in the ToC.
Customization: Feel free to modify the code to adjust the ToC style (e.g., nested lists, numbering).
Issues & Contributions: If you encounter any issues or have ideas for improving the tool, please open a GitHub issue or submit a pull request. We welcome contributions! 🙌
The Markdown-ToC-Generator
was designed to save you time and effort in organizing your markdown documents. We hope it helps improve your workflow! 🚀
Feel free to share this tool with others and give it a ⭐ on GitHub if you find it useful!
Made with ❤️ for developers by developers.