{"id":13462290,"url":"https://github.com/ekalinin/github-markdown-toc","last_synced_at":"2025-05-14T14:07:23.345Z","repository":{"id":20310419,"uuid":"23584347","full_name":"ekalinin/github-markdown-toc","owner":"ekalinin","description":"Easy TOC creation for GitHub README.md","archived":false,"fork":false,"pushed_at":"2024-10-12T19:30:59.000Z","size":174,"stargazers_count":3265,"open_issues_count":26,"forks_count":2742,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-04-28T13:58:40.665Z","etag":null,"topics":["github","markdown","shell","table-of-contents","toc"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/ekalinin.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":"2014-09-02T15:33:16.000Z","updated_at":"2025-04-26T16:08:37.000Z","dependencies_parsed_at":"2023-01-13T20:54:09.844Z","dependency_job_id":"c4f9ff80-8a4c-4099-9b0b-219eb7bb22da","html_url":"https://github.com/ekalinin/github-markdown-toc","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekalinin%2Fgithub-markdown-toc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekalinin%2Fgithub-markdown-toc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekalinin%2Fgithub-markdown-toc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekalinin%2Fgithub-markdown-toc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ekalinin","download_url":"https://codeload.github.com/ekalinin/github-markdown-toc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254159186,"owners_count":22024558,"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":["github","markdown","shell","table-of-contents","toc"],"created_at":"2024-07-31T12:00:43.869Z","updated_at":"2025-05-14T14:07:23.290Z","avatar_url":"https://github.com/ekalinin.png","language":"Shell","readme":"gh-md-toc\n=========\n\n[![CI](https://github.com/ekalinin/github-markdown-toc/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/ekalinin/github-markdown-toc/actions/workflows/ci.yml)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/ekalinin/github-markdown-toc)\n\ngh-md-toc — is for you if you **want to generate TOC** (Table Of Content) for a README.md or\na GitHub wiki page **without installing additional software**.\n\nIt's my try to fix a problem:\n\n  * [github/issues/215](https://github.com/isaacs/github/issues/215)\n\ngh-md-toc is able to process:\n\n  * stdin\n  * local files (markdown files in local file system)\n  * remote files (html files on github.com)\n\ngh-md-toc tested on Ubuntu, and macOS High Sierra (gh-md-toc release 0.4.9). If you want it on Windows, you\nbetter to use a golang based implementation:\n\n  * [github-markdown-toc.go](https://github.com/ekalinin/github-markdown-toc.go)\n\nIt's more solid, reliable and with ability of a parallel processing. And\nabsolutely without dependencies.\n\nTable of contents\n=================\n\n\u003c!--ts--\u003e\n   * [Installation](#installation)\n   * [Usage](#usage)\n      * [STDIN](#stdin)\n      * [Local files](#local-files)\n      * [Remote files](#remote-files)\n      * [Multiple files](#multiple-files)\n      * [Combo](#combo)\n      * [Auto insert and update TOC](#auto-insert-and-update-toc)\n      * [GitHub token](#github-token)\n      * [TOC generation with Github Actions](#toc-generation-with-github-actions)\n   * [Tests](#tests)\n   * [Dependency](#dependency)\n   * [Docker](#docker)\n     * [Local](#local)\n     * [Public](#public)\n\u003c!--te--\u003e\n\n\nInstallation\n============\n\nLinux (manual installation)\n```bash\n$ wget https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc\n$ chmod a+x gh-md-toc\n```\n\nMacOS (manual installation)\n```bash\n$ curl https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc -o gh-md-toc\n$ chmod a+x gh-md-toc\n```\n\nLinux or MacOS (using [Basher](https://github.com/basherpm/basher))\n```bash\n$ basher install ekalinin/github-markdown-toc\n# `gh-md-toc` will automatically be available in the PATH\n```\n\nUsage\n=====\n\n\nSTDIN\n-----\n\nHere's an example of TOC creating for markdown from STDIN:\n\n```bash\n➥ cat ~/projects/Dockerfile.vim/README.md | ./gh-md-toc -\n  * [Dockerfile.vim](#dockerfilevim)\n  * [Screenshot](#screenshot)\n  * [Installation](#installation)\n        * [OR using Pathogen:](#or-using-pathogen)\n        * [OR using Vundle:](#or-using-vundle)\n  * [License](#license)\n```\n\nLocal files\n-----------\n\nHere's an example of TOC creating for a local README.md:\n\n```bash\n➥ ./gh-md-toc ~/projects/Dockerfile.vim/README.md\n\n\nTable of Contents\n=================\n\n  * [Dockerfile.vim](#dockerfilevim)\n  * [Screenshot](#screenshot)\n  * [Installation](#installation)\n        * [OR using Pathogen:](#or-using-pathogen)\n        * [OR using Vundle:](#or-using-vundle)\n  * [License](#license)\n```\n\nRemote files\n------------\n\nAnd here's an example, when you have a README.md like this:\n\n  * [README.md without TOC](https://github.com/ekalinin/envirius/blob/f939d3b6882bfb6ecb28ef7b6e62862f934ba945/README.md)\n\nAnd you want to generate TOC for it.\n\nThere is nothing easier:\n\n```bash\n➥ ./gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md\n\nTable of Contents\n=================\n\n  * [envirius](#envirius)\n    * [Idea](#idea)\n    * [Features](#features)\n  * [Installation](#installation)\n  * [Uninstallation](#uninstallation)\n  * [Available plugins](#available-plugins)\n  * [Usage](#usage)\n    * [Check available plugins](#check-available-plugins)\n    * [Check available versions for each plugin](#check-available-versions-for-each-plugin)\n    * [Create an environment](#create-an-environment)\n    * [Activate/deactivate environment](#activatedeactivate-environment)\n      * [Activating in a new shell](#activating-in-a-new-shell)\n      * [Activating in the same shell](#activating-in-the-same-shell)\n    * [Get list of environments](#get-list-of-environments)\n    * [Get current activated environment](#get-current-activated-environment)\n    * [Do something in environment without enabling it](#do-something-in-environment-without-enabling-it)\n    * [Get help](#get-help)\n    * [Get help for a command](#get-help-for-a-command)\n  * [How to add a plugin?](#how-to-add-a-plugin)\n    * [Mandatory elements](#mandatory-elements)\n      * [plug_list_versions](#plug_list_versions)\n      * [plug_url_for_download](#plug_url_for_download)\n      * [plug_build](#plug_build)\n    * [Optional elements](#optional-elements)\n      * [Variables](#variables)\n      * [Functions](#functions)\n    * [Examples](#examples)\n  * [Example of the usage](#example-of-the-usage)\n  * [Dependencies](#dependencies)\n  * [Supported OS](#supported-os)\n  * [Tests](#tests)\n  * [Version History](#version-history)\n  * [License](#license)\n  * [README in another language](#readme-in-another-language)\n```\n\nThat's all! Now all you need — is copy/paste result from console into original\nREADME.md.\n\nIf you do not want to copy from console you can add `\u003e YOURFILENAME.md` at the end of the command like `./gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md \u003e table-of-contents.md` and this will store the table of contents to a file named table-of-contents.md in your current folder.\n\nAnd here is a result:\n\n  * [README.md with TOC](https://github.com/ekalinin/envirius/blob/24ea3be0d3cc03f4235fa4879bb33dc122d0ae29/README.md)\n\nMoreover, it's able to work with GitHub's wiki pages:\n\n```bash\n➥ ./gh-md-toc https://github.com/ekalinin/nodeenv/wiki/Who-Uses-Nodeenv\n\nTable of Contents\n=================\n\n  * [Who Uses Nodeenv?](#who-uses-nodeenv)\n    * [OpenStack](#openstack)\n    * [pre-commit.com](#pre-commitcom)\n```\n\nMultiple files\n--------------\n\nIt supports multiple files as well:\n\n```bash\n➥ ./gh-md-toc \\\n    https://github.com/aminb/rust-for-c/blob/master/hello_world/README.md \\\n    https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md \\\n    https://github.com/aminb/rust-for-c/blob/master/primitive_types_and_operators/README.md \\\n    https://github.com/aminb/rust-for-c/blob/master/unique_pointers/README.md\n\n  * [Hello world](https://github.com/aminb/rust-for-c/blob/master/hello_world/README.md#hello-world)\n\n  * [Control Flow](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#control-flow)\n    * [If](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#if)\n    * [Loops](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#loops)\n    * [For loops](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#for-loops)\n    * [Switch/Match](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#switchmatch)\n    * [Method call](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#method-call)\n\n  * [Primitive Types and Operators](https://github.com/aminb/rust-for-c/blob/master/primitive_types_and_operators/README.md#primitive-types-and-operators)\n\n  * [Unique Pointers](https://github.com/aminb/rust-for-c/blob/master/unique_pointers/README.md#unique-pointers)\n```\n\nCombo\n-----\n\nYou can easily combine both ways:\n\n```bash\n➥ ./gh-md-toc \\\n    ~/projects/Dockerfile.vim/README.md \\\n    https://github.com/ekalinin/sitemap.s/blob/master/README.md\n\n  * [Dockerfile.vim](~/projects/Dockerfile.vim/README.md#dockerfilevim)\n  * [Screenshot](~/projects/Dockerfile.vim/README.md#screenshot)\n  * [Installation](~/projects/Dockerfile.vim/README.md#installation)\n        * [OR using Pathogen:](~/projects/Dockerfile.vim/README.md#or-using-pathogen)\n        * [OR using Vundle:](~/projects/Dockerfile.vim/README.md#or-using-vundle)\n  * [License](~/projects/Dockerfile.vim/README.md#license)\n\n  * [sitemap.js](https://github.com/ekalinin/sitemap.js/blob/master/README.md#sitemapjs)\n    * [Installation](https://github.com/ekalinin/sitemap.js/blob/master/README.md#installation)\n    * [Usage](https://github.com/ekalinin/sitemap.js/blob/master/README.md#usage)\n    * [License](https://github.com/ekalinin/sitemap.js/blob/master/README.md#license)\n\n\u003c!-- Created by https://github.com/ekalinin/github-markdown-toc --\u003e\n```\n\nAuto insert and update TOC\n--------------------------\n\nJust put into a file these two lines:\n\n```\n\u003c!--ts--\u003e\n\u003c!--te--\u003e\n```\n\nAnd run:\n\n```bash\n$ ./gh-md-toc --insert README.test.md\n\nTable of Contents\n=================\n\n   * [gh-md-toc](#gh-md-toc)\n   * [Installation](#installation)\n   * [Usage](#usage)\n      * [STDIN](#stdin)\n      * [Local files](#local-files)\n      * [Remote files](#remote-files)\n      * [Multiple files](#multiple-files)\n      * [Combo](#combo)\n   * [Tests](#tests)\n   * [Dependency](#dependency)\n\n!! TOC was added into: 'README.test.md'\n!! Origin version of the file: 'README.test.md.orig.2018-02-04_192655'\n!! TOC added into a separate file: 'README.test.md.toc.2018-02-04_192655'\n\n\n\u003c!-- Created by https://github.com/ekalinin/github-markdown-toc --\u003e\n```\n\nNow check the same file:\n\n```bash\n➜ grep -A15 \"\u003c\\!\\-\\-ts\" README.test.md\n\u003c!--ts--\u003e\n   * [gh-md-toc](#gh-md-toc)\n   * [Table of contents](#table-of-contents)\n   * [Installation](#installation)\n   * [Usage](#usage)\n      * [STDIN](#stdin)\n      * [Local files](#local-files)\n      * [Remote files](#remote-files)\n      * [Multiple files](#multiple-files)\n      * [Combo](#combo)\n      * [Auto insert and update TOC](#auto-insert-and-update-toc)\n   * [Tests](#tests)\n   * [Dependency](#dependency)\n\n\u003c!-- Added by: \u003cyour-user\u003e, at: 2018-02-04T19:38+03:00 --\u003e\n\n\u003c!--te--\u003e\n```\n\nNext time when your file will be changed just repeat the command (`./gh-md-toc\n--insert ...`) and TOC will be refreshed again.\n\nGitHub token\n------------\n\nAll your tokens are [here](https://github.com/settings/tokens).\n\nYou will need them if you get an error like this:\n\n```\nParsing local markdown file requires access to github API\nError: You exceeded the hourly limit. See: https://developer.github.com/v3/#rate-limiting\nor place github auth token here: ./token.txt\n```\n\nA token can be used as an env variable:\n\n```bash\n➥ GH_TOC_TOKEN=2a2dab...563 ./gh-md-toc README.md\n\nTable of Contents\n=================\n\n* [github\\-markdown\\-toc](#github-markdown-toc)\n* [Table of Contents](#table-of-contents)\n* [Installation](#installation)\n* [Tests](#tests)\n* [Usage](#usage)\n* [LICENSE](#license)\n```\n\nOr from a file:\n\n```bash\n➥ echo \"2a2dab...563\" \u003e ./token.txt\n➥ ./gh-md-toc README.md\n\nTable of Contents\n=================\n\n* [github\\-markdown\\-toc](#github-markdown-toc)\n* [Table of Contents](#table-of-contents)\n* [Installation](#installation)\n* [Tests](#tests)\n* [Usage](#usage)\n* [LICENSE](#license)\n```\n\nTOC generation with Github Actions\n----------------------------------\n\nConfig:\n\n```yaml\non:\n  push:\n    branches: [main]\n    paths: ['foo.md']\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    timeout-minutes: 5\n    steps:\n      - uses: actions/checkout@v2\n      - run: |\n          curl https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc -o gh-md-toc\n          chmod a+x gh-md-toc\n          ./gh-md-toc --insert --no-backup --hide-footer foo.md\n          rm gh-md-toc\n      - uses: stefanzweifel/git-auto-commit-action@v4\n        with:\n          commit_message: Auto update markdown TOC\n```\n\nTests\n=====\n\nDone with [bats](https://github.com/bats-core/bats-core).\nUseful articles:\n\n  * https://www.engineyard.com/blog/how-to-use-bats-to-test-your-command-line-tools/\n  * http://blog.spike.cx/post/60548255435/testing-bash-scripts-with-bats\n\n\nHow to run tests:\n\n```bash\n➥ make test                                                                                                                 \n\n ✓ TOC for local README.md\n ✓ TOC for remote README.md\n ✓ TOC for mixed README.md (remote/local)\n ✓ TOC for markdown from stdin\n ✓ --help\n ✓ --version\n\n6 tests, 0 failures\n```\n\nDependency\n==========\n\n  * curl or wget\n  * awk (mawk is not tested)\n  * grep\n  * sed\n  * bats (for unit tests)\n\nTested on Ubuntu 14.04/14.10 in bash/zsh.\n\nDocker\n======\n\nLocal\n-----\n\n* Build\n\n```shell\n$ docker build -t markdown-toc-generator .\n```\n\n* Run on an URL\n\n```shell\n$ docker run -it markdown-toc-generator https://github.com/ekalinin/envirius/blob/master/README.md\n```\n\n* Run on a local file (need to share volume with docker)\n\n```shell\n$ docker run -it -v /data/ekalinin/envirius:/data markdown-toc-generator /data/README.md\n```\n\nPublic\n-------\n\n```shell\n$ docker pull evkalinin/gh-md-toc:0.7.0\n\n$ docker images | grep toc\nevkalinin/gh-md-toc                       0.7.0 0b8db6aed298        11 minutes ago      147MB\n\n$ docker run -it evkalinin/gh-md-toc:0.7.0 \\\n    https://github.com/ekalinin/envirius/blob/master/README.md\n```\n","funding_links":[],"categories":["Uncategorized","Shell","🔥 Contribution","shell","HarmonyOS","Credits","Table of Contents"],"sub_categories":["Uncategorized","🤖 ETAPI programs","Windows Manager","International Startups"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fekalinin%2Fgithub-markdown-toc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fekalinin%2Fgithub-markdown-toc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fekalinin%2Fgithub-markdown-toc/lists"}