tty-markdown 0.3.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 78fdb3db2ddf8fcb253d3f2b7fd48ce85f34db5b
-  data.tar.gz: b4176a98f2e6238a0b9d1d3eb32585610750a4b7
+SHA256:
+  metadata.gz: fa4ae8d84f0debb66b9d49522b36c335062c9932072b61eda061fed1408236b6
+  data.tar.gz: 2d79a3688cb49f9a5b1f5c1d11c9f4b8d9654990472219fe412b9039f8dc6373
 SHA512:
-  metadata.gz: c4ddf759c61068a151a2e07ad973fa0268ea671be2006ce1ae0fbd5d4aca6f823d0d682bd005af1473d75dd88b61fa69ac9ab5cc23576773b79b546b5651c232
-  data.tar.gz: 1fa053194d9f4ad41366a4b592888184668f4ea4be628d9cf57e79a296f60b90baaacbac4a8b5df3ed94b29f3baae29268103e7dc3b8328b5a5ecc7cd8547ee4
+  metadata.gz: 3af37ef74648802261e1768acf170134cc0d523a4af52f4a666e4aa52202b45da3c3e749e4abca8976b79b0b3e0fb5ac540ee2289cc37d296facf07a644bf1e1
+  data.tar.gz: b413d03ef5fb97c1f808154d4ddc8386763e0c4229ed7e0d20f515988f9c29b9210c7d707257d044ef3f95d88af46c6de825811eb5d4d9a4a5e9aa1a83f6fc68

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Change log
 
+## [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
+* Add markdown xml comments conversion
+
+## [v0.5.1] - 2019-02-07
+
+### Fixed
+* Fix spaces around inline code quotes collapses inside list items
+
+## [v0.5.0] - 2018-12-13
+
+### Changed
+* Change gemspec to load files directly
+* Change to update rouge dependency
+* Change to relax constraints on tty-screen and tty-color
+
+## [v0.4.0] - 2018-06-20
+
+## Fixed
+* Fix multiline paragraph indentation by Brett(@suwyn)
+
 ## [v0.3.0] - 2018-03-17
 
 ### Added
@@ -20,7 +78,7 @@
 * Add markdown math formula conversion
 * Add markdown typogrpahic symbols conversion by Tanaka Masaki(@T-a-n-a-k-a-M-a-s-a-k-i)
 * Add html entities conversion
-* Add warnings about unsupported conversions for completness
+* Add warnings about unsupported conversions for completeness
 
 ### Changed
 * Change gemspec to require Ruby >= 2.0.0
@@ -32,6 +90,11 @@
 
 * Initial implementation and release
 
+[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
 [v0.2.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.1.0...v0.2.0
 [v0.1.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.1.0

data/README.md

@@ -1,3 +1,7 @@
+<div align="center">
+  <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="tty 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]
@@ -17,7 +21,6 @@
 
 > 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
@@ -41,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
 
@@ -64,12 +73,14 @@ puts parsed
 The `parse_file` allows you to transform a markdown document into a terminal formatted output:
 
 ```ruby
-parsed = TTY::Markdown.parse('example.md')
+parsed = TTY::Markdown.parse_file('example.md')
 puts parsed
 ```
 
 ### 1.1 Header
 
+Parsing the following markdown headers:
+
 ```markdown
 TTY::Markdown
 =============
@@ -81,15 +92,9 @@ TTY::Markdown
 ### Nested list items
 ```
 
-and transforming it:
-
-```ruby
-parsed = TTY::Markdown.parse(markdown_string)
-```
-
-`puts parsed` will output:
+The terminal output looks like this:
 
-![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/headers.png)
+![Headers example](assets/headers.png)
 
 ### 1.2 List
 
@@ -103,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:
 
@@ -135,19 +153,15 @@ Given a markdown quote:
 > *Oh*, you can put **Markdown** into a blockquote.
 ```
 
-and transforming it:
-
-```ruby
-parsed = TTY::Markdown.parse(markdown_string)
-```
+The rendered output looks like this:
 
-`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
@@ -159,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.
 
@@ -183,17 +191,11 @@ For example, given the following table:
 | col 3 is | right-aligned |    $1 |
 ```
 
-and transforming it:
-
-```ruby
-parsed = TTY::Markdown.parse(markdown_string)
-```
-
-`puts parsed` will output:
+Then the terminal output will look like this:
 
-![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:
 
@@ -209,19 +211,38 @@ 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.pasre(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`
 
@@ -237,6 +258,9 @@ THEME = {
   strong: [:yellow, :bold],
   table: :yellow,
   quote: :yellow,
+  image: :bright_black,
+  note: :yellow,
+  comment: :bright_black
 }
 ```
 
@@ -256,6 +280,44 @@ 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"}})
+```
+
+### 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.

data/lib/tty-markdown.rb

@@ -1 +1 @@
-require_relative 'tty/markdown'
+require_relative "tty/markdown"

data/lib/tty/markdown.rb

@@ -1,95 +1,127 @@
 # frozen_string_literal: true
 
-require 'kramdown'
+require "kramdown/document"
+require "tty-color"
+require "tty-screen"
 
-require_relative 'markdown/parser'
-require_relative 'markdown/version'
+require_relative "markdown/converter"
+require_relative "markdown/version"
+require_relative "markdown/kramdown_ext"
 
 module TTY
   module Markdown
     SYMBOLS = {
-      arrow: '»',
-      bullet: '●',
-      bar: '┃',
-      diamond: '◈',
-      pipe: '│',
-      line: '─',
-      hellip: '…',
-      laquo: '«',
-      laquo_space: '« ',
-      raquo: '»',
-      raquo_space: ' »',
-      ndash: '-',
+      arrow: "»",
+      bullet: "●",
+      bar: "┃",
+      diamond: "◈",
+      pipe: "│",
+      line: "─",
+      hellip: "…",
+      laquo: "«",
+      laquo_space: "« ",
+      raquo: "»",
+      raquo_space: " »",
+      ndash: "-",
       mdash: "\u2014",
-      lsquo: '‘',
-      rsquo: '’',
-      ldquo: '“',
-      rdquo: '”',
-      top_left: '┌',
-      top_right: '┐',
-      top_center: '┬',
-      mid_left: '├',
-      mid_right: '┤',
-      mid_center: '┼',
-      bottom_right: '┘',
-      bottom_left: '└',
-      bottom_center: '┴',
+      lsquo: "‘",
+      rsquo: "’",
+      ldquo: "“",
+      rdquo: "”",
+      top_left: "┌",
+      top_right: "┐",
+      top_center: "┬",
+      mid_left: "├",
+      mid_right: "┤",
+      mid_center: "┼",
+      bottom_right: "┘",
+      bottom_left: "└",
+      bottom_center: "┴",
+      paren_left: "(",
+      paren_right: ")",
+      bracket_left: "[",
+      bracket_right: "]",
+      hash: "#",
+      delete: "\u0336"
     }.freeze
 
-    WIN_SYMBOLS = {
-      arrow: '->',
-      bullet: '*',
-      diamond: '*',
-      bar: '│',
-      pipe: '|',
-      line: '─',
-      hellip: '...',
-      laquo: '<<',
-      laquo_space: '<< ',
-      raquo: '>>',
-      raquo_space: ' >>',
-      ndash: '-',
+    ASCII_SYMBOLS = {
+      arrow: "->",
+      bullet: "*",
+      diamond: "*",
+      bar: "│",
+      pipe: "|",
+      line: "-",
+      hellip: "...",
+      laquo: "<<",
+      laquo_space: "<< ",
+      raquo: ">>",
+      raquo_space: " >>",
+      ndash: "-",
       mdash: "--",
-      lsquo: ''',
-      rsquo: ''',
-      ldquo: '"',
-      rdquo: '"',
-      top_left: '+',
-      top_right: '+',
-      top_center: '+',
-      mid_left: '+',
-      mid_right: '+',
-      mid_center: '+',
-      bottom_right: '+',
-      bottom_left: '+',
-      bottom_center: '+'
+      lsquo: "\"",
+      rsquo: "\"",
+      ldquo: "\"",
+      rdquo: "\"",
+      top_left: "+",
+      top_right: "+",
+      top_center: "+",
+      mid_left: "+",
+      mid_right: "+",
+      mid_center: "+",
+      bottom_right: "+",
+      bottom_left: "+",
+      bottom_center: "+",
+      paren_left: "(",
+      paren_right: ")",
+      bracket_left: "[",
+      bracket_right: "]",
+      hash: "#",
+      delete: "\u0336"
     }.freeze
 
     THEME = {
       em: :yellow,
-      header: [:cyan, :bold],
+      header: %i[cyan bold],
       hr: :yellow,
-      link: [:yellow, :underline],
+      link: %i[yellow underline],
       list: :yellow,
-      strong: [:yellow, :bold],
+      strong: %i[yellow bold],
       table: :yellow,
       quote: :yellow,
+      image: :bright_black,
+      note: :yellow,
+      comment: :bright_black
     }.freeze
 
     # Parse a markdown string
     #
-    # @param [Hash] options
-    # @option options [String] :colors
-    #   a number of colors supported
-    # @option options [String] :width
-    #
     # @param [String] source
     #   the source with markdown
+    # @param [Integer] :mode
+    #   a number of colors supported
+    # @param [Integer] :indent
+    #   the indent of the converted output
+    # @param [Hash<Symbol, String>] :symbols
+    #   the symbols to use when generating output
+    # @param [Hash<Symbol, Symbol>] :theme
+    #   the color names for markdown elements
+    # @param [Integer] :width
+    #   the width at which to wrap content
+    # @param [Boolean] :color
+    #   when to enable coloring out of always, never or auto
+    # @param [Hash] :doc_opts
+    #   the markdown document parser options
     #
     # @api public
-    def parse(source, **options)
-      doc = Kramdown::Document.new(source, options)
-      Parser.convert(doc.root, doc.options).join
+    def parse(source, width: TTY::Screen.width, theme: THEME, indent: 2,
+                      mode: TTY::Color.mode, symbols: {}, color: :auto,
+                      **doc_opts)
+      convert_options = { width: width, indent: indent, theme: theme,
+                          mode: mode, symbols: build_symbols(symbols),
+                          input: "KramdownExt", enabled: color_enabled(color) }
+      doc = Kramdown::Document.new(source, convert_options.merge(doc_opts))
+      Converter.convert(doc.root, doc.options).join
     end
     module_function :parse
 
@@ -97,18 +129,41 @@ module TTY
     #
     # @api public
     def parse_file(path, **options)
-      parse(::File.read(path), options)
+      parse(::File.read(path), **options)
     end
     module_function :parse_file
 
-    def symbols
-      @symbols ||= windows? ? WIN_SYMBOLS : SYMBOLS
+    # Convert color setting to Pastel setting
+    #
+    # @api private
+    def color_enabled(color)
+      case color.to_s
+      when "always" then true
+      when "never"  then false
+      else nil
+      end
     end
-    module_function :symbols
+    module_function :color_enabled
+    private_class_method :color_enabled
 
-    def windows?
-      ::File::ALT_SEPARATOR == "\\"
+    # Extract and build symbols
+    #
+    # @api private
+    def build_symbols(options)
+      if options == :ascii
+        ASCII_SYMBOLS
+      elsif options.is_a?(Hash)
+        base_symbols = options[:base] == :ascii ? ASCII_SYMBOLS : SYMBOLS
+        if options[:override].is_a?(Hash)
+          base_symbols.merge(options[:override])
+        else
+          base_symbols
+        end
+      else
+        SYMBOLS
+      end
     end
-    module_function :windows?
+    module_function :build_symbols
+    private_class_method :build_symbols
   end # Markdown
 end # TTY