{"id":16728762,"url":"https://github.com/hukkin/mdformat-toc","last_synced_at":"2025-03-17T01:31:37.686Z","repository":{"id":39887375,"uuid":"300473199","full_name":"hukkin/mdformat-toc","owner":"hukkin","description":"Mdformat plugin to generate a table of contents","archived":false,"fork":false,"pushed_at":"2024-10-15T20:06:08.000Z","size":80,"stargazers_count":19,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-12T15:16:58.278Z","etag":null,"topics":["mdformat","table-of-contents","toc","toc-generator"],"latest_commit_sha":null,"homepage":"","language":"Python","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/hukkin.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":"2020-10-02T01:49:03.000Z","updated_at":"2025-02-23T01:32:01.000Z","dependencies_parsed_at":"2024-10-17T01:16:42.833Z","dependency_job_id":"2fcc1f10-0574-4d7f-a296-97fd562d5eba","html_url":"https://github.com/hukkin/mdformat-toc","commit_stats":null,"previous_names":["hukkinj1/mdformat-toc"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hukkin%2Fmdformat-toc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hukkin%2Fmdformat-toc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hukkin%2Fmdformat-toc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hukkin%2Fmdformat-toc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hukkin","download_url":"https://codeload.github.com/hukkin/mdformat-toc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243836015,"owners_count":20355615,"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":["mdformat","table-of-contents","toc","toc-generator"],"created_at":"2024-10-12T23:11:38.557Z","updated_at":"2025-03-17T01:31:37.248Z","avatar_url":"https://github.com/hukkin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://github.com/hukkin/mdformat-toc/actions/workflows/tests.yaml/badge.svg?branch=master)](https://github.com/hukkin/mdformat-toc/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush)\n[![PyPI version](https://img.shields.io/pypi/v/mdformat-toc)](https://pypi.org/project/mdformat-toc)\n\n# mdformat-toc\n\n\u003e Mdformat plugin to generate a table of contents\n\n**Table of Contents**  *generated with [mdformat-toc](https://github.com/hukkin/mdformat-toc)*\n\n\u003c!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 --\u003e\n\n- [Description](#description)\n- [Install](#install)\n- [Usage](#usage)\n  - [Configuration](#configuration)\n    - [Minimum and maximum heading levels](#minimum-and-maximum-heading-levels)\n    - [Disabling anchor generation](#disabling-anchor-generation)\n    - [Changing the slug function](#changing-the-slug-function)\n\n\u003c!-- mdformat-toc end --\u003e\n\n## Description\n\nMdformat-toc is an [mdformat](https://github.com/executablebooks/mdformat) plugin\nthat adds mdformat the capability to auto-generate a table of contents (ToC).\nThe ToC is generated in a user-specified location in the Markdown file.\n\nMdformat-toc, by default, creates an HTML anchor for each heading listed in the ToC.\nToC links should therefore be compatible with any well-behaved Markdown renderer (including GitLab's renderer).\n\nHTML anchor generation can be disabled, in which case a user should configure a slug function that is compatible with the Markdown renderer used (GitHub and GitLab slug functions are currently supported).\n\n## Install\n\n```bash\npip install mdformat-toc\n```\n\n## Usage\n\nAdd the following line to your Markdown file.\nA ToC will be generated in the location indicated by it.\n\n```markdown\n\u003c!-- mdformat-toc start --\u003e\n```\n\nAfter adding the indicator line, simply run\n\n```bash\nmdformat \u003cfilename\u003e\n```\n\nand mdformat will generate a ToC.\n\n### Configuration\n\nArguments can be added to the indicator line to alter how the ToC is generated.\nAn indicator line with the default options would look like:\n\n```markdown\n\u003c!-- mdformat-toc start --slug=github --maxlevel=6 --minlevel=1 --\u003e\n```\n\nPlacing more than one indicator lines in a document is currently not supported.\n\n#### Minimum and maximum heading levels\n\nA user can configure a range of heading levels to be included in the ToC (and to be \"anchored\").\nFor instance, the following configuration will only list 2nd, 3rd and 4th level headings in the ToC:\n\n```markdown\n\u003c!-- mdformat-toc start --minlevel=2 --maxlevel=4 --\u003e\n```\n\n#### Disabling anchor generation\n\nBy default, an HTML anchor is appended to each heading.\nFor instance, the following heading\n\n```markdown\n# Some title\n```\n\nmight be formatted as\n\n```markdown\n# Some title\u003ca name=\"some-title\"\u003e\u003c/a\u003e\n```\n\nThis ensures that ToC links do not rely on a Markdown renderer to create HTML anchors,\nand makes the links universally compatible.\n\nToC links are by default compatible with the anchors generated by GitHub's Markdown renderer.\nIf your Markdown is only hosted on GitHub, you can disable mdformat-toc's HTML anchor generation:\n\n```markdown\n\u003c!-- mdformat-toc start --no-anchors --\u003e\n```\n\n#### Changing the slug function\n\nMdformat-toc defaults to using GitHub's slug function.\n\nIf your Markdown is not hosted on GitHub you may want to use GitLab's slug function instead:\n\n```markdown\n\u003c!-- mdformat-toc start --slug=gitlab --no-anchors --\u003e\n```\n\n**NOTE:** Unlike GitLab, GitHub requires using its own slug function in order for ToC links to work expectedly.\nCreating HTML anchors and using a non-GitHub slug function is not GitHub compatible\nbecause GitHub's Markdown renderer modifies the HTML anchors mdformat-toc creates.\nThe default configuration\n(GitHub slug function and anchor generation)\nis the only configuration cross-compatible with GitHub and GitLab.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhukkin%2Fmdformat-toc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhukkin%2Fmdformat-toc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhukkin%2Fmdformat-toc/lists"}