{"id":20692670,"url":"https://github.com/kevingimbel/mktoc","last_synced_at":"2025-12-28T13:58:32.990Z","repository":{"id":57639375,"uuid":"222000331","full_name":"KevinGimbel/mktoc","owner":"KevinGimbel","description":"🦀 Markdown Table of Content generator","archived":false,"fork":false,"pushed_at":"2023-11-15T08:41:47.000Z","size":2027,"stargazers_count":17,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-30T08:53:14.948Z","etag":null,"topics":["cli","command-line","command-line-tool","generator","markdown","rust","rust-library","table-of-contents","toc"],"latest_commit_sha":null,"homepage":"https://kevingimbel.de/oss","language":"Rust","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/KevinGimbel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2019-11-15T20:44:43.000Z","updated_at":"2025-04-01T08:52:11.000Z","dependencies_parsed_at":"2024-11-17T00:20:55.418Z","dependency_job_id":null,"html_url":"https://github.com/KevinGimbel/mktoc","commit_stats":{"total_commits":52,"total_committers":5,"mean_commits":10.4,"dds":"0.40384615384615385","last_synced_commit":"d153d56c8380a4185194d2bf0f3b5d746c27cdb7"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/KevinGimbel/mktoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KevinGimbel%2Fmktoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KevinGimbel%2Fmktoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KevinGimbel%2Fmktoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KevinGimbel%2Fmktoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KevinGimbel","download_url":"https://codeload.github.com/KevinGimbel/mktoc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KevinGimbel%2Fmktoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273278612,"owners_count":25077271,"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-09-02T02:00:09.530Z","response_time":77,"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":["cli","command-line","command-line-tool","generator","markdown","rust","rust-library","table-of-contents","toc"],"created_at":"2024-11-16T23:23:27.860Z","updated_at":"2025-12-28T13:58:32.983Z","avatar_url":"https://github.com/KevinGimbel.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `mktoc`\n\n![](assets/github-header.png)\n\n\u003csmall\u003eGraphic design is my passion ✨\u003c/small\u003e\n\n![](https://github.com/kevingimbel/mktoc/workflows/Clippy%20check/badge.svg)\n![](https://github.com/kevingimbel/mktoc/workflows/Test/badge.svg)\n![Coverage](assets/coverage/flat.svg)\n\n# Table of Contents\n\u003c!-- BEGIN mktoc {\"min_depth\":2, \"max_depth\":5} --\u003e\n\n- [About](#about)\n- [Installation](#installation)\n  - [Cargo](#cargo)\n  - [Binary](#binary)\n  - [Hermit](#hermit)\n  - [Nix](#nix)\n    - [Run on demand ](#run-on-demand)\n    - [Install (nixos / nix-darwin)](#install-nixos--nix-darwin)\n- [Usage](#usage)\n  - [Update Markdown file](#update-markdown-file)\n    - [Inline config](#inline-config)\n      - [`min_depth`](#min_depth)\n      - [`max_depth`](#max_depth)\n      - [`wrap_in_details`](#wrap_in_details)\n  - [Command line](#command-line)\n  - [Environment configuration](#environment-configuration)\n- [Auto-run with VSCode](#auto-run-with-vscode)\n- [Performance](#performance)\n- [Contributing](#contributing)\n  - [Where to start?](#where-to-start)\n  - [Tooling](#tooling)\n  - [Install dev build](#install-dev-build)\n- [License](#license)\n\u003c!-- END mktoc --\u003e\n\n\n## About\n[⬆️ Back to Top](#table-of-contents)\n\n`mktoc` parses markdown files and generates a Table Of Content linking all headlines up to heading level 6 deep, or as specified by command line arguments, environment variables, or inline JSON config (see [Usage](#usage)).\n\n## Installation\n[⬆️ Back to Top](#table-of-contents)\n\n`mktoc` can be installed using Cargo, the Rust package manager.\n\n### Cargo\n\n**Installation**\n```sh\n$ cargo install mktoc\n```\n\n**Update**\n```sh\n$ cargo install --force mktoc\n```\n\n### Binary\n\nBinaries for Linux and MacOS can be downloaded from the [release page](https://github.com/KevinGimbel/mktoc/releases/latest).\n\nWindows Binaries are not yet build automatically, see [#7](https://github.com/KevinGimbel/mktoc/issues/7).\n\n### Hermit\n\n`mktoc` is available in [hermit](https://github.com/cashapp/hermit) so it can be installed on a per-project basis without the need to install it globally.\n\n```sh\n$ hermit init\n$ hermit install mktoc\n```\n\nThis installs `mktoc` to the local bin directory at `bin/mktoc` inside the project.\n\n### Nix\n\n`mktoc` is available in [nixpkgs](https://search.nixos.org/packages?channel=unstable\u0026show=mktoc\u0026query=mktoc) since version 25.11.\n\n#### Run on demand \n\n```sh\nnix run 'github:nixos/nixpkgs/nixpkgs-unstable#mktoc'\n```\n\n#### Install (nixos / nix-darwin)\n\n```nix\nenvironment.systemPackages = [\n  pkgs.mktoc\n];\n```\n\n## Usage\n\n### Update Markdown file\n[⬆️ Back to Top](#table-of-contents)\n\nAdd the following HTML comment into the Markdown file where the Table of Contents should be rendered.\n\n```html\n\u003c!-- BEGIN mktoc --\u003e\n\u003c!-- END mktoc --\u003e\n```\n\nEverything between those comments will be replaced!\n\n#### Inline config\n[⬆️ Back to Top](#table-of-contents)\n\nStarting with version 3.0.0 it's possible to set values in-line which is great when collaborating with teams who may have individual settings.\n\n```html\n\u003c!-- BEGIN mktoc {\"min_depth\": 2, \"max_depth\": 4, \"wrap_in_details\": false} --\u003e\n\u003c!-- END mktoc -- \u003e\n```\n\nthis is equal to running `mktoc -m 2 -M 4` or setting these environment variables `MKTOC_MIN_DEPTH=2` and `MKTOC_MAX_DEPTH=4`.\n\nInline config takes priority over environment or CLI arguments.\n\n##### `min_depth`\n\nThe minimum depth to look for, defaults to 1 which is equal to `\u003ch1\u003e` or `#`.\n\n##### `max_depth`\n\nThe maximum depth to look for, defaults to 6 which is equal to `\u003ch6\u003e` or `######`.\n\n##### `wrap_in_details`\n\nIf set to true, the ToC will be wrapped in a `\u003cdetails\u003e` element.\n\n### Command line\n[⬆️ Back to Top](#table-of-contents)\n\nSpecify `--stdout` or `-s` to output generated content to `stdout` instead of overwriting file. By default the specified file will be overwritten.\n\n```sh\n$ mktoc -h\nGenerate Table of Contents from Markdown files\n\nUsage: mktoc [OPTIONS] [FILE]\n\nArguments:\n  [FILE]  [default: README.md]\n\nOptions:\n  -s, --stdout                 If set will output to stdout instead of replacing content in file\n  -m, --min-depth \u003cMIN_DEPTH\u003e  Minimum heading level [env: MKTOC_MIN_DEPTH=] [default: 1]\n  -M, --max-depth \u003cMAX_DEPTH\u003e  Maximum heading level [env: MKTOC_MAX_DEPTH=] [default: 6]\n  -w, --wrap-in-details        Wrap ToC in details html element [env: MKTOC_WRAP_IN_DETAILS=]\n  -h, --help                   Print help\n  -V, --version                Print version\n\n$ mktoc -s README.md\n$ mktoc -m 2 -M 4 README.md\n$ mktoc\n```\n\nIf no arguments are given the default or configured (via environment) values are\nused. \n\nSee `mktoc --help` for list of all arguments and flags.\n\n```sh\nmktoc\n\nUSAGE:\nmktoc [FLAGS] [OPTIONS] [file]\n\nFLAGS:\n-h, --help       Prints help information\n-s, --stdout     If set will output to stdout instead of replacing content in file\n-V, --version    Prints version information\n\nOPTIONS:\n-M, --max-depth \u003cmax-depth\u003e    Maximum heading level [env: MKTOC_MAX_DEPTH=]  [default: 6]\n-m, --min-depth \u003cmin-depth\u003e    Minimum heading level [env: MKTOC_MIN_DEPTH=2]  [default: 1]\n\nARGS:\n\u003cfile\u003e     [default: README.md]\n```\n\n### Environment configuration\n[⬆️ Back to Top](#table-of-contents)\n\nmktoc can be configured with environment variables, namely:\n\n- `MKTOC_MIN_DEPTH` equal to `-m`\n- `MKTOC_MAX_DEPTH` equal to `-M`\n\nPlace these variables in a shell environment file such as `~/.bashrc` or\n`~/.zshrc`, then just run mktoc without `-m` and `-M`\n\n```sh\n# The following in ~/.bashrc|~/.zshrc configures mktoc to render headings from level 2 to\n# level 4\n# \n# MKTOC_MIN_DEPTH=2\n# MKTOC_MAX_DEPTH=4\n# MKTOC_WRAP_IN_DETAILS=true\n\n$ mktoc README.md\n```\n\n## Auto-run with VSCode\n[⬆️ Back to Top](#table-of-contents)\n\nFor VSCode the [Run on save](https://github.com/emeraldwalk/vscode-runonsave) extension can be used to trigger mktoc.\n\nInstall the extension and then add the following config to workspace or user `settings.json`.\n\n```json\n\"emeraldwalk.runonsave\": {\n  \"commands\": [\n    {\n      \"match\": \"\\\\.md$\",\n      \"cmd\": \"mktoc ${file}\"\n    }\n  ]\n}\n```\n\nThis will run the command for every markdown file on safe. If there is no mktoc comment in the Markdown file nothing happens.\n\n## Performance\n[⬆️ Back to Top](#table-of-contents)\n\n`mktoc` is fast but can probably be even faster! Pull Requests and bug reports are appreciated!\n\n## Contributing\n[⬆️ Back to Top](#table-of-contents)\n\nWe love and welcome every form of contribution.\n\n### Where to start?\n\nHere are some good places to start:\n\n* Issues with label [Good first issue](https://github.com/kevingimbel/mktoc/labels/good%20first%20issue)\n* Issues with label [Documentation](https://github.com/kevingimbel/mktoc/labels/documentation)\n* Providing example implementations or usage demos\n\n### Tooling\n\n- [mktoc](https://github.com/KevinGimbel/mktoc) is used for table of content generation in the README.md (neat!)\n- [criterion](https://github.com/bheisler/criterion.rs) for benchmarking\n- [just]([https://](https://github.com/casey/just)) is used as task runner\n- [nix](https://nix.dev) is used for keeping dev tools versions equal across CI and local setups\n\n### Install dev build\n\nSometimes it's nice to install a specific version of mktoc, this can be done with the following command:\n\n```sh\n# install specific commit\ncargo install --git https://github.com/KevinGimbel/mktoc --force --rev $COMMIT_ID\n# install branch\ncargo install --git https://github.com/KevinGimbel/mktoc --force --branch $BRANCH_NAME\n```\n\n## License\n[⬆️ Back to Top](#table-of-contents)\n\nMIT, see LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevingimbel%2Fmktoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkevingimbel%2Fmktoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevingimbel%2Fmktoc/lists"}