{"id":13664878,"url":"https://github.com/piotrmurach/tty-markdown","last_synced_at":"2025-04-10T01:05:55.312Z","repository":{"id":53127654,"uuid":"118378379","full_name":"piotrmurach/tty-markdown","owner":"piotrmurach","description":"Convert a markdown document or text into a terminal friendly output.","archived":false,"fork":false,"pushed_at":"2025-04-09T20:37:48.000Z","size":503,"stargazers_count":309,"open_issues_count":0,"forks_count":16,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-09T21:37:06.374Z","etag":null,"topics":["cli","console","console-application","markdown","rubygem","terminal","tty"],"latest_commit_sha":null,"homepage":"https://ttytoolkit.org","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/piotrmurach.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"github":"piotrmurach"}},"created_at":"2018-01-21T22:10:27.000Z","updated_at":"2025-04-09T20:37:53.000Z","dependencies_parsed_at":"2024-01-03T00:30:50.100Z","dependency_job_id":"1aacaf68-019f-4033-845e-9eb8ae38e59b","html_url":"https://github.com/piotrmurach/tty-markdown","commit_stats":{"total_commits":267,"total_committers":9,"mean_commits":"29.666666666666668","dds":"0.048689138576779034","last_synced_commit":"ea498731cd47cf822b167c3b8aeed2fa0685b6d1"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piotrmurach","download_url":"https://codeload.github.com/piotrmurach/tty-markdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119429,"owners_count":21050754,"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":["cli","console","console-application","markdown","rubygem","terminal","tty"],"created_at":"2024-08-02T05:03:10.906Z","updated_at":"2025-04-10T01:05:55.291Z","avatar_url":"https://github.com/piotrmurach.png","language":"Ruby","funding_links":["https://github.com/sponsors/piotrmurach"],"categories":["Ruby","Happy Exploring 🤘"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://ttytoolkit.org\"\u003e\u003cimg width=\"130\" src=\"https://github.com/piotrmurach/tty/raw/master/images/tty.png\" alt=\"TTY Toolkit logo\" /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n# TTY::Markdown\n\n[![Gem Version](https://badge.fury.io/rb/tty-markdown.svg)][gem]\n[![Actions CI](https://github.com/piotrmurach/tty-markdown/actions/workflows/ci.yml/badge.svg)][gh_actions_ci]\n[![Build status](https://ci.appveyor.com/api/projects/status/k4vub4koct329ggd?svg=true)][appveyor]\n[![Maintainability](https://api.codeclimate.com/v1/badges/1656060107c73ac42c2b/maintainability)][codeclimate]\n[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-markdown/badge.svg)][coverage]\n\n[gem]: https://badge.fury.io/rb/tty-markdown\n[gh_actions_ci]: https://github.com/piotrmurach/tty-markdown/actions/workflows/ci.yml\n[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-markdown\n[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-markdown/maintainability\n[coverage]: https://coveralls.io/github/piotrmurach/tty-markdown\n\n\u003e Convert a Markdown document or text into a terminal friendly output.\n\n**TTY::Markdown** provides a Markdown processing component for the\n[TTY Toolkit](https://github.com/piotrmurach/tty).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"tty-markdown\"\n```\n\nAnd then execute:\n\n```shell\n$ bundle\n```\n\nOr install it yourself as:\n\n```shell\n$ gem install tty-markdown\n```\n\n## Contents\n\n* [1. Usage](#1-usage)\n  * [1.1 Header](#11-header)\n  * [1.2 List](#12-list)\n  * [1.3 Definition List](#13-definition-list)\n  * [1.4 Link](#14-link)\n  * [1.5 Blockquote](#15-blockquote)\n  * [1.6 Code and Syntax Highlighting](#16-code-and-syntax-highlighting)\n  * [1.7 Table](#17-table)\n  * [1.8 Horizontal Rule](#18-horizontal-rule)\n  * [1.9 Footnotes](#19-footnotes)\n* [2. Options](#2-options)\n  * [2.1 :mode](#21-mode)\n  * [2.2 :theme](#22-theme)\n  * [2.3 :width](#23-width)\n  * [2.4 :symbols](#24-symbols)\n  * [2.5 :indent](#25-indent)\n  * [2.6 :color](#26-color)\n* [3. Command line tool](#3-command-line-tool)\n\n## 1. Usage\n\nUsing `parse` method, you can transform a Markdown string into a terminal\nformatted content:\n\n```ruby\nparsed = TTY::Markdown.parse(\"# Hello\")\nputs parsed\n# =\u003e \"\\e[36;1mHello\\e[0m\\n\"\n```\n\nThe `parse_file` allows you to transform a Markdown document into a terminal\nformatted output:\n\n```ruby\nparsed = TTY::Markdown.parse_file('example.md')\nputs parsed\n```\n\n### 1.1 Header\n\nParsing the following Markdown headers:\n\n```markdown\nTTY::Markdown\n=============\n\n**tty-markdown** converts markdown document into a terminal friendly output.\n\n## Examples\n\n### Nested list items\n```\n\nThe terminal output looks like this:\n\n![Headers example](assets/headers.png)\n\n### 1.2 List\n\nBoth numbered and unordered lists are supported. Given a Markdown:\n\n```markdown\n- Item 1\n  - Item 2\n  - Item 3\n    - Item 4\n- Item 5\n```\n\nThe parsed output looks like this:\n\n![Unordered list example](assets/list.png)\n\n### 1.3 Definition List\n\nGiven a definition list:\n\n```markdown\nItem 1\n: This is the description for Item 1\n\nItem 2\n: This is the description for Item 2\n: This is another description for Item 2\n```\n\nThe parsed output looks like this:\n\n![Definition list example](assets/definition-list.png)\n\n### 1.4 Link\n\nA Markdown link:\n\n```markdown\n[An inline-style link](https://ttytoolkit.org)\n\n[An inline-style link with title](https://ttytoolkit.org \"TTY Toolkit Homepage\")\n```\n\nThe link text will be rendered with the link next to it:\n\n![Link example](assets/link.png)\n\n### 1.5 Blockquote\n\nGiven a Markdown quote:\n\n```markdown\n\u003e Blockquotes are very handy in email to emulate reply text.\n\u003e This line is part of the same quote.\n\u003e *Oh*, you can put **Markdown** into a blockquote.\n```\n\nThe rendered output looks like this:\n\n![Blockquote example](assets/quote.png)\n\n### 1.6 Code and Syntax Highlighting\n\nThe parser can highlight syntax of many programming languages.\n\nGiven a Markdown codeblock with a language specification:\n\n````markdown\n```ruby\nclass Greeter\n  def hello(name)\n    puts \"Hello #{name}\"\n  end\nend\n```\n````\n\nThe terminal output will look like this:\n\n![Code highlighting example](assets/codeblock.png)\n\n### 1.7 Table\n\nYou can transform tables which understand the Markdown alignment.\n\nFor example, given the following table:\n\n```markdown\n| Tables   |      Are      |  Cool |\n|----------|:-------------:|------:|\n| col 1 is |  left-aligned | $1600 |\n| col 2 is |    centered   |   $12 |\n| col 3 is | right-aligned |    $1 |\n```\n\nThen the terminal output will look like this:\n\n![Table example](assets/table.png)\n\n### 1.8 Horizontal Rule\n\nYou can specify a horizontal rule in Markdown:\n\n```markdown\n***\n```\n\nand then transform it:\n\n```ruby\nparsed = TTY::Markdown.parse(markdown_string)\n```\n\n`puts parsed` will output:\n\n![Horizontal rule example](assets/hr.png)\n\n### 1.9 Footnotes\n\nYou can create footnote references:\n\n```markdown\nIt is not down on any map[^foo]; true places[^bar] never are.\n\n[^foo]: A diagrammatic representation of an area of land or sea.\n[^bar]: A particular position, point, or area in space; a location.\n```\n\nAll footnotes will be displayed with a sequential number and rendered in\nthe terminal like this:\n\n![Footnotes example](assets/footnotes.png)\n\n## 2. Options\n\n### 2.1 `:mode`\n\nBy default the `256` color scheme is used to render code block elements.\n\nUse the `:mode` keyword to specify the maximum number of colors, for example,\nto be `16` ANSI colors:\n\n```ruby\nTTY::Markdown.parse(markdown_string, mode: 16)\n```\n\nThis feature may be handy when working in terminals with limited color support.\n\nBy default, **TTY::Markdown** detects terminal color mode and adjusts output\nautomatically.\n\n### 2.2 `:theme`\n\nUse the `:theme` keyword to change specific Markdown element styles.\n\nFor example, to override styles for the `link` and `list` elements do:\n\n```ruby\nTTY::Markdown.parse(markdown_string, theme: {link: :magenta, list: %i[magenta bold]})\n```\n\nHere's a complete list of element names with corresponding styles:\n\n| Name       | Style                   |\n|------------|-------------------------|\n| `:comment` | `:bright_black`         |\n| `:em`      | `:yellow`               |\n| `:header`  | `%i[cyan bold]`         |\n| `:hr`      | `:yellow`               |\n| `:image`   | `:bright_black`         |\n| `:link`    | `%i[yellow underline]`  |\n| `:list`    | `:yellow`               |\n| `:note`    | `:yellow`               |\n| `:quote`   | `:yellow`               |\n| `:strong`  | `%i[yellow bold]`       |\n| `:table`   | `:yellow`               |\n\nRead the [pastel](https://github.com/piotrmurach/pastel#3-supported-colors)\ndocumentation for all supported styles.\n\n### 2.3 `:width`\n\nUse the `:width` keyword to control the maximum width of the output:\n\n```ruby\nTTY::Markdown.parse(markdown_string, width: 80)\n```\n\nBy default the terminal screen width is used.\n\n### 2.4 `:symbols`\n\nBy default, formatted output includes various Unicode symbols. Use the\n`:symbols` keyword to switch to an ASCII set and/or override individual\nsymbols.\n\n```ruby\nTTY::Markdown.parse(markdown_string, symbols: :ascii)\nTTY::Markdown.parse(markdown_string, symbols: {base: :ascii})\nTTY::Markdown.parse(markdown_string, symbols: {override: {bullet: \"x\"}})\n```\n\nHere's a complete list of symbol names with corresponding ASCII and Unicode\ncharacters:\n\n| Name             | ASCII | Unicode |\n|------------------|-------|---------|\n| `:arrow`         | `-\u003e`  | `»`     |\n| `:bar`           | `\\|`  | `┃`     |\n| `:bottom_center` | `+`   | `┴`     |\n| `:bottom_left`   | `+`   | `└`     |\n| `:bottom_right`  | `+`   | `┘`     |\n| `:bracket_left`  | `[`   | `[`     |\n| `:bracket_right` | `]`   | `]`     |\n| `:bullet`        | `*`   | `●`     |\n| `:diamond`       | `*`   | `◈`     |\n| `:hash`          | `#`   | `#`     |\n| `:hellip`        | `...` | `…`     |\n| `:laquo`         | `\u003c\u003c`  | `«`     |\n| `:laquo_space`   | `\u003c\u003c ` | `« `    |\n| `:ldquo`         | `\"`   | `“`     |\n| `:lsquo`         | `\"`   | `‘`     |\n| `:line`          | `-`   | `─`     |\n| `:mdash`         | `-`   | `—`     |\n| `:mid_center`    | `+`   | `┼`     |\n| `:mid_left`      | `+`   | `├`     |\n| `:mid_right`     | `+`   | `┤`     |\n| `:ndash`         | `-`   | `-`     |\n| `:paren_left`    | `(`   | `(`     |\n| `:paren_right`   | `)`   | `)`     |\n| `:pipe`          | `\\|`  | `│`     |\n| `:raquo`         | `\u003e\u003e`  | `»`     |\n| `:raquo_space`   | ` \u003e\u003e` | ` »`    |\n| `:rdquo`         | `\"`   | `”`     |\n| `:rsquo`         | `\"`   | `’`     |\n| `:top_center`    | `+`   | `┬`     |\n| `:top_left`      | `+`   | `┌`     |\n| `:top_right`     | `+`   | `┐`     |\n\n### 2.5 `:indent`\n\nBy default, any content apart from the main `h1` header is indented with `2`\nspaces. Use the `:indent` keyword to provide custom indent or no indent at all:\n\n```ruby\nTTY::Markdown.parse(markdown_string, indent: 0)\n```\n\n### 2.6 `:color`\n\nUse the `:color` keyword to control when to apply coloring to various document\nelements. Valid values are `:always`, `:auto` or `:never`. The default `:auto`\nvalue automatically detects whether to color the output or not.\n\nFor example, to always color content regardless of terminal support:\n\n```ruby\nTTY::Markdown.parse(markdown_string, color: :always)\n```\n\n### 3. Command line tool\n\nInstall the [tty-markdown-cli](https://github.com/piotrmurach/tty-markdown-cli)\nto use the `tty-markdown` executable in the terminal:\n\n```bash\n$ tty-markdown README.md\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies.\nThen, run `rake spec` to run the tests. You can also run `bin/console`\nfor an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\nTo release a new version, update the version number in `version.rb`, and then\nrun `bundle exec rake release`, which will create a git tag for the version,\npush git commits and tags, and push the `.gem` file to\n[rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/piotrmurach/tty-markdown.\nThis project is intended to be a safe, welcoming space for collaboration,\nand contributors are expected to adhere to the\n[code of conduct](https://github.com/piotrmurach/tty-markdown/blob/master/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the TTY::Markdown project’s codebases, issue trackers,\nchat rooms and mailing lists is expected to follow the\n[code of conduct](https://github.com/piotrmurach/tty-markdown/blob/master/CODE_OF_CONDUCT.md).\n\n## Copyright\n\nCopyright (c) 2018 Piotr Murach. See\n[LICENSE.txt](https://github.com/piotrmurach/tty-markdown/blob/master/LICENSE.txt)\nfor further details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiotrmurach%2Ftty-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-markdown/lists"}