{"id":16102369,"url":"https://github.com/sshaw/markdown_usage","last_synced_at":"2026-04-13T17:34:08.022Z","repository":{"id":56882805,"uuid":"118870570","full_name":"sshaw/markdown_usage","owner":"sshaw","description":"Output a colorized version of your program's usage using a Markdown document embedded in your script, from your project's README, or anywhere else.","archived":false,"fork":false,"pushed_at":"2018-01-31T00:52:31.000Z","size":76,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-03T12:52:59.058Z","etag":null,"topics":["cli","command-line-tool","markdown","option-parser","readme","ruby","terminal","tty"],"latest_commit_sha":null,"homepage":"","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/sshaw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-25T06:11:15.000Z","updated_at":"2018-01-28T01:47:26.000Z","dependencies_parsed_at":"2022-08-20T22:31:03.610Z","dependency_job_id":null,"html_url":"https://github.com/sshaw/markdown_usage","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sshaw/markdown_usage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaw%2Fmarkdown_usage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaw%2Fmarkdown_usage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaw%2Fmarkdown_usage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaw%2Fmarkdown_usage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sshaw","download_url":"https://codeload.github.com/sshaw/markdown_usage/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaw%2Fmarkdown_usage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31762616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T15:25:13.801Z","status":"ssl_error","status_checked_at":"2026-04-13T15:25:09.162Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cli","command-line-tool","markdown","option-parser","readme","ruby","terminal","tty"],"created_at":"2024-10-09T18:53:40.400Z","updated_at":"2026-04-13T17:34:07.993Z","avatar_url":"https://github.com/sshaw.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MarkdownUsage\n\n[![Build Status](https://secure.travis-ci.org/sshaw/markdown_usage.svg)](https://secure.travis-ci.org/sshaw/markdown_usage)\n\nOutput a colorized version of your program's usage using a Markdown document embedded in your script, from your project's README, or anywhere else.\n\n`MarkdownUsage` uses [`TTY::Markdown`](https://github.com/piotrmurach/tty-markdown) to make\nyour program's usage look like this:\n\n![MarkdownUsage output](usage.png)\n\nIf your program does not use Ruby or you want to minimize your dependencies use [the `markdown_usage` Script](#markdown_usage-command).\n\n## Installation\n\n[Ruby](https://www.ruby-lang.org/en/downloads/) is required.\n\nMarkdownUsage can be installed via RubyGems:\n\n    $ gem install markdown_usage\n\nOr via Bundler. Add this line to your application's `Gemfile`:\n\n```ruby\ngem \"markdown_usage\"\n```\n\nAnd then execute:\n\n    $ bundle\n\n## Usage\n\nWhen it's time to display your program's usage call `MarkdownUsage.print` or `MarkdownUsage()` with the [desired configuration options](#options).\nBy default it will look for the usage in [the invoking code's data section](http://ruby-doc.org/docs/keywords/1.9/Object.html#method-i-__END__),\noutput it to `stdout`, and call `exit 0`.\n\nFor more info see [Options](#options).\n\n### Using `__END__`\n\nHere's an example script:\n\n```rb\n#!/usr/bin/ruby\n\nrequire \"optparse\"\nrequire \"markdown_usage\"\n\nOptionParser.new do |opts|\n  opts.on \"-h\", \"--help\" do\n    MarkdownUsage.print\n  end\n\n  opts.on \"-o\", \"--do-something\", \"My great option\" do |opt|\n    # ...\n  end\nend.parse!\n\n# The rest of your amazing program\n\n__END__\n**my_command** - command to do somethangz\n\n## Usage\n\n`my_command [options] file`\n\n  * `-a`      This does foo\n  * `-b``MAP` Mapping for something\n\n## MAP\n\nMap is a list of blah pairs\n\n## More Info\n\n- [Docs](http://example.com/docs)\n- [Bugs](http://example.com/bugs)\n\n```\n\n\nIf you're using this and releasing your script as a gem it must be installed via `gem install --no-wrappers my_gem`\nOtherwise, the data section will not be available to due the wrapper script added by RubyGems.\n\nIn this case it's better to use a file for the usage\n\n### Using a File\n\nTo extract the program's usage from the `Usage` section of your project's README:\n\n```rb\nMarkdownUsage.print(:source =\u003e \"README\", :sections =\u003e \"Usage\")\n```\n\nThis will look for a file named `README.md` or `README.markdown` in your project's root directory.\n\nMultiple sections can be extracted:\n\n```rb\nMarkdownUsage.print(:source =\u003e \"README\", :sections =\u003e %w[Usage Support])\n```\n\nTo use a different file specify its path:\n\n```rb\nMarkdownUsage.print(:source =\u003e \"path/to/README.md\")\n```\n\nWhen specifying a path you must provide the appropriate extension.\n\n### Options\n\n`MarkdownUsage.print` and `MarkdownUsage()` accept a `Hash` of the following options:\n\n#### `:exit`\n\nExit status to use after printing usage, defaults to `0`.\n\nSet this to `false` to prevent `exit` from being called.\n\n#### `:output`\n\nFile handle to output the usage on. Defaults to `$stdout`. The given handle must\nhave a `#puts` method.\n\nThe usage will *always* contain terminal escape codes.\n\n#### `:sections`\n\nSections to extract from the `:source`. These must be the headings without the\nleading or trailing heading format characters.\n\nIf the heading text has other formatting characters, they must be included (see [Examples](#examples)).\n\nCan be a `String` or an `Array` of strings.\n\n#### `:source`\n\nLocation of usage Markdown to print, defaults to your program's data (`__END__`) section.\n\nTo load a Markdown `README` from your project's root directory set this to `README`.\n\nRelative paths will be loaded relative to your project's root directory.\n\n#### `:raise_errors`\n\nIf `true` a `MarkdownUsage::Error` will be raised when `MarkdownUsage` encounters a problem.\nIf `false` a warning is sent to `stderr` instead.\n\n## `markdown_usage` Command\n\nEmbed or output a colorized version of your program's usage from a Markdown document.\n\n### Usage\n\n```\nmarkdown_usage [-hv] [-s sections] [-o output] markdown_doc\n```\n\n`markdown_doc` is a file containing the Markdown to use.\n\n- `-h` show this help menu\n- `-o` `output`   where to output the colorized usage, defaults to `stdout`\n- `-s` `sections` sections to extract from `markdown_doc`\n- `-v` show the version\n\n#### `output`\n\nThis can be a file or a script. If it's a script it will be added to the script's data section.\nExisting data section content will be overwritten.\n\nWe assume `output` is a script if one of the following are true:\n\n- It ends in `.rb` or `.pl` (these languages support data sections)\n- It contains  *nix shebang on the first line for `ruby` or `perl` e.g., `#!/usr/bin/env ruby`\n\n#### `sections`\n\nThese must be the headings without leading or trailing heading format characters.\nIf the heading text has other formatting characters, they must be included (see [Examples](#examples)).\n\nMultiple sections can be separated by a comma.\n\n### Examples\n\nOutput the section `Usage` from `README.md` to `USAGE`:\n\n```\nmarkdown_usage -s Usage README.md \u003e USAGE\n```\n\nOutput the sections `Usage` and `More Info` from `README.md` to `USAGE`:\n\n```\nmarkdown_usage -s 'Usage,More Info' README.md \u003e USAGE\n```\n\nAdd the following formatted section to the data section of `script.rb`:\n\n```\nmarkdown_usage -s '`markdown_usage` Command' -o script.rb README.md\n```\n\n## See Also\n\n- [`TTY::Markdown`](https://github.com/piotrmurach/tty-markdown) - without this there would be no `MarkdownUsage`\n- [tty_markdown](http://github.com/dapplebeforedawn/tty_markdown)\n- Perl's [`Pod::Usage`](https://metacpan.org/pod/Pod::Usage) - the inspiration for `MarkdownUsage`\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshaw%2Fmarkdown_usage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsshaw%2Fmarkdown_usage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshaw%2Fmarkdown_usage/lists"}