Awesome
<div align="center"> <a href="https://ttytoolkit.org"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="TTY Toolkit logo" /></a> </div>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:
```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.parse(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
Use the :theme
option to change specific markdown element styles.
For example, to override styles for the link
and list
elements do:
TTY::Markdown.parse(markdown_string, theme: {link: :magenta, list: %i[magenta bold]})
Here's a complete list of element names with corresponding styles:
Name | Style |
---|---|
:comment | :bright_black |
:em | :yellow |
:header | %i[cyan bold] |
:hr | :yellow |
:image | :bright_black |
:link | %i[yellow underline] |
:list | :yellow |
:note | :yellow |
:quote | :yellow |
:strong | %i[yellow bold] |
:table | :yellow |
Read pastel documentation for all supported styles.
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"}})
Here's a complete list of symbol names with corresponding ASCII and Unicode characters:
Name | ASCII | Unicode |
---|---|---|
:arrow | -> | » |
:bar | | | ┃ |
:bottom_center | + | ┴ |
:bottom_left | + | └ |
:bottom_right | + | ┘ |
:bracket_left | [ | [ |
:bracket_right | ] | ] |
:bullet | * | ● |
:diamond | * | ◈ |
:hash | # | # |
:hellip | ... | … |
:laquo | << | « |
:laquo_space | << | « |
:ldquo | " | “ |
:lsquo | " | ‘ |
:line | - | ─ |
:mdash | - | — |
:mid_center | + | ┼ |
:mid_left | + | ├ |
:mid_right | + | ┤ |
:ndash | - | - |
:paren_left | ( | ( |
:paren_right | ) | ) |
:pipe | | | │ |
:raquo | >> | » |
:raquo_space | >> | » |
:rdquo | " | ” |
:rsquo | " | ’ |
:top_center | + | ┬ |
:top_left | + | ┌ |
:top_right | + | ┐ |
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 https://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 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 (c) 2018 Piotr Murach. See LICENSE for further details.