TTY::Markdown
¶ ↑
Convert a markdown document or text into a terminal friendly output.
TTY::Markdown provides independent markdown processing component for TTY toolkit.
Installation¶ ↑
Add this line to your application's Gemfile:
gem 'tty-markdown'
And then execute:
$ bundle
Or install it yourself as:
$ gem install tty-markdown
Contents¶ ↑
1. Usage¶ ↑
Using parse
method, you can transform a markdown string into a terminal formatted content:
parsed = TTY::Markdown.parse("# Hello") puts parsed # => "\e[36;1mHello\e[0m\n"
The parse_file
allows you to transform a markdown document into a terminal formatted output:
parsed = TTY::Markdown.parse_file('example.md') puts parsed
1.1 Header¶ ↑
Parsing the following markdown headers:
TTY::Markdown ============= **tty-markdown** converts markdown document into a terminal friendly output. ## Examples ### Nested list items
The terminal output looks like this:
1.2 List¶ ↑
Both numbered and unordered lists are supported. Given a markdown:
- Item 1 - Item 2 - Item 3 - Item 4 - Item 5
The parsed output looks like this:
1.3 Definition List¶ ↑
Given a definition list:
Item 1 : This is the description for Item 1 Item 2 : This is the description for Item 2 : This is another description for Item 2
The parsed output looks like this:
1.4 Link¶ ↑
A markdown link:
[An inline-style link](https://ttytoolkit.org) [An inline-style link with title](https://ttytoolkit.org "TTY Toolkit Homepage")
The link text will be rendered with the link next to it:
1.5 Blockquote¶ ↑
Given a markdown quote:
> Blockquotes are very handy in email to emulate reply text. > This line is part of the same quote. > *Oh*, you can put **Markdown** into a blockquote.
The rendered output looks like this:
1.6 Code and Syntax Highlighting¶ ↑
The parser can highlight syntax of many programming languages.
Given a markdown codeblock with a language specification:
markdown ```ruby class Greeter def hello(name) puts "Hello #{name}" end end ```
The terminal output will look like this:
1.7 Table¶ ↑
You can transform tables which understand the markdown alignment.
For example, given the following table:
| Tables | Are | Cool | |----------|:-------------:|------:| | col 1 is | left-aligned | $1600 | | col 2 is | centered | $12 | | col 3 is | right-aligned | $1 |
Then the terminal output will look like this:
1.8 Horizontal Rule¶ ↑
You can specify a horizontal rule in markdown:
***
and then transform it:
parsed = TTY::Markdown.parse(markdown_string)
puts parsed
will output:
1.9 Footnotes¶ ↑
You can create footnote references:
It is not down on any map[^foo]; true places[^bar] never are. [^foo]: A diagrammatic representation of an area of land or sea. [^bar]: A particular position, point, or area in space; a location.
All footnotes will be displayed with a sequential number and rendered in the terminal like this:
2. Options¶ ↑
2.1 :mode
¶ ↑
By default the 256
color scheme is used to render code block elements.
You can change this by specifying maximum number of colors to be 16
ANSI colors:
TTY::Markdown.pasre(markdown_string, mode: 16)
This feature may be handy when working in terminals with limited color support.
By default, TTY::Markdown detects your terminal color mode and adjusts output automatically.
2.2 :theme
¶ ↑
A hash of styles that allows to customize specific elements of the markdown text. By default the following styles are used:
THEME = { em: :yellow, header: [:cyan, :bold], hr: :yellow, link: [:yellow, :underline], list: :yellow, strong: [:yellow, :bold], table: :yellow, quote: :yellow, image: :bright_black, note: :yellow, comment: :bright_black }
In order to provide new styles use :theme
key:
TTY::Markdown.parse(markdown_string, theme: { ... })
2.3 :width
¶ ↑
You can easily control the maximum width of the output by using the :width
key:
TTY::Markdown.parse(markdown_string, width: 80)
By default the terminal screen width is used.
2.4 :symbols
¶ ↑
By default formatting will include various Unicode symbols. You can switch to an included ASCII set and/or override individually with the :symbols
key:
TTY::Markdown.parse(markdown_string, symbols: :ascii) TTY::Markdown.parse(markdown_string, symbols: {base: :ascii}) TTY::Markdown.parse(markdown_string, symbols: {override: {bullet: "x"}})
2.5 :indent
¶ ↑
By default any content apart from the main h1
header is indented with 2
spaces. Use :indent
to provide custom indent or no indent at all:
TTY::Markdown.parse(markdown_string, indent: 0)
2.6 :color
¶ ↑
You can control when to apply coloring to various document elements.
Valid values are :never
, :always
or :auto
. By default :auto
is used which auto detects if coloring can be applied.
For example, to always color content regardless of terminal support do:
TTY::Markdown.parse(markdown_string, color: :always)
3. Command line tool¶ ↑
You can install tty-markdown-cli to use tty-markdown
executable in terminal:
$ tty-markdown README.md
Development¶ ↑
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing¶ ↑
Bug reports and pull requests are welcome on GitHub at github.com/piotrmurach/tty-markdown. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License¶ ↑
The gem is available as open source under the terms of the MIT License.
Code of Conduct¶ ↑
Everyone interacting in the TTY::Markdown
project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
Copyright¶ ↑
Copyright © 2018 Piotr Murach. See LICENSE for further details.