{"id":19853989,"url":"https://github.com/eugene-khyst/md-toc-cli","last_synced_at":"2025-06-26T23:05:50.689Z","repository":{"id":52246214,"uuid":"362407784","full_name":"eugene-khyst/md-toc-cli","owner":"eugene-khyst","description":"Automatically insert or update a clickable table of contents (TOC) into your Markdown documents based on its headings using CLI or JavaScript module. Perfect support for README.md files on GitHub.","archived":false,"fork":false,"pushed_at":"2024-02-21T08:30:33.000Z","size":279,"stargazers_count":4,"open_issues_count":1,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-15T19:23:28.529Z","etag":null,"topics":["cli","markdown","nodejs","npm","npm-package","table-of-contents","tableofcontents","toc","toc-generation","toc-generator"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eugene-khyst.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}},"created_at":"2021-04-28T09:16:34.000Z","updated_at":"2023-12-10T05:02:39.000Z","dependencies_parsed_at":"2024-02-21T09:35:59.356Z","dependency_job_id":"21299e89-48e7-4154-bd16-40328f805b4e","html_url":"https://github.com/eugene-khyst/md-toc-cli","commit_stats":null,"previous_names":["eugene-khyst/md-toc-cli","evgeniy-khist/markdown-toc"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eugene-khyst%2Fmd-toc-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eugene-khyst%2Fmd-toc-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eugene-khyst%2Fmd-toc-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eugene-khyst%2Fmd-toc-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eugene-khyst","download_url":"https://codeload.github.com/eugene-khyst/md-toc-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251969236,"owners_count":21673180,"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","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":["cli","markdown","nodejs","npm","npm-package","table-of-contents","tableofcontents","toc","toc-generation","toc-generator"],"created_at":"2024-11-12T14:08:15.679Z","updated_at":"2025-05-02T01:30:26.673Z","avatar_url":"https://github.com/eugene-khyst.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003ca id=\"0\"\u003e\u003c/a\u003eTable of contents generator for Markdown\n\n- [Introduction](#1)\n- [Usage](#2)\n  - [Docker](#2-1)\n  - [npm](#2-2)\n  - [Programmatic](#2-3)\n- [Example](#3)\n\n\u003c!-- Table of contents is made with https://github.com/eugene-khyst/md-toc-cli --\u003e\n\n![npm version](https://img.shields.io/npm/v/md-toc-cli)\n![npm downloads](https://img.shields.io/npm/dt/md-toc-cli)\n![GitHub licence](https://img.shields.io/github/license/eugene-khyst/md-toc-cli)\n\n## \u003ca id=\"1\"\u003e\u003c/a\u003eIntroduction\n\nAutomatically insert or update a clickable table of contents (TOC) into your Markdown documents based on its headings using CLI or JavaScript module with the perfect support for `README.md` files on GitHub.\n\n**md-toc-cli** creates table of contents from level 2-6 headings (e.g., `## Heading`, `### Heading` etc.) and inserts it after level 1 heading or at the beginning of the file.\nZero or one level 1 heading is expected (e.g., `# Heading`).\n\nHTML anchor elements are added to level 1-6 headings to make table of content items clickable, e.g. `\u003ca id=\"...\"\u003e\u003c/a\u003e`.\n\nAnchor at level 1 heading allows creating [Back to top](#0) links as `[Back to top](#0)`.\n\n![md-toc-cli usage](md-toc-cli.svg)\n\n## \u003ca id=\"2\"\u003e\u003c/a\u003eUsage\n\n**md-toc-cli** is available as [npm package](https://www.npmjs.com/package/md-toc-cli) and [Docker image](https://hub.docker.com/r/eugenekhyst/md-toc-cli).\n\n### \u003ca id=\"2-1\"\u003e\u003c/a\u003eDocker\n\nWhen running **md-toc-cli** using Docker, mount the directory containing the Markdown files as a volume.\n\n1. Insert table of contents to the `README.md` file in the current directory\n   ```bash\n   docker run --rm -v .:/markdown eugenekhyst/md-toc-cli -i README.md\n   ```\n2. Read the manual\n\n   ```bash\n   docker run --rm -v .:/markdown eugenekhyst/md-toc-cli --help\n   ```\n\n   ```\n   md-toc-cli [file]\n\n   Automatically insert or update a clickable table of contents (TOC) into your\n   Markdown documents based on its headings (levels 2-6).\n\n   Positionals:\n     file  Markdown file for inserting or updating table of contents in\n                                                    [string] [default: \"README.md\"]\n\n   Options:\n         --version           Show version number                          [boolean]\n         --help              Show help                                    [boolean]\n     -i, --in-place          Edit file in place          [boolean] [default: false]\n     -s, --suffix            The extension of a backup copy. If no extension is\n                             supplied, the original file is overwritten without\n                             making a backup. This option implies -i.      [string]\n     -t, --tab-width         The number of spaces per indentation-level\n                                                              [number] [default: 2]\n     -l, --list-item-symbol  Symbol used in front of line items to create an\n                             unordered list\n                                   [string] [choices: \"-\", \"*\", \"+\"] [default: \"-\"]\n     -n, --no-attribution    Do not add an attribution \"Table of contents is made\n                             with ...\"                   [boolean] [default: false]\n   ```\n\n### \u003ca id=\"2-2\"\u003e\u003c/a\u003enpm\n\nWhen running **md-toc-cli** using Node.js, install the package globally for convenience.\n\n1. Make sure Node.js 18.x LTS or newer is installed.\n2. Install **md-toc-cli** as a global package\n   ```bash\n   npm i -g md-toc-cli\n   ```\n3. Insert table of contents to the `README.md` file in the current directory\n   ```bash\n   md-toc-cli -i README.md\n   ```\n4. Read the manual\n\n   ```bash\n   $ md-toc-cli --help\n   ```\n\n### \u003ca id=\"2-3\"\u003e\u003c/a\u003eProgrammatic\n\n**md-toc-cli** can be used as a library in JavaScript and TypeScript projects.\n\n1. Make sure Node.js 18 or newer is installed.\n2. Install md-toc-cli\n   ```bash\n   npm i md-toc-cli\n   ```\n3. Import md-toc-cli functions\n   ```javascript\n   import { insertOrUpdateToc, insertOrUpdateTocInFile } from 'md-toc-cli';\n   ```\n4. Programmatically insert or update the table of contents in a Markdown string or file\n   ```javascript\n   insertOrUpdateToc(markdownContent, {\n     tabWidth: 2,\n     listItemSymbol: '-',\n     noAttribution: false,\n   });\n   ```\n   ```javascript\n   await insertOrUpdateTocInFile('README.md', {\n     inPlace: false,\n     suffix: 'orig',\n     tabWidth: 2,\n     listItemSymbol: '-',\n     noAttribution: false,\n   });\n   ```\n\n## \u003ca id=\"3\"\u003e\u003c/a\u003eExample\n\n1. Create file `test.md` as follows\n\n   ```markdown\n   # Heading 1\n\n   ## Heading 2a\n\n   ### Heading 3aa\n\n   #### Heading 4a\n\n   ##### Heading 5a\n\n   ###### Heading 6a\n\n   ### Heading 3ab\n\n   ## Heading 2b\n\n   ### Heading 3b\n\n   #### Heading 4b\n\n   ## Heading 2c\n\n   ### Heading 3c\n   ```\n\n2. Insert table of contents to `test.md` and backup the original file\n   ```bash\n   md-toc-cli test.md -i -s 'orig'\n   ```\n3. A backup `test.md.orig` is created for original file `test.md`.\n4. A clickable table of contents is inserted into `test.md`\n\n   ```markdown\n   # \u003ca id=\"0\"\u003e\u003c/a\u003eHeading 1\n\n   - [Heading 2a](#1)\n     - [Heading 3aa](#1-1)\n       - [Heading 4a](#1-1-1)\n         - [Heading 5a](#1-1-1-1)\n           - [Heading 6a](#1-1-1-1-1)\n     - [Heading 3ab](#1-2)\n   - [Heading 2b](#2)\n     - [Heading 3b](#2-1)\n       - [Heading 4b](#2-1-1)\n   - [Heading 2c](#3)\n     - [Heading 3c](#3-1)\n   \n   \u003c!-- Table of contents is made with https://github.com/eugene-khyst/md-toc-cli --\u003e\n\n   ## \u003ca id=\"1\"\u003e\u003c/a\u003eHeading 2a\n\n   ### \u003ca id=\"1-1\"\u003e\u003c/a\u003eHeading 3aa\n\n   #### \u003ca id=\"1-1-1\"\u003e\u003c/a\u003eHeading 4a\n\n   ##### \u003ca id=\"1-1-1-1\"\u003e\u003c/a\u003eHeading 5a\n\n   ###### \u003ca id=\"1-1-1-1-1\"\u003e\u003c/a\u003eHeading 6a\n\n   ### \u003ca id=\"1-2\"\u003e\u003c/a\u003eHeading 3ab\n\n   ## \u003ca id=\"2\"\u003e\u003c/a\u003eHeading 2b\n\n   ### \u003ca id=\"2-1\"\u003e\u003c/a\u003eHeading 3b\n\n   #### \u003ca id=\"2-1-1\"\u003e\u003c/a\u003eHeading 4b\n\n   ## \u003ca id=\"3\"\u003e\u003c/a\u003eHeading 2c\n\n   ### \u003ca id=\"3-1\"\u003e\u003c/a\u003eHeading 3c\n   ```\n\n5. Make any change to the level 2-6 headings (e.g. delete level 5-6 headings and rename level 3 headings).\n6. Update the table of contents in `test.md`\n   ```bash\n   md-toc-cli -i test.md\n   ```\n7. The table of contents in `test.md` is updated according to the level 2-6 headings.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feugene-khyst%2Fmd-toc-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feugene-khyst%2Fmd-toc-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feugene-khyst%2Fmd-toc-cli/lists"}