{"id":39403152,"url":"https://github.com/rlauer6/markdown-utils","last_synced_at":"2026-01-18T03:26:57.080Z","repository":{"id":75534190,"uuid":"126629407","full_name":"rlauer6/markdown-utils","owner":"rlauer6","description":"Utility for adding a table of contents to markdown and/or rendering the markdown using GitHub API","archived":false,"fork":false,"pushed_at":"2025-08-26T20:02:11.000Z","size":42,"stargazers_count":3,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-27T03:33:08.859Z","etag":null,"topics":["markdown","toc-generator"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rlauer6.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2018-03-24T18:38:40.000Z","updated_at":"2025-08-26T20:02:15.000Z","dependencies_parsed_at":"2025-08-26T21:24:02.228Z","dependency_job_id":"a346c861-3324-4487-b3ab-cf589f0fc5e9","html_url":"https://github.com/rlauer6/markdown-utils","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/rlauer6/markdown-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlauer6%2Fmarkdown-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlauer6%2Fmarkdown-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlauer6%2Fmarkdown-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlauer6%2Fmarkdown-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rlauer6","download_url":"https://codeload.github.com/rlauer6/markdown-utils/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlauer6%2Fmarkdown-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28528038,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"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":["markdown","toc-generator"],"created_at":"2026-01-18T03:26:51.298Z","updated_at":"2026-01-18T03:26:57.026Z","avatar_url":"https://github.com/rlauer6.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Table of Contents\n\n* [README](#readme)\n* [Installation](#installation)\n  * [Prerequisites](#prerequisites)\n  * [Building and Deploying](#building-and-deploying)\n  * [Building from CPAN](#building-from-cpan)\n* [Usage](#usage)\n* [Tips \u0026 Tricks](#tips--tricks)\n  * [\u0026#64;DATE(format)\u0026#64;](#dateformat)\n  * [\u0026#64;GIT_EMAIL\u0026#64;](#gitemail)\n  * [\u0026#64;GIT_USER\u0026#64;](#gituser)\n  * [\u0026#64;TOC\u0026#64;](#toc)\n  * [\u0026#64;TOC_BACK(optional text)\u0026#64;](#tocbackoptional-text)\n  * [Custom TOC Title](#custom-toc-title)\n  * [Prevent heading from being included in table of contents](#prevent-heading-from-being-included-in-table-of-contents)\n* [Rendering](#rendering)\n* [License](#license)\n\n__Updated 2025-10-09__ by anonymouse \u003crclauer@gmail.com\u003e\n\n# README\n\nA quick search regarding how to get a table of contents into my\nmarkdown yielded only a few hits or projects that seemed a little weighty\nto me, so here's a little Perl script with just a few\ndependencies that you might find useful.  See [Usage](#usage) for more\ninformation.\n\nThe script will render your markdown as HTML using either the [GitHub\nAPI](https://docs.github.com/en/rest/markdown) or the Perl module [Text::Markdown::Discount](https://metacpan.org/pod/Text::Markdown::Discount)\n\nA default stylesheet will be applied but you can provide your own\nstyle sheet as well.\n\n# Installation\n\n## Prerequisites\n\nThe script has been tested with these versions, but others might work\ntoo.\n\n| Module                   | Version |\n|--------------------------|---------|\n| `Class::Accessor::Fast`  | 0.51  |\n| `Date::Format`           | 2.24  |\n| `HTTP::Request`          | 6.00  |\n| `IO::Scalar`             | 2.113 |\n| `JSON`                   | 4.03  |\n| `LWP::UserAgent`         | 6.36  |\n| `Readonly`               | 2.05  |\n\n## Building and Deploying\n\nThe build will now create a CPAN distribution.\n\n```\ngit clone https://github.com/rlauer6/markdown-utils.git\nmake \u0026\u0026 make cpan\n```\n\nTo deploy the application use `cpanm`\n\n```\ncurl -L https://cpanmin.us | perl - --sudo App::cpanminus\ncpanm -n -v cpan/Markdown-Render-*.tar.gz\n```\n\n## Building from CPAN\n\n```\ncpanm -v Markdown::Render\n```\n\n# Usage\n\n```\nUsage:\n     md-utils.pl options [markdown-file]\n\n    Utility to add a table of contents and other goodies to your GitHub\n    flavored markdown.\n\n    *   @TOC@ where you want to see your TOC.\n\n    *   @TOC_BACK@ to insert an internal link to TOC\n\n    *   @DATE(format-str)@ where you want to see a formatted date\n\n    *   @GIT_USER@ where you want to see your git user name\n\n    *   @GIT_EMAIL@ where you want to see your git email address\n\n    *   the --render option to render the HTML for the markdown\n\n  Examples:\n     md-utils.pl README.md.in \u003e README.md\n\n     md-utils.pl -r README.md.in\n\n  Options:\n     -B, --body     default is to add body tag, use --nobody to prevent    \n     -b, --both     interpolates intermediate file and renders HTML\n     -c, --css      css file\n     -e, --engine   github, text_markdown (default: github)\n     -h             help\n     -i, --infile   input file, default: STDIN\n     -m, --mode     for GitHub API mode is 'gfm' or 'markdown' (default: markdown)\n     -n, --no-titl  do not print a title for the TOC\n     -o, --outfile  outfile, default: STDOUT\n     -r, --render   render only, does NOT interpolate keywords\n     -R, --raw      return raw HTML from engine\n     -t, --title    string to use for a custom title, default: \"Table of Contents\"\n     -v, --version  version\n     -N, --nocss    do not add any CSS link\n\n  Tips:\n    *   Use !# to prevent a header from being include in the table of\n        contents.\n\n        Add your own custom back to TOC message @TOC_BACK(Back to Index)@\n\n    *   Date format strings are based on format strings supported by the\n        Perl module 'Date::Format'.\n\n        The default format is %Y-%m-%d if not format is given.\n\n    *   use the --nobody tag to return the HTML without the\n        \u003chtml\u003e\u003cbody\u003e\u003c/body\u003e\u003c/html\u003e wrapper.\n\n        \"--raw\" mode will also return HTML without wrapper.\n```\n\n# Tips \u0026 Tricks\n\n1. Add \u0026#64;TOC\u0026#64; somewhere in your markdown\n1. Use !# to prevent heading from being part of the table of contents\n1. Finalize your markdown...\n   ```\n   cat README.md.in | md-utils.pl \u003e README.md\n   ```\n1. ...or...kick it old school with a `Makefile` if you like\n   ```\n   FILES = \\\n       README.md.in\n\n   MARKDOWN=$(FILES:.md.in=.md)\n   HTML=$(MARKDOWN:.md=.html)\n   \n   # interpolate the custom markdown keywords\n   $(MARKDOWN): % : %.in\n       md-utils $\u003c \u003e $@\n   \n   $(HTML): $(MARKDOWN)\n       md-utils -r $\u003c \u003e $@\n   \n   all: $(MARKDOWN) $(HTML)\n   \n   markdown: $(MARKDOWN)\n   \n   html: $(HTML)\n   \n   clean:\n       rm -f $(MARKDOWN) $(HTML)\n   ```\n1. ...and then...\n    ```\n    make all\n    ```\n\n## \u0026#64;DATE(format)\u0026#64;\n\nAdd the current date using a custom format.  Essentially calls the\nPerl function `time2str`.  See `perldoc Date::Format`.\n\nIf no format is present the default is %Y-%m-%d (YYYY-MM-DD).\n\n_Best practice would be to use a `Makefile` to generate your final\n`README.md` from your `README.md.in` template as shown\n[above](#usage) and generate your `README.md` as the last step before\npushing your branch to a repository._\n\nExample:\n\n\u0026#64;`DATE(%Y-%m-%d)`\u0026#64;\n\n## \u0026#64;GIT_EMAIL\u0026#64;\n## \u0026#64;GIT_USER\u0026#64;\n\nIf you've done something like:\n\n```\ngit config --global user.name \"Fred Flintstone\"\ngit config --global user.email \"fflintstone@bedrock.org\"\n```\n\nor\n\n```\ngit config --local user.name \"Fred Flintstone\"\ngit config --local user.email \"fflintstone@bedrock.org\"\n```\n\n...then you can expect to see those in your markdown, otherwise don't\nuse the tags.\n\n[Back to Top](#table-of-contents)\n\n## \u0026#64;TOC\u0026#64;\n\nAdd this tag anywhere in your markdown in include a table of contents.\n\n## \u0026#64;TOC_BACK(optional text)\u0026#64;\n\nAdd \u0026#64;TOC_BACK\u0026#64; anywhere in your markdown template to insert an\ninternal link back to the table of contents.\n\n@`TOC_BACK`@\n\n@`TOC_BACK(Back to Index)`@\n\n[Back to Top](#table-of-contents)\n\n## Custom TOC Title\n\nUse the `--no-title` option if you don't want the script to insert a\nheader for the TOC.\nUse the `--title` option if you want a custom header for the TOC.\n\n## Prevent heading from being included in table of contents\n\nPrecede the heading level with bang (!) and that heading will not be\nincluded in the table of contents.\n\n[Back to Top](#table-of-contents)\n\n# Rendering\n\nUsing the [GiHub rendering\nAPI](https://developer.github.com/v3/markdown/), you can create HTML\npretty easily. So if you want to preview your markdown...you might try:\n\n```\njq --slurp --raw-input '{\"text\": \"\\(.)\", \"mode\": \"markdown\"}' \u003c README.md | \\\n  curl -s --data @- https://api.github.com/markdown\n```\n\n__...but alas you might find that your internal links don't work in\nthat rendered HTML...__\n\nNever fear...the `--render` option of this utility will go ahead and set that right for\nyou and munge the HTML so that internal links really work...or at\nleast they do for me.\n\n```\nmd-utils --render README.md \u003e README.html\n```\n\n[Back to Top](#table-of-contents)\n\n# License\n\nThis software is licensed under the same terms as Perl.\n\n[Back to Top](#table-of-contents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frlauer6%2Fmarkdown-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frlauer6%2Fmarkdown-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frlauer6%2Fmarkdown-utils/lists"}