{"id":16958442,"url":"https://github.com/dohliam/tocdown","last_synced_at":"2025-04-11T22:08:10.256Z","repository":{"id":27668386,"uuid":"31154327","full_name":"dohliam/tocdown","owner":"dohliam","description":"A table of contents generator for markdown","archived":false,"fork":false,"pushed_at":"2020-07-08T21:58:35.000Z","size":48,"stargazers_count":13,"open_issues_count":0,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-11T22:08:05.008Z","etag":null,"topics":["github-flavored-markdown","javascript","markdown","markdown-toc","table-of-contents","toc"],"latest_commit_sha":null,"homepage":"https://dohliam.github.io/tocdown/","language":"Ruby","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/dohliam.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":"2015-02-22T05:56:51.000Z","updated_at":"2024-11-17T15:34:57.000Z","dependencies_parsed_at":"2022-09-08T02:34:58.787Z","dependency_job_id":null,"html_url":"https://github.com/dohliam/tocdown","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dohliam%2Ftocdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dohliam%2Ftocdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dohliam%2Ftocdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dohliam%2Ftocdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dohliam","download_url":"https://codeload.github.com/dohliam/tocdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248487713,"owners_count":21112191,"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-flavored-markdown","javascript","markdown","markdown-toc","table-of-contents","toc"],"created_at":"2024-10-13T22:42:36.887Z","updated_at":"2025-04-11T22:08:10.221Z","avatar_url":"https://github.com/dohliam.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tocdown - A table of contents generator for markdown\n\nTocdown is a general purpose table of contents (TOC) generator that takes markdown as input. There is a command-line version written in Ruby and a Javascript version with identical functionality that can be used in a browser.\n\n\u003c!-- TocDown Begin --\u003e\n* [1 Rationale](#rationale)\n* [2 Usage](#usage)\n  * [2.1 General guidelines](#general-guidelines)\n  * [2.2 toc.rb](#tocrb)\n    * [2.2.1 Options](#options)\n    * [2.2.2 test.md](#testmd)\n  * [2.3 toclib.rb](#toclibrb)\n  * [2.4 toc.js](#tocjs)\n    * [2.4.1 Shortcut keys](#shortcut-keys)\n* [3 To do](#to-do)\n* [4 Credits](#credits)\n* [5 License](#license)\n\u003c!-- TocDown End --\u003e\n\n## Rationale\n\nThere are several existing ways to generate a table of contents from a given markdown file, but most of them focus on outputting unordered html lists, and generally lack options for tweaking the output.\n\nThe need for a flexible table of contents generator arose when it became clear that none of the available solutions were able to generate a plain text or markdown TOC in numbered [ISO 2145 format](https://en.wikipedia.org/wiki/ISO_2145).\n\nISO 2145 provides a specification for the numbering of divisions and subdivisions in written documents, whose format is essentially:\n\n    1\n      1.1\n      1.2\n        1.2.1\n        1.2.2\n      1.3\n    2\n\nIt is possible to number the section headings in a document according to ISO 2145 format using pandoc (with the command `pandoc --number-sections`), but only for pdf or html output. It can also generate a very nice table of contents (with `pandoc --toc`), but this appears to only work for pdf output.\n\nTocdown generates ISO 2145-compliant tables of contents by default, though both numbering and indentation can be optionally turned off. Its non-interactive mode is also suitable for command-line piping or as part of a toolchain (for example, to automatically include a table of contents for each file in a directory).\n\n## Usage\n\nTocdown comes in two versions: toc.rb (written in Ruby) and toc.js (written in Javascript), whose feature sets are identical.\n\n### General guidelines\n\nIn markdown, heading levels are determined by the number of `#` characters at the beginning of a line. Thus, a line beginning with `# A heading` would be equivalent to `\u003ch1\u003e` in HTML markup, or Heading 1.\n\nHowever, since Heading 1 is usually used for the title of a document, it is by default ignored in both toc.rb and toc.js. That means the top level (**TOC level 1**) is by default `##` (`\u003ch2\u003e`) or Heading 2, as in this README.\n\nThe above behaviour can be changed by selecting the _Include Heading 1 (Title)_ option, in which case Heading 1 will be **TOC level 1**, and Heading 2 will be **TOC level 2** etc.\n\nIt is also possible to start level numbering at zero, using the _Allow zero-level heading_ option. This means that the top level of the document (whether Heading 1 or Heading 2) will be listed as **0** in the TOC. Sub-headings will be listed as **0.1**, **0.2**, **0.3** etc. This may be useful in cases where, for example, the first heading in the document represents an Introduction or Preface, followed by Chapter or Section 1.\n\n### toc.rb\n\nThe command-line version of tocdown can be used interactively by executing the command `./toc.rb`, or non-interactively by specifying an input filename as a parameter:\n\n    ./toc.rb [options] [filename]\n\nIt is also possible to use the tocdown library from within a script by including the file `toclib.rb`. Further details and examples of using toclib can be found [below](#toclibrb).\n\n#### Options\n\nA number of options are available that change the way the output is processed or displayed. A list of all available options can be viewed by using the `--help` option:\n\n    ./toc.rb --help\n\nCurrently, the following options are available:\n\n* `-b`, `--bullets`: _Non-numbered headings_\n* `-d`, `--heading-depth DEPTH`: _Specify maximum heading depth [between 1 and 6]_\n* `-f`, `--four`: _Use four spaces instead of two for markdown indentation_\n* `-i`, `--no-indent`: _Remove heading indentation_\n* `-l`, `--no-links`: _Remove links to section headings_\n* `-m`, `--markdown`: _Output markdown instead of plain text_\n* `-t`, `--top-level`: _Include top-level heading (Heading 1 / Title)_\n* `-z`, `--zero`: _Allow for zero heading or Chapter 0, e.g. Introduction, Preface etc._\n* `-r`, `--replace-in-file`: _Place the toc in the file it self. `\u003c!-- TocDown Begin --\u003e` and `\u003c!-- TocDown End --\u003e` are required to be present in the file._\n* `-s`, `--scan-after-marker`: Skip headings until `\u003c!-- TocDown Begin --\u003e` marker is located.\n\nOptions can be combined arbitrarily, so e.g., `./toc.rb -mbi` will produce a table of contents in markdown format with non-numbered headings and no indendation.\n\n#### test.md\n\nIf you have downloaded the source package, you can try out tocdown using the provided test.md sample file:\n\n    ./toc.rb test.md\n\nThis will display something similar to the following text on standard output:\n\n    1 Top-level topic\n     1.1 First sub-topic\n      1.1.1 First sub-sub-topic\n       1.1.1.1 First sub-sub-sub-topic\n        1.1.1.1.1 First sub-sub-sub-sub-topic\n     1.2 Second sub-topic\n     1.3 Third sub-topic\n      1.3.1 A sub-sub-topic\n       1.3.1.1 And a sub-sub-sub-topic\n    2 Second top-level topic\n\nIf you specify markdown output with the `-m` option, you will get something like the following result instead:\n\n    * [1 Top-level topic](#top-level-topic)\n      * [1.1 First sub-topic](#first-sub-topic)\n        * [1.1.1 First sub-sub-topic](#first-sub-sub-topic)\n          * [1.1.1.1 First sub-sub-sub-topic](#first-sub-sub-sub-topic)\n            * [1.1.1.1.1 First sub-sub-sub-sub-topic](#first-sub-sub-sub-sub-topic)\n      * [1.2 Second sub-topic](#second-sub-topic)\n      * [1.3 Third sub-topic](#third-sub-topic)\n        * [1.3.1 A sub-sub-topic](#a-sub-sub-topic)\n          * [1.3.1.1 And a sub-sub-sub-topic](#and-a-sub-sub-sub-topic)\n    * [2 Second top-level topic](#second-top-level-topic)\n\nYou can try out the other options in different combinations to see how they affect the output.\n\n### toclib.rb\n\nFor more fine-grained control, the features of tocdown can also be accessed from within a script by including the file `toclib.rb`.\n\nA minimal example script might look like this:\n\n    require_relative 'toclib.rb'\n\n    text = \"## Some markdown text\\n\\nSome more text\\n\\n### A sub-heading\"\n    md_to_toc(text)\n\nThis will return the string `\"1 Some markdown text\\n 1.1 A sub-heading\\n\"`.\n\nYou can also pass in optional parameters to get different results:\n\n    md_to_toc(text, :markdown =\u003e true)\n    md_to_toc(text, :markdown =\u003e true, :noindent =\u003e true)\n\n### toc.js\n\nThe Javascript version of tocdown, `toc.js` was designed to have the same features and functionality as the command-line version. Since it can be accessed in a browser it is convenient for one-offs and short documents (such as this one). The output live updates when configuration options are selected, so it is also useful as a way to see the effect of different options and parameters on a given input text.\n\nOnce you have generated a table of contents, you can preview the output in [Remarkable](https://jonschlinkert.github.io/remarkable/demo/) by clicking the _View TOC in Remarkable_ button.\n\nA fully functioning demo of toc.js can be found [here](http://dohliam.github.io/tocdown/).\n\n#### Shortcut keys\n\nThe input and output boxes can be accessed using keyboard shortcut keys (access keys) for convenience:\n\n* Shortcut modifier key + `.`: **Focus input textarea**\n* Shortcut modifier key + `o`: **Focus output textarea**\n\nThe modifier keys you need to press will differ depending on which browser and operating system you are using. See [here](https://github.com/dohliam/xsampa#access-keys) for a list of common access keys for different browsers.\n\nAll of the options in toc.js are also accessible using access keys:\n\n* Shortcut modifier key + `b`: **Output bulleted list instead of numbered list**\n* Shortcut modifier key + `c`: **Create TOC**\n* Shortcut modifier key + `d`: **Maximum heading depth selector**\n* Shortcut modifier key + `i`: **Remove heading indentation**\n* Shortcut modifier key + `l`: **Remove links to section headings**\n* Shortcut modifier key + `m`: **Output markdown**\n* Shortcut modifier key + `r`: **View TOC in Remarkable**\n* Shortcut modifier key + `s`: **Sample text**\n* Shortcut modifier key + `t`: **Include top-level heading (Heading 1 / Title)**\n* Shortcut modifier key + `z`: **Allow for zero-level heading**\n\n## To do\n\n* Option to output html\n\n## Credits\n\n* [mui](https://github.com/muicss/mui) CSS by @amorey ([MIT](https://github.com/muicss/mui/blob/master/LICENSE.txt)), prototyped using [dropin-minimal-css](https://github.com/dohliam/dropin-minimal-css)\n* [github-corners](https://github.com/tholman/github-corners) by @tholman\n\n## License\n\nMIT -- see LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdohliam%2Ftocdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdohliam%2Ftocdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdohliam%2Ftocdown/lists"}