{"id":16728816,"url":"https://github.com/sebdah/markdown-toc","last_synced_at":"2025-03-21T21:31:11.770Z","repository":{"id":57492085,"uuid":"110642308","full_name":"sebdah/markdown-toc","owner":"sebdah","description":"Table of Contents generator for Markdown","archived":false,"fork":false,"pushed_at":"2020-05-01T16:02:17.000Z","size":345,"stargazers_count":22,"open_issues_count":6,"forks_count":9,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-18T05:22:43.251Z","etag":null,"topics":["github","go","golang","markdown","table-of-contents"],"latest_commit_sha":null,"homepage":"","language":"Go","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/sebdah.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}},"created_at":"2017-11-14T04:54:20.000Z","updated_at":"2024-06-07T12:35:06.000Z","dependencies_parsed_at":"2022-08-28T11:50:31.596Z","dependency_job_id":null,"html_url":"https://github.com/sebdah/markdown-toc","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebdah%2Fmarkdown-toc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebdah%2Fmarkdown-toc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebdah%2Fmarkdown-toc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebdah%2Fmarkdown-toc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sebdah","download_url":"https://codeload.github.com/sebdah/markdown-toc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244874157,"owners_count":20524576,"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","go","golang","markdown","table-of-contents"],"created_at":"2024-10-12T23:11:54.752Z","updated_at":"2025-03-21T21:31:10.777Z","avatar_url":"https://github.com/sebdah.png","language":"Go","readme":"# markdown-toc\n\n\u003cp align=\"center\"\u003e\n    \u003cstrong\u003eGenerating your Markdown Table of Contents\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://travis-ci.org/sebdah/markdown-toc\"\u003e\u003cimg src=\"https://img.shields.io/travis/sebdah/markdown-toc.svg\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://hub.docker.com/r/sebdah/markdown-toc/\"\u003e\u003cimg src=\"https://img.shields.io/badge/docker-latest-blue.svg\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://godoc.org/github.com/sebdah/markdown-toc\"\u003e\u003cimg src=\"https://img.shields.io/badge/godoc-documentation-blue.svg\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sebdah/markdown-toc/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/sebdah/markdown-toc.svg\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sebdah/markdown-toc/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/sebdah/markdown-toc.svg\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n`markdown-toc` is a small application written in Go that helps you generate a\nTable of Contents (ToC) for your Markdown file. There are already a number of\nscripts etc doing this, but I failed to find one that suited my needs.\n\nIn short the features of `markdown-toc` are:\n\n- Cross platform (OS X, Linux, Windows)\n- Replacement of an existing ToC\n  - The new file can be written to `stdout` or overwritten on disk\n- Able to skip `n` number of initial headers\n- Configurable depth of headers to include\n- Customizable header for the table of contents\n\n**Please star the project if you like it!**\n\n\u003c!-- ToC start --\u003e\n# Table of Contents\n\n1. [Table of Contents](#table-of-contents)\n1. [Installation](#installation)\n   1. [Running it in Docker](#running-it-in-docker)\n   1. [Building it yourself](#building-it-yourself)\n1. [Example usage](#example-usage)\n   1. [Generating a ToC to `stdout`](#generating-a-toc-to-stdout)\n   1. [Controlling depth of headers](#controlling-depth-of-headers)\n   1. [Set a custom header](#set-a-custom-header)\n   1. [Render the ToC without a header](#render-the-toc-without-a-header)\n   1. [Skip `n` headers](#skip-n-headers)\n   1. [Print the full Markdown file, not only the ToC](#print-the-full-markdown-file-not-only-the-toc)\n   1. [Inject the ToC into a file on disk](#inject-the-toc-into-a-file-on-disk)\n1. [Helping out!](#helping-out)\n   1. [Running the test suite](#running-the-test-suite)\n   1. [Build locally with build flags](#build-locally-with-build-flags)\n1. [Releasing new versions](#releasing-new-versions)\n1. [Contributors](#contributors)\n1. [License](#license)\n\u003c!-- ToC end --\u003e\n\n# Installation\n\n## Running it in Docker\n\nThe project has a Docker image that you can use easily:\n\n    docker run -v $(pwd)\":/app\" -w /app --rm -it sebdah/markdown-toc README.md\n\nThe above will mount your current directory into the Docker container. Just\nmodify the `-v` flag according to your needs if you need to modify some other\nfolder.\n\n`markdown-toc` is the `ENTRYPOINT` in the `Dockerfile`, which means that it's\nthe default command.\n\n## Building it yourself\n\nCurrently the easiest way is to clone the repository and run:\n\n    make install\n\nYou will end up having a binary called `markdown-toc` in your system afterwards.\n\n# Example usage\n\n## Generating a ToC to `stdout`\n\nCommand:\n\n    markdown-toc README.md\n\nOutput:\n\n    \u003c!-- ToC start --\u003e\n    # Table of Contents\n\n    - [`markdown-toc` - Generate your Table of Contents](#`markdown-toc`---generate-your-table-of-contents)\n    - [Example usage](#example-usage)\n      - [Generating a ToC to `stdout`](#generating-a-toc-to-`stdout`)\n    - [License](#license)\n    \u003c!-- ToC end --\u003e\n\n## Controlling depth of headers\n\nUsing the `--depth` flag you can control how many labels of headers to include\nin the output. If the `--depth` is set to `1`, only level 1 headers are\nincluded. Set this value to `0` (default) to include any depth of headers.\n\nCommand:\n\n    markdown-toc --depth 1 README.md\n\nOutput:\n\n    \u003c!-- ToC start --\u003e\n    # Table of Contents\n\n    - [`markdown-toc` - Generate your Table of Contents](#`markdown-toc`---generate-your-table-of-contents)\n    - [Example usage](#example-usage)\n    - [License](#license)\n    \u003c!-- ToC end --\u003e\n\n## Set a custom header\n\nBy default we print a header like `# Table of Contents` above the table of\ncontents. You can change the header to suit your project using the `--header`\nflag.\n\nCommand:\n\n    markdown-toc --header \"# ToC\" README.md\n\nOutput:\n\n    \u003c!-- ToC start --\u003e\n    # ToC\n\n    - [`markdown-toc` - Generate your Table of Contents](#`markdown-toc`---generate-your-table-of-contents)\n    - [Example usage](#example-usage)\n      - [Generating a ToC to `stdout`](#generating-a-toc-to-`stdout`)\n    - [License](#license)\n    \u003c!-- ToC end --\u003e\n\n## Render the ToC without a header\n\nBy default we print a header like `# Table of Contents` above the table of\ncontents. You can remove the header by providing `--no-header` to the command.\n\nCommand:\n\n    markdown-toc --no-header README.md\n\nOutput:\n\n    \u003c!-- ToC start --\u003e\n    - [`markdown-toc` - Generate your Table of Contents](#`markdown-toc`---generate-your-table-of-contents)\n    - [Example usage](#example-usage)\n      - [Generating a ToC to `stdout`](#generating-a-toc-to-`stdout`)\n    - [License](#license)\n    \u003c!-- ToC end --\u003e\n\n## Skip `n` headers\n\nIf you do not want to include `n` number of initial headers in your ToC, you can\nuse the `--skip-headers=1` flag. This is useful if you have your project name as\nthe first header and you don't really want that in the ToC for example.\n\nCommand:\n\n    markdown-toc --skip-headers=1 README.md\n\nOutput:\n\n    \u003c!-- ToC start --\u003e\n    - [Example usage](#example-usage)\n      - [Generating a ToC to `stdout`](#generating-a-toc-to-`stdout`)\n    - [License](#license)\n    \u003c!-- ToC end --\u003e\n\n## Print the full Markdown file, not only the ToC\n\n    markdown-toc --replace README.md\n\nThis will print the full Markdown of `README.md` and a table of contents section\nwill be injected into the Markdown based on the following rules:\n\n- If no ToC was found, the ToC will be injected on top of the file\n- If a section starting with `\u003c!-- ToC start --\u003e` and ending with\n  `\u003c!-- ToC end --\u003e` is found, it will be replaced with the new ToC.\n\n## Inject the ToC into a file on disk\n\n    markdown-toc --replace --inline README.md\n\nThis will overwrite the `README.md` file on disk with the full Markdown of\n`README.md` and a table of contents section will be injected into the Markdown\nbased on the following rules:\n\n- If no ToC was found, the ToC will be injected on top of the file\n- If a section starting with `\u003c!-- ToC start --\u003e` and ending with\n  `\u003c!-- ToC end --\u003e` is found, it will be replaced with the new ToC.\n\n# Helping out!\n\nThere are many ways to help out with this project. Here are a few:\n\n- Answer questions [here](https://github.com/sebdah/markdown-toc/issues)\n- Enhance the documentation\n- Spread the good word on [Twitter](https://twitter.com) or similar places\n- Implement awesome features. Some of the suggested features can be found\n  [here](https://github.com/sebdah/markdown-toc/issues)\n\n## Running the test suite\n\n    make test\n\n## Build locally with build flags\n\n    make build\n\n# Releasing new versions\n\nFrom the `master` branch run `make release`. You will need to have access to\npushing to the GitHub project as well as Docker Hub.\n\n# Contributors\n\n- [Sebastian Dahlgren](https://twitter.com/sebdah) (maintainer)\n\n# License\n\nMIT license\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebdah%2Fmarkdown-toc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsebdah%2Fmarkdown-toc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebdah%2Fmarkdown-toc/lists"}