{"id":15117426,"url":"https://github.com/derlin/bitdowntoc","last_synced_at":"2025-04-06T13:12:24.693Z","repository":{"id":150723059,"uuid":"345431021","full_name":"derlin/bitdowntoc","owner":"derlin","description":"Online and command-line Markdown TOC generator, with built-in support for BitBucket Server, GitHub, Gitlab, dev.to and more!","archived":false,"fork":false,"pushed_at":"2025-02-16T11:58:58.000Z","size":1780,"stargazers_count":93,"open_issues_count":8,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-30T12:08:59.234Z","etag":null,"topics":["bitbucket-server","command-line-tool","markdown","online","toc-generation","tools"],"latest_commit_sha":null,"homepage":"https://bitdowntoc.derlin.ch","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/derlin.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":"2021-03-07T19:11:22.000Z","updated_at":"2025-03-07T07:31:00.000Z","dependencies_parsed_at":"2024-06-08T15:49:55.959Z","dependency_job_id":"1e8a28d1-e8d6-4428-904b-9459313deb75","html_url":"https://github.com/derlin/bitdowntoc","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derlin%2Fbitdowntoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derlin%2Fbitdowntoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derlin%2Fbitdowntoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derlin%2Fbitdowntoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/derlin","download_url":"https://codeload.github.com/derlin/bitdowntoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247485290,"owners_count":20946398,"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":["bitbucket-server","command-line-tool","markdown","online","toc-generation","tools"],"created_at":"2024-09-26T01:45:57.392Z","updated_at":"2025-04-06T13:12:24.668Z","avatar_url":"https://github.com/derlin.png","language":"Kotlin","funding_links":[],"categories":["Kotlin"],"sub_categories":[],"readme":"# BitDownToc\n\n![GitHub Release](https://img.shields.io/github/v/release/derlin/bitdowntoc?style=for-the-badge) \u0026nbsp;\n![GitHub Release Date](https://img.shields.io/github/release-date/derlin/bitdowntoc?display_date=published_at\u0026style=for-the-badge) \u0026nbsp;\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/derlin/bitdowntoc/deploy.yml?branch=main\u0026style=for-the-badge\u0026label=deploy)\n---\n\n![BitDownToc](https://github.com/derlin/bitdowntoc/raw/main/src/jsMain/resources/og-bitdowntoc.png?style=for-the-badge)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://bitdowntoc.derlin.ch/\" target=\"_blank\"\u003e\n    \u003cimg alt=\"try online badge\" src=\"https://img.shields.io/badge/try%20online-ff610e?style=for-the-badge\"\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"https://github.com/derlin/homebrew-bitdowntoc\" target=\"_blank\"\u003e\n    \u003cimg alt=\"install badge\" src=\"https://img.shields.io/badge/install%20(brew)-9b4dca?style=for-the-badge\"\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"https://github.com/derlin/bitdowntoc/releases/latest\" target=\"_blank\"\u003e\n    \u003cimg alt=\"download badge\" src=\"https://img.shields.io/badge/download-546e7a?style=for-the-badge\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nBitDownToc adds a table of contents (TOC) to your Markdown files, either online or from the command line.\nIt supports **Gitlab** and **GitHub** styles, and can generate anchors to comply with **Bitbucket Server**\n(and its lack of proper markdown support using the generic profile), **[dev.to](https://dev.to)**,\n**[hashnode](https://hashnode.com)**, and more!\n\nThanks to small comments (in HTML or liquid tags), it can also detect previously generated TOC,\nso you can run it every time you change your README without worries. In other words, it is **idempotent** 🤩.\n\nIt supports English, French, and most **Latin languages**, but not Cyrillic or Chinese!\n\n----\n\nTOC (generated by this tool, duh, using the `github` profile):\n\n\u003c!-- TOC start (generated with https://github.com/derlin/bitdowntoc) --\u003e\n\n- [Usage](#usage)\n   * [Online](#online)\n   * [From the command line](#from-the-command-line)\n   * [About native executables](#about-native-executables)\n- [TOC flavors (profiles)](#toc-flavors-profiles)\n   * [Built-in profiles](#built-in-profiles)\n   * [Other platforms](#other-platforms)\n   * [Still not fitting your use case?](#still-not-fitting-your-use-case)\n- [TOC placement](#toc-placement)\n- [About the code](#about-the-code)\n   * [Motivation](#motivation)\n   * [Kotlin all the way!](#kotlin-all-the-way)\n   * [Build and run](#build-and-run)\n- [Contributing](#contributing)\n- [About the license](#about-the-license)\n\n\u003c!-- TOC end --\u003e\n\n\n## Usage\n\n### Online\n\nGo to https://bitdowntoc.derlin.ch !\n\n### From the command line\n\nHaving [homebrew](https://brew.sh)? Install bitdowntoc with:\n```bash\nbrew install derlin/bitdowntoc/bitdowntoc\n```\n\nOtherwise, the **JVM jar** can be found in the [releases](https://github.com/derlin/bitdowntoc/releases).\nIf you want the latest version, check the [nightly release](https://github.com/derlin/bitdowntoc/releases/nightly).\n\nNative executables for Linux, Mac and Windows are available for releases only.\nSee [About native executables](#about-native-executables) for more info.\n\nOnce installed, run:\n```bash\n# Generic, e.g. BitBucket Server\nbitdowntoc readme.md --inplace\n# GitLab\nbitdowntoc -p gitlab readme.md --inplace # or\nbitdowntoc --no-anchors readme.md --inplace\n# GitHub\nbitdowntoc -p github readme.md --inplace # or\nbitdowntoc --no-anchors --no-concat-spaces readme.md --inplace\n# DevTo\nbitdowntoc -p devto\n# Hashnode\nbitdowntoc -p hashnode\n\n# Piping from stdin\ncat README.md | bitdowntoc\n```\nNOTE: if you are downloaded the jar, replace `bitdowntoc` above with `java -jar bitdowntoc-jvm-*.jar`.\nIf you installed the native executable manually, replace `bitdowntoc` above with `\u003cpath/to/executable\u003e`.\n\nThe tool will output the transformed file depending on the following options (mutually exclusive):\n\n* default: output to stdout;\n* `-i`/`--inplace`: replace input file (incompatible with reading from stdin);\n* `-o`/`--output`: output to the specified file.\n\n**IMPORTANT**: do not use bash redirects with the same file (input = output), it won't work as you expect!\n\nIf you have a doubt, run BitDownToc with `-h` or `--help`:\n```text\nUsage: bitdowntoc [\u003coptions\u003e] [\u003cpath\u003e]\n\nOptions:\n  --version                      Show version and exit\n  --indent-chars=\u003ctext\u003e          Characters used for indenting the toc\n                                 (default: '-*+')\n  --indent-spaces=\u003cint\u003e          Number of spaces per indentation level for\n                                 indenting the toc (default: '3')\n  --concat-spaces / --no-concat-spaces\n                                 Whether to trim heading spaces in generated\n                                 links (foo-bar) or not (foo----bar) (default:\n                                 true)\n  --anchors-prefix=\u003ctext\u003e        Prefix added to all anchors and TOC links\n                                 (e.g. 'heading-') (default: '')\n  --anchors / --no-anchors       Whether to generate anchors below headings\n                                 (e.g. BitBucket Server) (default: true)\n  --anchors-algo=(DEFAULT|DEVTO|HASHNODE)\n                                 How handle special chars, links, etc. in\n                                 titles before generating anchor links\n                                 (default: DEFAULT)\n  --comment-style=(HTML|LIQUID)  Language to use for generating comments around\n                                 TOC and anchors (default: HTML)\n  --trim-toc / --no-trim-toc     Whether to indent TOC based on the registered\n                                 headings, or based on the actual heading\n                                 levels (default: true)\n  --oneshot / --no-oneshot       Whether to add comments so bitdowntoc can\n                                 regenerate/update the toc and anchors (false)\n                                 or not (true) (default: false)\n  --max-level=\u003cint\u003e              Maximum heading level to include to the toc (\u003c\n                                 1 means no limit) (default: '-1')\n  --toc-only                     Only output the TOC\n  -p, --profile=(GENERIC|GITHUB|GITLAB17|GITLAB|HASHNODE|DEVTO)\n                                 Load default options for a specific site\n  -i, --inplace                  Overwrite input file. This is incompatible\n                                 with reading from stdin\n  -o, --output-file=\u003cpath\u003e       Write the output to a file instead of stdout\n  -h, --help                     Show this message and exit\n\nArguments:\n  \u003cpath\u003e  Markdown file, or '-' to read from stdin\n```\n\n### About native executables\n\nNative executables are attached to each release.\n\n**Linux**\n\nOn Linux, you may just have to run `chmod +x` before use.\n\n**Mac**\n\nOn Mac, you need to run `chmod +x` and then execute the script once.\nIt will be blocked, but you can allow it anyway by going to *System Preferences* \u003e *Security* and pressing \"Allow Anyway\".\nOnce done, re-execute BitDownToc and click \"Open\" on the popup.\nYou are good to go.\n\n**Windows**\n\nOn Windows, right-click on the executable and press *Properties*.\nIn the general tab under *Security* at the bottom, tick \"Unblock\".\nYou can now execute it in the CMD. Note that it may take a while to launch, but only the first time ;)\n\n## TOC flavors (profiles)\n\nThis tool supports some profiles out-of-the-box: GitLab, GitLab 17 (version 17.0 and above), GitHub, and dev.to.\nThe Generic profile is perfect for platforms such as BitBucket Server which do not generate anchor links on their own.\nSimply choose your flavor using the profile option (`-p`/`--profile`).\n\nIt is however highly customizable, and the options can also fit many other platforms.\nHere is a breakdown of the options (that differ from the defaults) to use for each.\n\n### Built-in profiles\n\n* *Generic* → generate anchors (e.g. BitBucket Server)\n* *GitLab* → concat spaces, do not generate anchors\n* *GitLab 17* → do not concat spaces, do not generate anchors\n* *GitHub* → do not concat spaces, do not generate anchors\n* *dev.to* → concat spaces, do not generate anchors, comment style = liquid, anchors algorithm = DEVTO\n* *hashnode* → concat spaces, anchors prefix = \"heading-\", anchors algorithm = HASHNODE\n\n### Other platforms\n\n* *BitBucket.org* (supports the `[TOC]` directly) → anchors algorithm = DEVTO, anchors prefix = `markdown-header-`\n  ❗ will break if you use code in your headings (backticks) - open an issue if you want support :)\n\nIf you have more ideas or platforms you want to use, let me know by opening an issue 😊.\n\n### Still not fitting your use case?\n\nIf no combination of available options fits your Markdown processor, simply use the *generate anchors* (or use the *BitBucket* profile).\n\nSince the anchors are manually added to the markdown, the TOC will work as long as `\u003ca\u003e` tags with a `name` parameter\nare supported. If you are working with a platform supporting liquid tags instead (e.g. forem), set the *comment style* option to LIQUID\n(or use the *dev.to* profile).\n\n## TOC placement\n\nYou can control where the table of content will be inserted by adding the marker (on its own line):\n```text\n[TOC]\n```\n\nAny header above the marker will be ignored. The option \"*trim toc*\" (turned on by default) means that if\nyou have e.g. only level-2 headers below the marker, the TOC will be indented as if those were level 1 headers.\n\n---\n\n## About the code\n\n### Motivation\n\nI got the motivation from the lack of existing tools supporting **BitBucket Server**.\nAs of version 6, the BitBucket processor doesn't insert any ID or name to the HTML headers generated from markdown, meaning there is no way\nof targeting a specific header without manually adding an anchor of the form:\n```html\n\u003ca name=\"some-heading\"\u003e\u003c/a\u003e\n```\n\nI found [this blog](https://rderik.com/blog/generate-table-of-contents-with-anchors-for-markdown-file-vim-plugin/)\nmentioning a Vim plugin doing it for you, but this requires Vim (obviously) and the anchors support lives in a\nspecific branch that is unlikely to be maintained.\n\nI am quite fond of [GitHub Wiki TOC generator](https://ecotrust-canada.github.io/markdown-toc/)\n(you should see the inspiration here), and wanted something similar but more flexible\n(not only targeting GitHub and supporting symbols and diacritics).\n\n\n### Kotlin all the way!\n\nThis project was also a great way to play with Kotlin MPP (Multi-Platform Projects).\n\nThe code is split between:\n* a common module handling the TOC generation, and defining the default options;\n* a JVM module with a [Clikt](https://ajalt.github.io/clikt/) CLI;\n* a JS module that is imported into a static HTML page.\n\n![Kotlin MultiPlatform Overview](other/kotlin-multiplatform-overview.png)\n\nTests are implemented in the common module, with one exception: some additional tests are located in the JVM module,\nbecause I wanted to load test files and reading files is not supported in common...\n\n### Build and run\n\nTo build the project, use the custom target `bitdowntoc`, which will produce the JVM fat jar and copy the compiled\njs scripts into the directory `html/scripts`:\n```bash\n./gradlew bitdowntoc\n```\nThe `html` folder can then be deployed as a static site.\n\n\nTo run tests, use `check` or `allTests`:\n```bash\n./gradlew allTests\n```\n\n---\n\n## Contributing\n\nIf you find this tool helpful, please star the repo or add a comment somewhere, it will help me keep enough motivation\nto maintain it properly.\n\nIf you want to contribute, feel free open a PR anytime! Just keep in mind:\n\n* code style → [Kotlin Coding Conventions](https://kotlinlang.org/docs/coding-conventions.html#configure-style-in-ide)\n* commit messages → [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)\n* pull requests policy → rebase + squash (one commit per PR, rebased on the main branch)\n* build and run → see sections above 😏\n\n---\n\n## About the license\n\nI chose the [Common Clause](https://commonsclause.com) for this project,\njust because I had a very bad experience once, where someone took one of my projects\nas is, added adverts and republished it under his own name.\n\nI know most of the Open Source community isn't like that, but bitdowntoc is unlikely\nto be used in a commercial product anyway. Thus, the license is only here to ensure\nno one will suddenly make a non-free bitdowntoc clone.\n\nIf you have any problem with this, feel free to share your thoughts in an issue,\nI will be glad to discuss (and maybe revisit) it!\n\nUntil then, please to do whatever you want with bitdowntoc, as long as your\nheart is pure.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderlin%2Fbitdowntoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fderlin%2Fbitdowntoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderlin%2Fbitdowntoc/lists"}