{"id":13396578,"url":"https://github.com/thlorenz/doctoc","last_synced_at":"2025-05-13T15:09:04.889Z","repository":{"id":3409039,"uuid":"4459367","full_name":"thlorenz/doctoc","owner":"thlorenz","description":"📜 Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated by github or other sites.","archived":false,"fork":false,"pushed_at":"2024-10-27T14:17:00.000Z","size":366,"stargazers_count":4325,"open_issues_count":66,"forks_count":479,"subscribers_count":61,"default_branch":"master","last_synced_at":"2025-05-01T22:39:56.003Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/doctoc","language":"JavaScript","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/thlorenz.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},"funding":{"github":"thlorenz","custom":["paypal.me/thlorenz/25"]}},"created_at":"2012-05-27T02:27:43.000Z","updated_at":"2025-05-01T06:28:31.000Z","dependencies_parsed_at":"2024-01-13T09:35:54.089Z","dependency_job_id":"62dbe7e0-ea4a-438a-b1aa-d0041eb31ced","html_url":"https://github.com/thlorenz/doctoc","commit_stats":{"total_commits":172,"total_committers":32,"mean_commits":5.375,"dds":"0.36046511627906974","last_synced_commit":"95715a3a56fe08fb3d74e53f64b54b25756b31fa"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thlorenz%2Fdoctoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thlorenz%2Fdoctoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thlorenz%2Fdoctoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thlorenz%2Fdoctoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thlorenz","download_url":"https://codeload.github.com/thlorenz/doctoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252118330,"owners_count":21697583,"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":[],"created_at":"2024-07-30T18:00:57.287Z","updated_at":"2025-05-05T21:13:27.466Z","avatar_url":"https://github.com/thlorenz.png","language":"JavaScript","readme":"# DocToc [![Node.js CI](https://github.com/thlorenz/doctoc/actions/workflows/node.js.yml/badge.svg)](https://github.com/thlorenz/doctoc/actions/workflows/node.js.yml)\n\nGenerates table of contents for markdown files inside local git repository. Links are compatible with anchors generated\nby github or other sites via a command line flag.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Adding toc to all files in a directory and sub directories](#adding-toc-to-all-files-in-a-directory-and-sub-directories)\n  - [Update existing doctoc TOCs effortlessly](#update-existing-doctoc-tocs-effortlessly)\n  - [Adding toc to individual files](#adding-toc-to-individual-files)\n    - [Examples](#examples)\n  - [Using doctoc to generate links compatible with other sites](#using-doctoc-to-generate-links-compatible-with-other-sites)\n    - [Example](#example)\n  - [Specifying location of toc](#specifying-location-of-toc)\n  - [Specifying a custom TOC title](#specifying-a-custom-toc-title)\n  - [Specifying a maximum heading level for TOC entries](#specifying-a-maximum-heading-level-for-toc-entries)\n  - [Printing to stdout](#printing-to-stdout)\n  - [Usage as a `git` hook](#usage-as-a-git-hook)\n  - [Docker image](#docker-image)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\n## Installation\n\n    npm install -g doctoc\n\n## Usage\n\nIn its simplest usage, you can pass one or more files or folders to the\n`doctoc` command. This will update the TOCs of each file specified as well as of\neach markdown file found by recursively searching each folder. Below are some\nexamples.\n\n### Adding toc to all files in a directory and sub directories\n\nGo into the directory that contains your local git project and type:\n\n    doctoc .\n\nThis will update all markdown files in the current directory and all its\nsubdirectories with a table of content that will point at the anchors generated\nby the markdown parser. Doctoc defaults to using the GitHub parser, but other\n[modes can be\nspecified](#using-doctoc-to-generate-links-compatible-with-other-sites).\n\n### Ignoring individual files\nIn order to ignore a specific file when running `doctoc` on an entire directory, just add `\u003c!-- DOCTOC SKIP --\u003e` to the top of the file you wish to ignore.\n\n### Update existing doctoc TOCs effortlessly\n\nIf you already have a TOC inserted by doctoc, it will automatically be updated by running the command (rather than inserting a duplicate toc). Doctoc locates the TOC by the `\u003c!-- START doctoc --\u003e` and `\u003c!-- END doctoc --\u003e` comments, so you can also move a generated TOC to any other portion of your document and it will be updated there.\n\n### Adding toc to individual files\n\nIf you want to convert only specific files, do:\n\n    doctoc /path/to/file [...]\n\n#### Examples\n\n    doctoc README.md\n\n    doctoc CONTRIBUTING.md LICENSE.md\n\n### Using doctoc to generate links compatible with other sites\n\nIn order to add a table of contents whose links are compatible other sites add the appropriate mode flag:\n\nAvailable modes are:\n\n```\n--bitbucket bitbucket.org\n--nodejs    nodejs.org\n--github    github.com\n--gitlab    gitlab.com\n--ghost     ghost.org\n```\n\n#### Example\n\n    doctoc README.md --bitbucket\n\n### Specifying location of toc\n\nBy default, doctoc places the toc at the top of the file. You can indicate to have it placed elsewhere with the following format:\n\n```markdown\n\u003c!-- START doctoc --\u003e\n\u003c!-- END doctoc --\u003e\n```\n\nYou place this code directly in your .md file. For example:\n\n```markdown\n// my_new_post.md\nHere we are, introducing the post. It's going to be great!\nBut first: a TOC for easy reference.\n\n\u003c!-- START doctoc --\u003e\n\u003c!-- END doctoc --\u003e\n\n# Section One\n\nHere we'll discuss...\n\n```\n\nRunning doctoc will insert the toc at that location.\n\n### Specifying a custom TOC title\n\nUse the `--title` option to specify a (Markdown-formatted) custom TOC title; e.g., `doctoc --title '**Contents**' .` From then on, you can simply run `doctoc \u003cfile\u003e` and doctoc will keep the title you specified.\n\nAlternatively, to blank out the title, use the `--notitle` option. This will simply remove the title from the TOC.\n\n### Specifying a maximum heading level for TOC entries\n\nUse the `--maxlevel` option to limit TOC entries to headings only up to the specified level; e.g., `doctoc --maxlevel 3 .`\n\nBy default,\n\n- no limit is placed on Markdown-formatted headings,\n- whereas headings from embedded HTML are limited to 4 levels.\n\n### Printing to stdout\n\nYou can print to stdout by using the `-s` or `--stdout` option.\n\n[ack]: http://beyondgrep.com/\n\n### Only update existing ToC\n\nUse `--update-only` or `-u` to only update the existing ToC. That is, the Markdown files without ToC will be left untouched. It is good if you want to use `doctoc` with `lint-staged`.\n\n### Usage as a `git` hook\n\ndoctoc can be used as a [pre-commit](http://pre-commit.com) hook by using the\nfollowing configuration:\n\n```yaml\nrepos:\n-   repo: https://github.com/thlorenz/doctoc\n    rev: ...  # substitute a tagged version\n    hooks:\n    -   id: doctoc\n```\n\nThis will run `doctoc` against markdown files when committing to ensure the\nTOC stays up-to-date.\n\n### Docker image\n\nThere's an unofficial Docker image project for doctoc, if you'd like to use doctoc via Docker or other container based CI/CD pipeline, you can take a look at [PeterDaveHello/docker-doctoc](https://github.com/PeterDaveHello/docker-doctoc)\n","funding_links":["https://github.com/sponsors/thlorenz","paypal.me/thlorenz/25"],"categories":["markdown","Acknowledgments","JavaScript","Utilities","HarmonyOS","Table of Contents","Documentation Tools","Contribute","Uncategorized","目录","README Generators","others","🔧 Tools Used","\u003ca name=\"markdown\"\u003e\u003c/a\u003eMarkdown"],"sub_categories":["Talks","Markdown","Windows Manager","Uncategorized","Dynamic Badges","🔧 Uncategorized Tools","Sites"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthlorenz%2Fdoctoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthlorenz%2Fdoctoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthlorenz%2Fdoctoc/lists"}