markdown-toc-generator 1.0.0__tar.gz

markdown_toc_generator-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Electronic Mango
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

markdown_toc_generator-1.0.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.3
+Name: markdown-toc-generator
+Version: 1.0.0
+Summary: Python scripts generating Table of Contents from markdown headers.
+Keywords: Markdown,ToC,toc,table-of-contents,Table of Contents
+Author: Electronic Mango
+Author-email: Electronic Mango <78230210+Electronic-Mango@users.noreply.github.com>
+License: MIT License
+         
+         Copyright (c) 2026 Electronic Mango
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/Electronic-Mango/markdown-toc-generator
+Project-URL: Documentation, https://electronic-mango.github.io/markdown-toc-generator
+Project-URL: Repository, https://github.com/Electronic-Mango/markdown-toc-generator
+Description-Content-Type: text/markdown
+
+# Markdown Table of Contents generator
+
+Basic Markdown Table of Contents generator written in `Python`.
+
+The script generates ToC in a form of a nested list based on headings in Markdown files.
+The ToC can be printed to console, or inserted/updated into analyzed files.
+
+> **Warning**: Inserting/updating ToC into the files can be destructive, as entire file is read, ToC is inserted/updated, then entire file is overwritten. The remaining contents of the file shouldn't be affected, but be careful.
+
+The project is managed by [uv](https://docs.astral.sh/uv/).
+
+
+## Usage
+
+The main script is `toc.py`, it has a built-in help with all parameters described:
+```bash
+./src/toc.py --help
+```
+
+
+### Arguments
+
+ * **`--root`, `-r`** - **required**, path in which files will be analyzed (recursively)
+ * **`--exclude`, `-e`** - paths to files, or directories, which should be excluded from analysis, **relative to root**
+ * **`--in-place`, `-i`** - update analyzed files with generated ToC, **potentially destructive** and will request confirmation before any changes are done
+ * **`--force`, `-f`** - skip confirmation for potentially destructive operations, like for `--in-place` flag
+ * **`--skip`, `-s`** - skip *n* highest level headings from generated ToC
+ * **`--take`, `-t`** - control how many headings are inserted into the ToC, starting from not-skipped by `--skip` - e.g. `--skip 1 --take 2` will include levels 2-4
+ * **`--toc-regex`** - regex used for updating/inserting ToC into files when using `--in-place` flag
+ * **`--summary`** - generate summary from all analyzed headings into one output - all ToCs with their respective files generated into one Markdown output
+ * **`--summary-path`** - write the generated summary to a file under passed path (`--in-place` flag is still required), **potentially very destructive** as the summary will overwrite everything in that file; this path is automatically excluded; **NOT relative to root**
+ * **`--summary-heading`** - prefix added to the generated summary as the highest level heading
+
+
+### ToC regular expression
+
+The default regex used to insert ToC into the file itself is:
+```
+^(#[^#].+)$(\s*-.+\n)*\s*
+```
+It will look for the first heading available and treat the list right after it as the ToC to replace. So by default the script assumes, that file structure will be something like:
+
+```markdown
+# First heading in file (but doesn't have to be level 1)
+
+- First element of ToC
+  - First subelement of ToC
+- Second element of ToC
+
+Something else, not a list, which won't be modified.
+The rest of the file doesn't matter.
+```
+
+These regexes should include two groups - first looks for the section right before the ToC (which won't be modified in the resulting file), the second looks for the ToC itself (which will be replaced).
+
+
+### Summary
+
+The generated summary will have a structure of:
+
+```markdown
+Summary heading as per `--summary-heading` flag, or "# Summary:" by default
+
+## Link to directory with notes, text is the directory name
+
+### Link to a note, text is taken from the heading level 1 from that note
+
+- [Heading 2 name](link to file and section)
+ - [Heading 3 name](link to file and section)
+- [Heading 2 name](link to file and section)
+```
+
+And so on.
+
+When flags `--in-place` and `--summary-path PATH_TO_FILE` are passed the resulting summary will be written to `PATH_TO_FILE` as is overwritting everything else in the file, so **it can be very destructive**.
+
+
+### Examples
+
+Generate ToC based on files in `notes/stuff` subdirectory, except for `README.md` and files under `ignore/notes`; ignore the highest level heading and include only 2 levels after that; only print to console, without summary:
+```bash
+./src/toc.py -r notes/stuff -e README.md ignore/notes -s 1 -t 2
+```
+
+The same as above, but print a summary as well, with `# Some stuff:` prefix:
+```bash
+./src/toc.py -r notes/stuff -e README.md ignore/notes -s 1 -t 2 --summary --summary-heading '# Some stuff:'
+```
+
+Insert ToC into files, print summary to console:
+```bash
+./src/toc.py -r notes/stuff -e README.md ignore/notes -s 1 -t 2 -i --summary --summary-heading '# Some stuff:'
+```
+
+Write summary to `README.md`:
+```bash
+./src/toc.py -r notes/stuff -e README.md ignore/notes -s 1 -t 2 -i --summary --summary-heading '# Some stuff:' --summary-path README.md
+```

markdown_toc_generator-1.0.0/README.md

@@ -0,0 +1,98 @@
+# Markdown Table of Contents generator
+
+Basic Markdown Table of Contents generator written in `Python`.
+
+The script generates ToC in a form of a nested list based on headings in Markdown files.
+The ToC can be printed to console, or inserted/updated into analyzed files.
+
+> **Warning**: Inserting/updating ToC into the files can be destructive, as entire file is read, ToC is inserted/updated, then entire file is overwritten. The remaining contents of the file shouldn't be affected, but be careful.
+
+The project is managed by [uv](https://docs.astral.sh/uv/).
+
+
+## Usage
+
+The main script is `toc.py`, it has a built-in help with all parameters described:
+```bash
+./src/toc.py --help
+```
+
+
+### Arguments
+
+ * **`--root`, `-r`** - **required**, path in which files will be analyzed (recursively)
+ * **`--exclude`, `-e`** - paths to files, or directories, which should be excluded from analysis, **relative to root**
+ * **`--in-place`, `-i`** - update analyzed files with generated ToC, **potentially destructive** and will request confirmation before any changes are done
+ * **`--force`, `-f`** - skip confirmation for potentially destructive operations, like for `--in-place` flag
+ * **`--skip`, `-s`** - skip *n* highest level headings from generated ToC
+ * **`--take`, `-t`** - control how many headings are inserted into the ToC, starting from not-skipped by `--skip` - e.g. `--skip 1 --take 2` will include levels 2-4
+ * **`--toc-regex`** - regex used for updating/inserting ToC into files when using `--in-place` flag
+ * **`--summary`** - generate summary from all analyzed headings into one output - all ToCs with their respective files generated into one Markdown output
+ * **`--summary-path`** - write the generated summary to a file under passed path (`--in-place` flag is still required), **potentially very destructive** as the summary will overwrite everything in that file; this path is automatically excluded; **NOT relative to root**
+ * **`--summary-heading`** - prefix added to the generated summary as the highest level heading
+
+
+### ToC regular expression
+
+The default regex used to insert ToC into the file itself is:
+```
+^(#[^#].+)$(\s*-.+\n)*\s*
+```
+It will look for the first heading available and treat the list right after it as the ToC to replace. So by default the script assumes, that file structure will be something like:
+
+```markdown
+# First heading in file (but doesn't have to be level 1)
+
+- First element of ToC
+  - First subelement of ToC
+- Second element of ToC
+
+Something else, not a list, which won't be modified.
+The rest of the file doesn't matter.
+```
+
+These regexes should include two groups - first looks for the section right before the ToC (which won't be modified in the resulting file), the second looks for the ToC itself (which will be replaced).
+
+
+### Summary
+
+The generated summary will have a structure of:
+
+```markdown
+Summary heading as per `--summary-heading` flag, or "# Summary:" by default
+
+## Link to directory with notes, text is the directory name
+
+### Link to a note, text is taken from the heading level 1 from that note
+
+- [Heading 2 name](link to file and section)
+ - [Heading 3 name](link to file and section)
+- [Heading 2 name](link to file and section)
+```
+
+And so on.
+
+When flags `--in-place` and `--summary-path PATH_TO_FILE` are passed the resulting summary will be written to `PATH_TO_FILE` as is overwritting everything else in the file, so **it can be very destructive**.
+
+
+### Examples
+
+Generate ToC based on files in `notes/stuff` subdirectory, except for `README.md` and files under `ignore/notes`; ignore the highest level heading and include only 2 levels after that; only print to console, without summary:
+```bash
+./src/toc.py -r notes/stuff -e README.md ignore/notes -s 1 -t 2
+```
+
+The same as above, but print a summary as well, with `# Some stuff:` prefix:
+```bash
+./src/toc.py -r notes/stuff -e README.md ignore/notes -s 1 -t 2 --summary --summary-heading '# Some stuff:'
+```
+
+Insert ToC into files, print summary to console:
+```bash
+./src/toc.py -r notes/stuff -e README.md ignore/notes -s 1 -t 2 -i --summary --summary-heading '# Some stuff:'
+```
+
+Write summary to `README.md`:
+```bash
+./src/toc.py -r notes/stuff -e README.md ignore/notes -s 1 -t 2 -i --summary --summary-heading '# Some stuff:' --summary-path README.md
+```

markdown_toc_generator-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "markdown-toc-generator"
+authors = [{name = "Electronic Mango", email = "78230210+Electronic-Mango@users.noreply.github.com"}]
+version = "1.0.0"
+description = "Python scripts generating Table of Contents from markdown headers."
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.14"
+keywords = ["Markdown", "ToC", "toc", "table-of-contents", "Table of Contents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Electronic-Mango/markdown-toc-generator"
+Documentation = "https://electronic-mango.github.io/markdown-toc-generator"
+Repository = "https://github.com/Electronic-Mango/markdown-toc-generator"
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12"]
+build-backend = "uv_build"
+
+[project.scripts]
+markdown_toc_generator = "markdown_toc_generator.toc:main"
+
+[dependency-groups]
+dev = [
+    "black>=26.3.1",
+    "flake8>=7.3.0",
+    "isort>=8.0.1",
+]

markdown_toc_generator-1.0.0/src/markdown_toc_generator/__main__.py

@@ -0,0 +1,3 @@
+if __name__ == "__main__":
+    from markdown_toc_generator.toc import main
+    main()

markdown_toc_generator-1.0.0/src/markdown_toc_generator/arguments.py

@@ -0,0 +1,93 @@
+from argparse import ArgumentParser, Namespace
+from pathlib import Path
+
+TOC_REGEX = r"^(#[^#].+)$(\s*-.+\n)*\s*"
+
+
+def parse_arguments() -> Namespace:
+    parser = ArgumentParser(
+        description=(
+            "Markdown Table-of-Contents generator, print them to console, "
+            "or insert them into Markdown files themselves"
+        )
+    )
+    parser.add_argument(
+        "-r",
+        "--root",
+        type=Path,
+        default=Path(),
+        help="set root path for all operations, by default current path is used",
+    )
+    parser.add_argument(
+        "-e",
+        "--exclude",
+        type=Path,
+        nargs="*",
+        default=[],
+        help=(
+            "paths (relative to root) which should be excluded from analysis, "
+            "can be single files, can be entire directories"
+        ),
+    )
+    parser.add_argument(
+        "-i",
+        "--in-place",
+        action="store_true",
+        help=(
+            "insert generated ToC into the files, POTENTIALLY DESCTRUCTIVE operation "
+            "as entire contents of the file is read, ToC is inserted, "
+            "then entire file is overwritten"
+        ),
+    )
+    parser.add_argument(
+        "-f",
+        "--force",
+        action="store_true",
+        help="skip confirmation for potentially destructive operations (e.g. for --in-place flag)",
+    )
+    parser.add_argument(
+        "-s",
+        "--skip",
+        type=int,
+        default=0,
+        help="how many levels should be skipped from ToC (starting at the highest)",
+    )
+    parser.add_argument(
+        "-t",
+        "--take",
+        type=int,
+        default=0,
+        help=(
+            "how many levels should be added to ToC (starting from the highest) "
+            "relative to --take ('--skip 1 --take 3' results in levels 2-4 to be included in ToC)"
+        ),
+    )
+    parser.add_argument(
+        "--toc-regex",
+        default=TOC_REGEX,
+        help=(
+            "regex used to insert ToC into file with --in-place, "
+            "first capture group looks for a 'prefix' string for the ToC (which is preserved), "
+            "the second one looks for the ToC itself (which will be replaced), "
+            f"'{TOC_REGEX}' used by default"
+        ),
+    )
+    parser.add_argument(
+        "--summary", action="store_true", help="generate summary of all analyzed files"
+    )
+    parser.add_argument(
+        "--summary-path",
+        type=Path,
+        help=(
+            "insert the generated summary into a file (--in-place flag is still required), "
+            "POTENTIALLY VERY DESCTRUCTIVE as entire file will be replaced by the summary, "
+            "no smart analysis is done, entire file is rewritten"
+        ),
+    )
+    parser.add_argument(
+        "--summary-heading",
+        type=str,
+        default="# Summary:",
+        help="main heading used for generated summary",
+    )
+    return parser.parse_args()

markdown_toc_generator-1.0.0/src/markdown_toc_generator/heading.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+from typing import NamedTuple
+from urllib.parse import quote
+
+
+class Heading(NamedTuple):
+    level: int
+    name: str
+    path: Path
+    section_link: str
+
+    def str(self, skip: int, section_only: bool) -> str:
+        list_prefix = " " * (self.level - skip - 1) * 2
+        file_link = quote(str(self.path)) if not section_only else ""
+        return f"{list_prefix}- [{self.name}]({file_link}{self.section_link})"

markdown_toc_generator-1.0.0/src/markdown_toc_generator/output_toc.py

@@ -0,0 +1,82 @@
+from itertools import groupby
+from os import linesep
+from pathlib import Path
+from re import MULTILINE, sub
+from urllib.parse import quote
+
+from markdown_toc_generator.heading import Heading
+
+
+def handle_file_toc(
+    heading_data: dict[Path, list[Heading]], skip: int, take: int, in_place: bool, toc_regex: str
+) -> None:
+    for path, headings in heading_data.items():
+        if not (toc := format_headings(headings, skip, take, True)):
+            continue
+        if in_place:
+            insert_toc(path, toc, toc_regex)
+        else:
+            print(f"{path}:{linesep}{toc}{linesep}")
+
+
+def handle_summary_toc(
+    heading_data: dict[Path, list[Heading]],
+    skip: int,
+    take: int,
+    in_place: bool,
+    target_path: Path | None,
+    main_heading: str,
+) -> None:
+    all_paths = {path for full_path in heading_data for path in full_path.parents[:-1]}
+    all_paths = sorted(all_paths, key=lambda path: (path, len(path.parents)))
+    heading_data_per_directory = {
+        group[0]: dict(values).values()
+        for group, values in groupby(heading_data.items(), lambda item: item[0].parents[:-1])
+    }
+    expanded_heading_data = {path: heading_data_per_directory.get(path, []) for path in all_paths}
+    toc = ""
+    for dir_path, dir_headings in expanded_heading_data.items():
+        level = 2
+        toc += format_path_heading(dir_path, level)
+        for file_headings in dir_headings:
+            # toc += format_path_heading(file_path, level + 1)
+            first_heading = file_headings[0]
+            toc += f"{'#' * (level + 1)}{first_heading.str(0, False)[1:]}{linesep * 2}"
+            toc += format_headings(file_headings, skip, take, False)
+            toc += linesep * 2
+    if in_place and target_path and target_path.is_file():
+        print(f"Updating {target_path}")
+        with open(target_path, "w") as file:
+            file.write(f"{main_heading}{linesep * 2}{toc}")
+    else:
+        print(f"{linesep * 2}{main_heading}{linesep * 2}{toc}{linesep}")
+
+
+def format_headings(headings: list[Heading], skip: int, take: int, section_only: bool) -> str:
+    return linesep.join(
+        heading.str(skip, section_only)
+        for heading in headings
+        if level_in_range(heading.level, skip, take)
+    )
+
+
+def level_in_range(level: int, skip: int, take: int) -> bool:
+    return (level > skip and level <= (take + skip)) if take else (level > skip)
+
+
+def insert_toc(path: Path, toc: str, toc_regex: str) -> None:
+    toc = (linesep * 2) + toc + (linesep * 3)
+    with open(path, "r") as file:
+        text = file.read()
+    if toc in text:
+        print(f"No changes made to: {path}")
+        return
+    print(f"Updating ToC in: {path}")
+    sub_regex = rf"\1{toc}"
+    new_text = sub(toc_regex, sub_regex, text, count=1, flags=MULTILINE)
+    with open(path, "w") as file:
+        file.write(new_text)
+
+
+def format_path_heading(path: Path, level: int) -> str:
+    return f"{'#' * level} [{path.name}]({quote(str(path))}){linesep * 2}"

markdown_toc_generator-1.0.0/src/markdown_toc_generator/parse_headings.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+from re import search, sub
+
+from markdown_toc_generator.heading import Heading
+
+HEADER_REGEX = r"^(#+) (.+)"
+CODE_BLOCK_REGEX = r"^```"
+
+
+def parse_headings_from_file(path: Path) -> list[Heading]:
+    with open(path, "r") as file:
+        text = file.readlines()
+    headings = get_all_headings(text)
+    return [Heading(level, name, path, create_section_link(name)) for level, name in headings]
+
+
+def get_all_headings(lines: list[str]) -> list[tuple[int, str]]:
+    headings = []
+    is_code_block = False
+    for line in lines:
+        if search(CODE_BLOCK_REGEX, line):
+            is_code_block = not is_code_block
+        if is_code_block:
+            continue
+        if match := search(HEADER_REGEX, line):
+            headings.append((len(match.group(1)), match.group(2)))
+    return headings
+
+
+def create_section_link(name: str) -> str:
+    section_link = sub(r"[^0-9a-z-_ ]", "", name.lower()).replace(" ", "-")
+    return f"#{section_link}"

markdown_toc_generator-1.0.0/src/markdown_toc_generator/toc.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+
+from pathlib import Path
+
+from markdown_toc_generator.arguments import parse_arguments
+from markdown_toc_generator.heading import Heading
+from markdown_toc_generator.output_toc import handle_file_toc, handle_summary_toc
+from markdown_toc_generator.parse_headings import parse_headings_from_file
+
+
+def main():
+    args = parse_arguments()
+    root = args.root.absolute()
+    normalized_excludes = get_all_excludes(root, args.exclude, args.summary_path)
+    in_place = verify_in_place(args.in_place, args.force)
+    notes_paths = get_all_notes_paths(root, normalized_excludes)
+    notes_paths.sort(key=lambda path: (len(path.parents), path))
+    heading_data = parse_all_headings(notes_paths)
+    handle_file_toc(heading_data, args.skip, args.take, in_place, args.toc_regex)
+    if args.summary or args.summary_path:
+        handle_summary_toc(heading_data, 1, 1, in_place, args.summary_path, args.summary_heading)
+
+
+def normalize(root: Path, path: Path) -> Path:
+    return path.absolute().relative_to(root)
+
+
+def get_all_excludes(root: Path, exclude: list[Path], readme: Path | None) -> set[Path]:
+    return {normalize(root, path) for path in exclude + [readme] if path}
+
+
+def verify_in_place(in_place: bool, force: bool) -> bool:
+    if not in_place or force:
+        return in_place
+    return input(
+        "Changing files in-place can lead to data loss, use at your own risk. "
+        "Continue with changes in-place? [y/n] "
+    ).lower() in ("y", "yes")
+
+
+def get_all_notes_paths(root: Path, exclude: set[Path]) -> list[Path]:
+    return [
+        normalize(root, path)
+        for path in root.rglob("*.md")
+        if not any(check_excluded_path(normalize(root, path), excluded) for excluded in exclude)
+    ]
+
+
+def check_excluded_path(path: Path, excluded: Path) -> bool:
+    return path == excluded if excluded.is_file() else excluded in path.parents
+
+
+def parse_all_headings(notes_paths: list[Path]) -> dict[Path, list[Heading]]:
+    return {path: parse_headings_from_file(path) for path in notes_paths}
+
+
+if __name__ == "__main__":
+    main()