tty-markdown 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea7da61bd62bfbf0bafb500dc1e5fb041e0c31f6707185c16de535b6f8ded6b3
-  data.tar.gz: '09c0b125b0eb7f92282d2c190b0a436c999978e1cb8f5e8b0f86bf38ca262c26'
+  metadata.gz: 9d66f69be1b2127af4896ee71342a8be1ea8cf9dabcdceed64c696baf23121a8
+  data.tar.gz: 7e612092f8fa261a8ae1bff784d4a5f607882c417576978c4f18d8ef87bca9c8
 SHA512:
-  metadata.gz: ff8630e97b4ac9107baf7ef9b7a3fdbff7efa27a54858d9eaca2fa5a21b5181119ab2d9d9c50d529c7438a746914ca8286803c47afa19d9e8dc7535ccd46f1bc
-  data.tar.gz: 9efc7db6f92eca9d144a30a1457affac40a607658c3613d2bcef7c224c516d718fef3a1b8064cc534ddb67ec08945cd32c5feb01e3fc26a49e0940a7b8650f47
+  metadata.gz: 219503274cc89c967412401023b4fa194dc018538115d30d45cbe0ed3fb103dbe9f14dfefd29aeef3de03a9d87bcce5def305c9c9f69aeb4a59b171dd96313b5
+  data.tar.gz: 5587f2552f75db9e0a053cb7afe2975f5a984329f53d94f3c50868c8253daf3e8f5383c128d59307c782e7395934a58128d5c09d25ca739e02800f51e2694053

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Change log
 
+## [v0.7.1] - 2022-12-21
+
+### Changed
+* Change the symbols option to accept string value
+
+### Fixed
+* Fix the theme option to allow overriding specific markdown element styles
+
+## [v0.7.0] - 2020-09-03
+
+### Added
+* Add converter for br element by @krage
+* Add configuration of symbols by @krage
+* Add definition list support
+* Add table footer formatting
+* Add formatting of image source location
+* Add footnotes support
+* Add XML comments support
+* Add HTML div/i/em/b/strong/img/a element support
+* Add color configuration setting
+
+### Changed
+* Change #new to accept configuration options as keywords
+* Display links with both label and optional title by @krage
+* Display link without the label when label content is same as link target @krage
+* Change hr formatting to be always full width
+* Differentiate between span and block math elements
+* Display abbreviation with its definition
+* Improve performance by calculating table column widths and row heights only once
+* Change to remove mailto: from email links for brevity @krage
+* Change to update kramdown to support versions >= 1.16 and < 3.0
+* Change to update pastel, tty-color & tty-screen dependencies
+* Change HTML del element formatting to strikethrough
+* Rename colors setting to mode
+
+### Fixed
+* Fix break line handling by @krage
+* Fix links handling by @krage
+* Fix table formatting of empty cells
+* Fix content wrapping to account for the current indentation
+* Fix header wrapping
+* Fix blockquote formatting of content with emphasised style or apostrophe
+* Fix support for HTML del element
+
 ## [v0.6.0] - 2019-03-30
 
 ### Added
@@ -15,7 +59,7 @@
 ### Changed
 * Change gemspec to load files directly
 * Change to update rouge dependency
-* Change to relax constraings on tty-screen and tty-color
+* Change to relax constraints on tty-screen and tty-color
 
 ## [v0.4.0] - 2018-06-20
 
@@ -54,7 +98,10 @@
 
 * Initial implementation and release
 
-[v0.6.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.5.0...v0.6.0
+[v0.7.1]: https://github.com/piotrmurach/tty-markdown/compare/v0.7.0...v0.7.1
+[v0.7.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.6.0...v0.7.0
+[v0.6.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.5.1...v0.6.0
+[v0.5.1]: https://github.com/piotrmurach/tty-markdown/compare/v0.5.0...v0.5.1
 [v0.5.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.4.0...v0.5.0
 [v0.4.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.3.0...v0.4.0
 [v0.3.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.2.0...v0.3.0

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2018 Piotr Murach
+Copyright (c) 2018 Piotr Murach (piotrmurach.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,27 +1,26 @@
 <div align="center">
-  <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://cdn.rawgit.com/piotrmurach/tty/master/images/tty.png" alt="tty logo" /></a>
+  <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 [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
 
 [![Gem Version](https://badge.fury.io/rb/tty-markdown.svg)][gem]
-[![Build Status](https://secure.travis-ci.org/piotrmurach/tty-markdown.svg?branch=master)][travis]
+[![Actions CI](https://github.com/piotrmurach/tty-markdown/workflows/CI/badge.svg?branch=master)][gh_actions_ci]
 [![Build status](https://ci.appveyor.com/api/projects/status/k4vub4koct329ggd?svg=true)][appveyor]
 [![Maintainability](https://api.codeclimate.com/v1/badges/1656060107c73ac42c2b/maintainability)][codeclimate]
 [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-markdown/badge.svg)][coverage]
-[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-markdown.svg?branch=master)][inchpages]
+[![Inline docs](https://inch-ci.org/github/piotrmurach/tty-markdown.svg?branch=master)][inchpages]
 
 [gitter]: https://gitter.im/piotrmurach/tty
-[gem]: http://badge.fury.io/rb/tty-markdown
-[travis]: http://travis-ci.org/piotrmurach/tty-markdown
+[gem]: https://badge.fury.io/rb/tty-markdown
+[gh_actions_ci]: https://github.com/piotrmurach/tty-markdown/actions?query=workflow%3ACI
 [appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-markdown
 [codeclimate]: https://codeclimate.com/github/piotrmurach/tty-markdown/maintainability
 [coverage]: https://coveralls.io/github/piotrmurach/tty-markdown
-[inchpages]: http://inch-ci.org/github/piotrmurach/tty-markdown
+[inchpages]: https://inch-ci.org/github/piotrmurach/tty-markdown
 
 > Convert a markdown document or text into a terminal friendly output.
 
-
 **TTY::Markdown** provides independent markdown processing component for [TTY](https://github.com/piotrmurach/tty) toolkit.
 
 ## Installation
@@ -45,15 +44,21 @@ Or install it yourself as:
 * [1. Usage](#1-usage)
   * [1.1 Header](#11-header)
   * [1.2 List](#12-list)
-  * [1.3 Link](#13-link)
-  * [1.4 Blockquote](#14-blockquote)
-  * [1.5 Code and Syntax Highlighting](#15-code-and-syntax-highlighting)
-  * [1.6 Table](#16-table)
-  * [1.7 Horizontal Rule](#17-horizontal-rule)
+  * [1.3 Definition List](#13-definition-list)
+  * [1.4 Link](#14-link)
+  * [1.5 Blockquote](#15-blockquote)
+  * [1.6 Code and Syntax Highlighting](#16-code-and-syntax-highlighting)
+  * [1.7 Table](#17-table)
+  * [1.8 Horizontal Rule](#18-horizontal-rule)
+  * [1.9 Footnotes](#19-footnotes)
 * [2. Options](#2-options)
-  * [2.1 :colors](#21-colors)
+  * [2.1 :mode](#21-mode)
   * [2.2 :theme](#22-theme)
   * [2.3 :width](#23-width)
+  * [2.4 :symbols](#24-symbols)
+  * [2.5 :indent](#25-indent)
+  * [2.6 :color](#26-color)
+* [3. Command line tool](#3-command-line-tool)
 
 ## 1. Usage
 
@@ -74,6 +79,8 @@ puts parsed
 
 ### 1.1 Header
 
+Parsing the following markdown headers:
+
 ```markdown
 TTY::Markdown
 =============
@@ -85,15 +92,9 @@ TTY::Markdown
 ### Nested list items
 ```
 
-and transforming it:
+The terminal output looks like this:
 
-```ruby
-parsed = TTY::Markdown.parse(markdown_string)
-```
-
-`puts parsed` will output:
-
-![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/headers.png)
+![Headers example](assets/headers.png)
 
 ### 1.2 List
 
@@ -107,29 +108,42 @@ Both numbered and unordered lists are supported. Given a markdown:
 - Item 5
 ```
 
-and transforming it:
+The parsed output looks like this:
 
-```ruby
-parsed = TTY::Markdown.parse(markdown_string)
+![Unordered list example](assets/list.png)
+
+### 1.3 Definition List
+
+Given a definition list:
+
+```markdown
+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
 ```
 
-`puts parsed` will produce:
+The parsed output looks like this:
 
-![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/list.png)
+![Definition list example](assets/definition-list.png)
 
-### 1.3 Link
+### 1.4 Link
 
-A mardown link:
+A markdown link:
 
 ```markdown
-[I'm an inline-style link](https://www.google.com)
+[An inline-style link](https://ttytoolkit.org)
+
+[An inline-style link with title](https://ttytoolkit.org "TTY Toolkit Homepage")
 ```
 
-will be rendered with actual link content next to it:
+The link text will be rendered with the link next to it:
 
-![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/link.png)
+![Link example](assets/link.png)
 
-### 1.4 Blockquote
+### 1.5 Blockquote
 
 Given a markdown quote:
 
@@ -139,19 +153,15 @@ Given a markdown quote:
 > *Oh*, you can put **Markdown** into a blockquote.
 ```
 
-and transforming it:
+The rendered output looks like this:
 
-```ruby
-parsed = TTY::Markdown.parse(markdown_string)
-```
-
-`puts parsed` will output:
+![Blockquote example](assets/quote.png)
 
-![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/quote.png)
+### 1.6 Code and Syntax Highlighting
 
-### 1.5 Code and Syntax Highlighting
+The parser can highlight syntax of many programming languages.
 
-The parser can highlight syntax of many programming languages. Given the markdown codeblock with language specification:
+Given a markdown codeblock with a language specification:
 
 ````markdown
 ```ruby
@@ -163,17 +173,11 @@ end
 ```
 ````
 
-and converting this snippet:
-
-```ruby
-parsed = TTY::Markdown.parse(code_snippet)
-```
-
-`puts parsed` will produce:
+The terminal output will look like this:
 
-![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/syntax_highlight.png)
+![Code highlighting example](assets/codeblock.png)
 
-### 1.6 Table
+### 1.7 Table
 
 You can transform tables which understand the markdown alignment.
 
@@ -187,17 +191,11 @@ For example, given the following table:
 | col 3 is | right-aligned |    $1 |
 ```
 
-and transforming it:
+Then the terminal output will look like this:
 
-```ruby
-parsed = TTY::Markdown.parse(markdown_string)
-```
-
-`puts parsed` will output:
-
-![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/table.png)
+![Table example](assets/table.png)
 
-### 1.7 Horizontal Rule
+### 1.8 Horizontal Rule
 
 You can specify a horizontal rule in markdown:
 
@@ -213,42 +211,66 @@ parsed = TTY::Markdown.parse(markdown_string)
 
 `puts parsed` will output:
 
-![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/hr.png)
+![Horizontal rule example](assets/hr.png)
+
+### 1.9 Footnotes
+
+You can create footnote references:
+
+```markdown
+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:
+
+![Footnotes example](assets/footnotes.png)
 
 ## 2. Options
 
-### 2.1 `:colors`
+### 2.1 `:mode`
 
-By default the `256` colors scheme is used to render code block elements. You can change that by specifying desired number of colors:
+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:
 
 ```ruby
-TTY::Markdown.pasre(markdown_string, colors: 16)
+TTY::Markdown.parse(markdown_string, mode: 16)
 ```
 
-This feauture may be handy when working in terminals with limited color support. By default, **TTY::Markdown** detects your terminal color mode and adjusts output automatically.
+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:
+Use the `:theme` option to change specific markdown element styles.
+
+For example, to override styles for the `link` and `list` elements do:
 
 ```ruby
-THEME = {
-  em: :yellow,
-  header: [:cyan, :bold],
-  hr: :yellow,
-  link: [:yellow, :underline],
-  list: :yellow,
-  strong: [:yellow, :bold],
-  table: :yellow,
-  quote: :yellow,
-}
+TTY::Markdown.parse(markdown_string, theme: {link: :magenta, list: %i[magenta bold]})
 ```
 
-In order to provide new styles use `:theme` key:
+Here's a complete list of element names with corresponding styles:
 
-```ruby
-TTY::Markdown.parse(markdown_string, theme: { ... })
-```
+| 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](https://github.com/piotrmurach/pastel#3-supported-colors) for all supported styles.
 
 ### 2.3 `:width`
 
@@ -260,6 +282,80 @@ 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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+TTY::Markdown.parse(markdown_string, color: :always)
+```
+
+### 3. Command line tool
+
+You can install [tty-markdown-cli](https://github.com/piotrmurach/tty-markdown-cli) to use `tty-markdown` executable in terminal:
+
+```bash
+$ 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.
@@ -268,7 +364,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## 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 [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+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](https://github.com/piotrmurach/tty-markdown/blob/master/CODE_OF_CONDUCT.md).
 
 ## License