tty-markdown 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea7da61bd62bfbf0bafb500dc1e5fb041e0c31f6707185c16de535b6f8ded6b3
-  data.tar.gz: '09c0b125b0eb7f92282d2c190b0a436c999978e1cb8f5e8b0f86bf38ca262c26'
+  metadata.gz: fa4ae8d84f0debb66b9d49522b36c335062c9932072b61eda061fed1408236b6
+  data.tar.gz: 2d79a3688cb49f9a5b1f5c1d11c9f4b8d9654990472219fe412b9039f8dc6373
 SHA512:
-  metadata.gz: ff8630e97b4ac9107baf7ef9b7a3fdbff7efa27a54858d9eaca2fa5a21b5181119ab2d9d9c50d529c7438a746914ca8286803c47afa19d9e8dc7535ccd46f1bc
-  data.tar.gz: 9efc7db6f92eca9d144a30a1457affac40a607658c3613d2bcef7c224c516d718fef3a1b8064cc534ddb67ec08945cd32c5feb01e3fc26a49e0940a7b8650f47
+  metadata.gz: 3af37ef74648802261e1768acf170134cc0d523a4af52f4a666e4aa52202b45da3c3e749e4abca8976b79b0b3e0fb5ac540ee2289cc37d296facf07a644bf1e1
+  data.tar.gz: b413d03ef5fb97c1f808154d4ddc8386763e0c4229ed7e0d20f515988f9c29b9210c7d707257d044ef3f95d88af46c6de825811eb5d4d9a4a5e9aa1a83f6fc68

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # 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
@@ -15,7 +51,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 +90,9 @@
 
 * Initial implementation and release
 
-[v0.6.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.5.0...v0.6.0
+[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/README.md

@@ -1,5 +1,5 @@
 <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://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]
@@ -21,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
@@ -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:
-
-```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
 
@@ -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)
-```
+The terminal output will look like this:
 
-`puts parsed` will produce:
+![Code highlighting example](assets/codeblock.png)
 
-![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/syntax_highlight.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:
-
-```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:
 
@@ -213,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`
 
@@ -241,6 +258,9 @@ THEME = {
   strong: [:yellow, :bold],
   table: :yellow,
   quote: :yellow,
+  image: :bright_black,
+  note: :yellow,
+  comment: :bright_black
 }
 ```
 
@@ -260,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