From d6692012087b383e3fe022db6dc69dd08919e62b Mon Sep 17 00:00:00 2001
From: ankraft <an.kraft@gmail.com>
Date: Wed, 29 Nov 2023 11:46:18 +0100
Subject: [PATCH] Support special tags to insert a TOC
---
generateTOC/README.md | 21 ++++++++++++++++++---
generateTOC/generateTOC.py | 8 ++++++--
2 files changed, 24 insertions(+), 5 deletions(-)
diff --git a/generateTOC/README.md b/generateTOC/README.md
index ac34a43..be66556 100644
--- a/generateTOC/README.md
+++ b/generateTOC/README.md
@@ -3,7 +3,18 @@
The script will generate a TOC for a Markdown file, based on the headers in the file.
It generates and prints the TOC to the console, and optionally also inserts it into the original file.
-For the latter, it will first create a backup copy of the file and then replace any section named "# Contents" with the new table of contents.
+For the latter, it will first create a backup copy of the file and then replace any section named "# Contents" with the new table of contents **in the original input document**.
+
+### Support for Table-of-Content Tags
+
+Some renderers support special tags in the Markdown document to automatically insert a TOC. This script supports the following tags:
+
+- `<!--TOC-->`
+- `[TOC]`
+- `[CONTENT]`
+
+If the `--toctags` and `--add-content` options are specified, the script will replace these tags with the generated TOC in the original input document. To keep the original document intact, it may be a good idea to first create a backup copy of the document and work on that copy.
+
## Prerequisites
@@ -19,7 +30,9 @@ $ python generateTOC.py <document path>
## Command Line Options
```
-usage: generateTOC.py [-h] [--add-content] [--contents] [--indent <indent>] [--level LEVELS] document
+usage: generateTOC.py [-h] [--add-content] [--contents] [--indent <indent>]
+ [--level LEVELS] [--toc-tags]
+ document
positional arguments:
document document to parse
@@ -27,9 +40,11 @@ positional arguments:
options:
-h, --help show this help message and exit
--add-content, -a add TOC to "# Content" section in the document (default: False)
- --contents, -c add link to "Contents" section in the generated TOC (default: False)
+ --contents, -c add link to "Contents" section in the generated TOC (default:
+ False)
--indent <indent>, -i <indent>
indent spaces for each level (default: 4)
--level LEVELS, -l LEVELS
limit the TOC levels; 0 means no limit (default: 0)
+ --toc-tags, -t replace special TOC tokens in the document (default: False)
```
\ No newline at end of file
diff --git a/generateTOC/generateTOC.py b/generateTOC/generateTOC.py
index 5f63622..4e29ace 100644
--- a/generateTOC/generateTOC.py
+++ b/generateTOC/generateTOC.py
@@ -13,6 +13,9 @@ import argparse, os, re
from rich import print
+tocTags:[str] = ['[TOC]', '[CONTENT]', '<!--TOC-->']
+""" TOC tags to replace in the document with the TOC. """
+
def backupFile(filename:str) -> None:
""" Backup a file.
@@ -97,8 +100,8 @@ def processDocument(args:argparse.Namespace) -> None:
continue
inToc = False
- # Write the new TOC
- if line.strip() == '# Contents':
+ # Write the new TOC in the right place
+ if (args.tocTags and line.strip() in tocTags) or line.strip() == '# Contents':
inToc = True
f.write(to)
continue
@@ -133,6 +136,7 @@ if __name__ == '__main__':
parser.add_argument('--contents', '-c', action='store_true', dest='contents', default = False, help = 'add link to "Contents" section in the generated TOC')
parser.add_argument('--indent', '-i', action='store', dest='indent', type = nonNegativeInt, default = 4, metavar = '<indent>', help = 'indent spaces for each level')
parser.add_argument('--level', '-l', action='store', dest='levels', type = nonNegativeInt, default = 0, help = 'limit the TOC levels; 0 means no limit')
+ parser.add_argument('--toc-tags', '-t', action='store_true', dest='tocTags', default = False, help = 'replace special TOC tokens in the document')
parser.add_argument('document', help = 'document to parse')
args = parser.parse_args()
--
GitLab