Create tables of contents for your markdown files !
- ✔️ Compatible with GitHub Markdown
- ✔️ Supports multiple titles with the same name
- ✔️ Supports special characters and emojis in titles
- ✔️ Can be used recursively on multiple files
- ✔️ Update current table of content if it exists
- ✔️ Chose the maximum and minimum headers level
- ✔️ Easy to use !
You need :
git clone https://github.com/Teskann/mdtoc
cd mdtoc
make
You can now use mdtoc as a console application ! 🎉
💡 You don't need the source files anymore, delete them :
cd .. && rm -rf mdtoc
usage: mdtoc [-h] [-m MIN_DEPTH] [-M MAX_DEPTH] [-t TOC_TITLE] [-l TOC_LEVEL] [-p] [-v] [-r] input
Create tables of contents for your markdown files !
positional arguments:
input Input file/directory. If you give a directory (with -r or not), mdtoc is
applied on all *.md files. If the input does not contain a mdtoc table of
content, it is created at the beginning of the file. If you wish to put
the ToC elsewhere, add a placeholder in your file (`[](mdtoc) ...
[](/mdtoc)`). If this placeholder is already in the file, all the content
between `[](mdtoc)` and `[](/mdtoc)` is replaced by the TOC.
optional arguments:
-h, --help show this help message and exit
-m MIN_DEPTH, --min-depth MIN_DEPTH
Minimum heading level. If this is set to `None`, there is no minimum depth
applied. For example, if you set -m to `2`, all the headings with level <
2 will be ignored (such as `# Dummy Heading`). Default is None.
-M MAX_DEPTH, --max-depth MAX_DEPTH
Maximum heading level. If this is set to `None`, there is no maximum depth
applied. For example, if you set -M to `3`, all the headings with level >
3 will be ignored (such as `#### Dummy Heading`). Default is None.
-t TOC_TITLE, --toc-title TOC_TITLE
Title of the table of content part. Defaults to `Table of Contents`.
-l TOC_LEVEL, --toc-level TOC_LEVEL
Heading level of the Table of content section. Defaults to 1.
-p, --print Do not overwrite the markdown file but print it with the table of content.
-v, --verbose List processed files verbosely.
-r, --recursive
If you run mdtoc on a file for the first time, the table of contents is
set at the beginning of the file. If you wish to put it elsewhere, add
placeholders [](mdtoc) and [](/mdtoc) in your file :
# This is my title
This is the description of the file
[](mdtoc) <-- Placeholder to indicate the beginning of the ToC
The table of content will be here !
Placeholder to indicate the end of the ToC --> [](/mdtoc)
## Section 1
bla bla bla
...If you run mdtoc on a file with a mdtoc Table of Content, it will be updated.
If you get an issue running mdtoc, notice this has been developed under :
| Software | Version |
|---|---|
| Operating System | Ubuntu 20.04 |
| Python | 3.8.8 |
| marko | 1.1.0 |