{"id":15048508,"url":"https://github.com/ralf-tischer/md-toc","last_synced_at":"2026-02-13T10:38:58.376Z","repository":{"id":228430950,"uuid":"770478949","full_name":"ralf-tischer/md-toc","owner":"ralf-tischer","description":"A command line tool to automatically create tables of content (TOC) for markdown files with the file extension .md.","archived":false,"fork":false,"pushed_at":"2025-01-03T18:30:23.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-22T08:53:51.765Z","etag":null,"topics":["command-line","markdown","markdown-parser","md","python","toc","toc-generator","tool"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ralf-tischer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-11T16:13:44.000Z","updated_at":"2025-01-03T18:30:27.000Z","dependencies_parsed_at":"2024-06-03T20:58:32.732Z","dependency_job_id":"8280eccd-dac4-483d-a930-16e7122cea11","html_url":"https://github.com/ralf-tischer/md-toc","commit_stats":null,"previous_names":["ralftischer/md-toc","coder-ratz/md-toc","ralf-tischer/md-toc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ralf-tischer/md-toc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralf-tischer%2Fmd-toc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralf-tischer%2Fmd-toc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralf-tischer%2Fmd-toc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralf-tischer%2Fmd-toc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ralf-tischer","download_url":"https://codeload.github.com/ralf-tischer/md-toc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralf-tischer%2Fmd-toc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272936489,"owners_count":25018177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","markdown","markdown-parser","md","python","toc","toc-generator","tool"],"created_at":"2024-09-24T21:13:36.968Z","updated_at":"2026-02-13T10:38:53.336Z","avatar_url":"https://github.com/ralf-tischer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MD-TOC\n\n| Ralf Tischer 2024-2025\n\nA command line tool to automatically create tables of content (TOC) for markdown files with the file extension `.md`. \n\n\u003c!-- MD-TOC START LEVEL 99 --\u003e\n\n## Table of Contents\n\n  - [Usage](#usage)\n    - [Clone Script](#clone-script)\n    - [Run Script](#run-script)\n    - [Prepare Markdown File](#prepare-markdown-file)\n    - [Include External TOCs](#include-external-tocs)\n  - [Examples](#examples)\n  - [Author](#author)\n\n\u003c!-- MD-TOC END --\u003e\n\n## Usage\n\n### Clone Script\n\nCopy `md_toc.py` to main path of local directory. \n\n* Fork\n\nFork this repository in GitHub and `git clone` into a local folder. \n\n* Standard\n\n  ```bash\n  wget https://raw.githubusercontent.com/ralf-tischer/md-toc/main/md_toc.py\n  ```\n\n* Powershell\n\n  In Powershell use `Invoke-WebRequest -Uri` to download:\n\n  ```bash\n  Invoke-WebRequest -Uri \"https://raw.githubusercontent.com/ralf-tischer/md-toc/main/md_toc.py\" -OutFile \"md_toc.py\"\n  ```\n### Run Script\n\nStart _MD-TOC_ from command line. \n```bash\npython ./md_toc.py -f README.md\n```\n\nOptions:\n* `-f` or `--files`: list of files, optional\n* `-p` or `--paths`: list of paths, optional\n* `-s` or `--sub`: if set, browse all paths sub-directories, optional\n* `-l` or `--level`: maximum level of headings to be included to TOC, optional, default=99\n* `-v` or `--verbose`: print some details to console \n\nWhen finished, delete the local copy of _MD-TOC_:\n```bash\nrm md_toc.py\n```\n\n### Prepare Markdown File\n\nThe _MD-TOC_ script browses through the markdown file and search for (not printed) tokens. These tokens mark beginning and end of an existing table of content. \nIf the tokens are found, _MD-TOC_ starts parsing after the end token. So any heading before the TOC - including the title - will not be included to the new TOC.\nIf not set, the tokens are automatically added by the script and the TOC is placed at the beginning of the file. \nAlternatively, the `START` and `END` tokens can be placed in the file manually. Level specifies the number of heading levels to be included to the TOC:\n\n```bash\n\u003c!-- MD-TOC START LEVEL 3 --\u003e\n\nAll text between the tokens will be overwritten by the new table of content.\n\n\u003c!-- MD-TOC END --\u003e\n\n``` \n### Include External TOCs\n\n_MD-TOC_ can include tables of content from external files. This allows to collect anchor links from several different files in the current TOC like bookmarks.\nExternal tables are included into the main TOC. Each has its own level of detail to be displayed. \nExternal TOCs are simplified in a way that further sub-TOCs will be ignored (no recursion will appear).\n\nThe invisible `INCLUDE` tokens are placed between `START` and `END` and specify filename (including relative path, if there is any) and `LEVEL`. \n\n```bash\n\u003c!-- MD-TOC START LEVEL 3 --\u003e\n\u003c!-- MD-TOC INCLUDE details.md LEVEL 3 --\u003e\n\u003c!-- MD-TOC INCLUDE more/details_db.md LEVEL 2 --\u003e\n\nAll text between the tokens will be overwritten by the new table of content.\n\n\u003c!-- MD-TOC END --\u003e\n```\n\n## Examples\n\nCreate TOC for `README.md` and `describe.py` to level 3:\n```bash\npython ./md_toc.py -f README.md describe.py --level 3\n```\n\nCreate TOC for all `.md` files in current directory with all levels:\n```bash\npython ./md_toc.py -p \".\"\n```\n\nCreate TOC for all `.md` files in `path/` directory including all subdirectories with all levels:\n```bash\npython ./md_toc.py -p \"path/\" -s\n```\n## Author\n\n| Ralf Tischer, 2024-2025\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fralf-tischer%2Fmd-toc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fralf-tischer%2Fmd-toc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fralf-tischer%2Fmd-toc/lists"}