{"id":13878648,"url":"https://github.com/bkuhlmann/tocer","last_synced_at":"2025-04-05T08:05:13.028Z","repository":{"id":45695576,"uuid":"46237607","full_name":"bkuhlmann/tocer","owner":"bkuhlmann","description":"A command line interface for generating Markdown table of contents.","archived":false,"fork":false,"pushed_at":"2025-03-25T02:13:09.000Z","size":941,"stargazers_count":46,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T07:04:25.878Z","etag":null,"topics":["markdown","table-of-contents","toc"],"latest_commit_sha":null,"homepage":"https://alchemists.io/projects/tocer","language":"Ruby","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/bkuhlmann.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.adoc","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["bkuhlmann"]}},"created_at":"2015-11-15T21:53:21.000Z","updated_at":"2025-03-25T02:13:13.000Z","dependencies_parsed_at":"2023-02-19T01:01:43.126Z","dependency_job_id":"8ca0ffff-15a9-4e32-962f-383cc7c67e30","html_url":"https://github.com/bkuhlmann/tocer","commit_stats":{"total_commits":776,"total_committers":2,"mean_commits":388.0,"dds":"0.0012886597938144284","last_synced_commit":"50a967326ea7a3eaaae5b3efd0c3371f0b26b141"},"previous_names":[],"tags_count":110,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Ftocer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Ftocer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Ftocer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Ftocer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bkuhlmann","download_url":"https://codeload.github.com/bkuhlmann/tocer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305933,"owners_count":20917208,"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":["markdown","table-of-contents","toc"],"created_at":"2024-08-06T08:01:55.636Z","updated_at":"2025-04-05T08:05:13.011Z","avatar_url":"https://github.com/bkuhlmann.png","language":"Ruby","funding_links":["https://github.com/sponsors/bkuhlmann"],"categories":["Ruby"],"sub_categories":[],"readme":":toc: macro\n:toclevels: 5\n:figure-caption!:\n\n= Tocer\n\nTocer (a.k.a. Table of Contenter) is a command line interface for generating table of contents for\nMarkdown files. Use this tool to automatically manage and update your documentation with minimal\neffort. Works on single files or multiple files within nested directory structures.\n\ntoc::[]\n\n== Features\n\n* Supports Markdown ATX-style headers. Example: `# Header`.\n** Does not support header suffixes. Example: `# Header #`.\n** Does not support header prefixes without spaces. Example: `#Header`.\n* Supports table of contents generation for single or multiple files.\n* Supports custom label. Default: `## Table of Contents`.\n* Supports file list filtering. Default: `\"README.md\"`.\n* Prepends table of contents to Markdown documents that don’t have table of contents.\n* Rebuilds Markdown documents that have existing table of contents.\n\n== Requirements\n\n. A UNIX-based system.\n. link:https://www.ruby-lang.org[Ruby].\n\n== Setup\n\nTo install _with_ security, run:\n\n[source,bash]\n----\n# 💡 Skip this line if you already have the public certificate installed.\ngem cert --add \u003c(curl --compressed --location https://alchemists.io/gems.pem)\ngem install tocer --trust-policy HighSecurity\n----\n\nTo install _without_ security, run:\n\n[source,bash]\n----\ngem install tocer\n----\n\nYou can also add the gem directly to your project:\n\n[source,bash]\n----\nbundle add tocer\n----\n\n== Usage\n\n=== Command Line Interface (CLI)\n\nFrom the command line, run: `tocer --help`\n\nimage:https://alchemists.io/images/projects/tocer/screenshots/usage.png[Usage,width=581,height=326,role=focal_point]\n\nTo generate the table of contents at a specific position within your Markdown files, add the\nfollowing lines to your file(s) prior to generation:\n\n[source,markdown]\n----\n\u003c!-- Tocer[start] --\u003e\n\u003c!-- Tocer[finish] --\u003e\n----\n\nIn the case that Tocer has auto-generated a table of contents for a Markdown file; the existing\ntable of contents has become stale; or placement of the table of contents has changed, you can\nre-run Tocer on that file to auto-update it with new table of contents.\n\n=== Customization\n\nThis gem can be configured via a global configuration: `~/.config/tocer/configuration.yml`.\n\nIt can also be configured via link:https://alchemists.io/projects/xdg[XDG] environment\nvariables.\n\nThe default configuration is as follows:\n\n[source,yaml]\n----\nlabel: \"## Table of Contents\"\npatterns:\n  - \"README.md\"\nroot_dir: \".\"\n----\n\nFeel free to take this default configuration, modify, and save as your own custom\n`configuration.yml`.\n\nThe `configuration.yml` file can be configured as follows:\n\n* `label`: The header label for the table of contents.\n* `patterns`: The list of included files.\n* `root_dir`: The root path to use for processing files.\n\nThere are multiple ways the include list can be defined. Here are some examples:\n\n[source,yaml]\n----\n# Use an empty array to ignore all files:\n:patterns: []\n\n# Use an array of wildcards for groups of files with similar extensions:\n:patterns:\n  - \"*.md\"\n  - \"*.mkd\"\n  - \"*.markdown\"\n\n# Use a mix of wild cards and relative names/paths to customized as necessary:\n:patterns:\n  - \"README.md\"\n  - \"docs/*.md\"\n  - \"*.markdown\"\n\n# Use a recursive glob to traverse and update all sub-directories:\n:patterns:\n  - \"**/*.md\"\n----\n\n=== Rake\n\nYou can add Rake support by adding the following to your `Rakefile`:\n\n[source,ruby]\n----\nbegin\n  require \"tocer/rake/register\"\nrescue LoadError =\u003e error\n  puts error.message\nend\n\nTocer::Rake::Register.call\n----\n\nOnce required and registered, the following tasks will be available (i.e. `bundle exec rake -T`):\n\n....\nrake toc[label,includes]   # Insert/Update Table of Contents\n....\n\nYou can invoke the task as follows (quotes are only necessary if spaces are used):\n\n[source,bash]\n----\nrake toc[\"## Example, *.md\"]\n----\n\n== Development\n\nTo contribute, run:\n\n[source,bash]\n----\ngit clone https://github.com/bkuhlmann/tocer\ncd tocer\nbin/setup\n----\n\nYou can also use the IRB console for direct access to all objects:\n\n[source,bash]\n----\nbin/console\n----\n\n== Tests\n\nTo test, run:\n\n[source,bash]\n----\nbin/rake\n----\n\n== link:https://alchemists.io/policies/license[License]\n\n== link:https://alchemists.io/policies/security[Security]\n\n== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]\n\n== link:https://alchemists.io/policies/contributions[Contributions]\n\n== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]\n\n== link:https://alchemists.io/projects/tocer/versions[Versions]\n\n== link:https://alchemists.io/community[Community]\n\n== Credits\n\n* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].\n* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkuhlmann%2Ftocer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbkuhlmann%2Ftocer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkuhlmann%2Ftocer/lists"}