tty-markdown 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: ea7da61bd62bfbf0bafb500dc1e5fb041e0c31f6707185c16de535b6f8ded6b3
4
- data.tar.gz: '09c0b125b0eb7f92282d2c190b0a436c999978e1cb8f5e8b0f86bf38ca262c26'
3
+ metadata.gz: fa4ae8d84f0debb66b9d49522b36c335062c9932072b61eda061fed1408236b6
4
+ data.tar.gz: 2d79a3688cb49f9a5b1f5c1d11c9f4b8d9654990472219fe412b9039f8dc6373
5
5
  SHA512:
6
- metadata.gz: ff8630e97b4ac9107baf7ef9b7a3fdbff7efa27a54858d9eaca2fa5a21b5181119ab2d9d9c50d529c7438a746914ca8286803c47afa19d9e8dc7535ccd46f1bc
7
- data.tar.gz: 9efc7db6f92eca9d144a30a1457affac40a607658c3613d2bcef7c224c516d718fef3a1b8064cc534ddb67ec08945cd32c5feb01e3fc26a49e0940a7b8650f47
6
+ metadata.gz: 3af37ef74648802261e1768acf170134cc0d523a4af52f4a666e4aa52202b45da3c3e749e4abca8976b79b0b3e0fb5ac540ee2289cc37d296facf07a644bf1e1
7
+ data.tar.gz: b413d03ef5fb97c1f808154d4ddc8386763e0c4229ed7e0d20f515988f9c29b9210c7d707257d044ef3f95d88af46c6de825811eb5d4d9a4a5e9aa1a83f6fc68
@@ -1,5 +1,41 @@
1
1
  # Change log
2
2
 
3
+ ## [v0.7.0] - 2020-09-03
4
+
5
+ ### Added
6
+ * Add converter for br element by @krage
7
+ * Add configuration of symbols by @krage
8
+ * Add definition list support
9
+ * Add table footer formatting
10
+ * Add formatting of image source location
11
+ * Add footnotes support
12
+ * Add XML comments support
13
+ * Add HTML div/i/em/b/strong/img/a element support
14
+ * Add color configuration setting
15
+
16
+ ### Changed
17
+ * Change #new to accept configuration options as keywords
18
+ * Display links with both label and optional title by @krage
19
+ * Display link without the label when label content is same as link target @krage
20
+ * Change hr formatting to be always full width
21
+ * Differentiate between span and block math elements
22
+ * Display abbreviation with its definition
23
+ * Improve performance by calculating table column widths and row heights only once
24
+ * Change to remove mailto: from email links for brevity @krage
25
+ * Change to update kramdown to support versions >= 1.16 and < 3.0
26
+ * Change to update pastel, tty-color & tty-screen dependencies
27
+ * Change HTML del element formatting to strikethrough
28
+ * Rename colors setting to mode
29
+
30
+ ### Fixed
31
+ * Fix break line handling by @krage
32
+ * Fix links handling by @krage
33
+ * Fix table formatting of empty cells
34
+ * Fix content wrapping to account for the current indentation
35
+ * Fix header wrapping
36
+ * Fix blockquote formatting of content with emphasised style or apostrophe
37
+ * Fix support for HTML del element
38
+
3
39
  ## [v0.6.0] - 2019-03-30
4
40
 
5
41
  ### Added
@@ -15,7 +51,7 @@
15
51
  ### Changed
16
52
  * Change gemspec to load files directly
17
53
  * Change to update rouge dependency
18
- * Change to relax constraings on tty-screen and tty-color
54
+ * Change to relax constraints on tty-screen and tty-color
19
55
 
20
56
  ## [v0.4.0] - 2018-06-20
21
57
 
@@ -54,7 +90,9 @@
54
90
 
55
91
  * Initial implementation and release
56
92
 
57
- [v0.6.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.5.0...v0.6.0
93
+ [v0.7.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.6.0...v0.7.0
94
+ [v0.6.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.5.1...v0.6.0
95
+ [v0.5.1]: https://github.com/piotrmurach/tty-markdown/compare/v0.5.0...v0.5.1
58
96
  [v0.5.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.4.0...v0.5.0
59
97
  [v0.4.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.3.0...v0.4.0
60
98
  [v0.3.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.2.0...v0.3.0
data/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <div align="center">
2
- <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>
2
+ <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>
3
3
  </div>
4
4
 
5
5
  # TTY::Markdown [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
@@ -21,7 +21,6 @@
21
21
 
22
22
  > Convert a markdown document or text into a terminal friendly output.
23
23
 
24
-
25
24
  **TTY::Markdown** provides independent markdown processing component for [TTY](https://github.com/piotrmurach/tty) toolkit.
26
25
 
27
26
  ## Installation
@@ -45,15 +44,21 @@ Or install it yourself as:
45
44
  * [1. Usage](#1-usage)
46
45
  * [1.1 Header](#11-header)
47
46
  * [1.2 List](#12-list)
48
- * [1.3 Link](#13-link)
49
- * [1.4 Blockquote](#14-blockquote)
50
- * [1.5 Code and Syntax Highlighting](#15-code-and-syntax-highlighting)
51
- * [1.6 Table](#16-table)
52
- * [1.7 Horizontal Rule](#17-horizontal-rule)
47
+ * [1.3 Definition List](#13-definition-list)
48
+ * [1.4 Link](#14-link)
49
+ * [1.5 Blockquote](#15-blockquote)
50
+ * [1.6 Code and Syntax Highlighting](#16-code-and-syntax-highlighting)
51
+ * [1.7 Table](#17-table)
52
+ * [1.8 Horizontal Rule](#18-horizontal-rule)
53
+ * [1.9 Footnotes](#19-footnotes)
53
54
  * [2. Options](#2-options)
54
- * [2.1 :colors](#21-colors)
55
+ * [2.1 :mode](#21-mode)
55
56
  * [2.2 :theme](#22-theme)
56
57
  * [2.3 :width](#23-width)
58
+ * [2.4 :symbols](#24-symbols)
59
+ * [2.5 :indent](#25-indent)
60
+ * [2.6 :color](#26-color)
61
+ * [3. Command line tool](#3-command-line-tool)
57
62
 
58
63
  ## 1. Usage
59
64
 
@@ -74,6 +79,8 @@ puts parsed
74
79
 
75
80
  ### 1.1 Header
76
81
 
82
+ Parsing the following markdown headers:
83
+
77
84
  ```markdown
78
85
  TTY::Markdown
79
86
  =============
@@ -85,15 +92,9 @@ TTY::Markdown
85
92
  ### Nested list items
86
93
  ```
87
94
 
88
- and transforming it:
89
-
90
- ```ruby
91
- parsed = TTY::Markdown.parse(markdown_string)
92
- ```
93
-
94
- `puts parsed` will output:
95
+ The terminal output looks like this:
95
96
 
96
- ![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/headers.png)
97
+ ![Headers example](assets/headers.png)
97
98
 
98
99
  ### 1.2 List
99
100
 
@@ -107,29 +108,42 @@ Both numbered and unordered lists are supported. Given a markdown:
107
108
  - Item 5
108
109
  ```
109
110
 
110
- and transforming it:
111
+ The parsed output looks like this:
111
112
 
112
- ```ruby
113
- parsed = TTY::Markdown.parse(markdown_string)
113
+ ![Unordered list example](assets/list.png)
114
+
115
+ ### 1.3 Definition List
116
+
117
+ Given a definition list:
118
+
119
+ ```markdown
120
+ Item 1
121
+ : This is the description for Item 1
122
+
123
+ Item 2
124
+ : This is the description for Item 2
125
+ : This is another description for Item 2
114
126
  ```
115
127
 
116
- `puts parsed` will produce:
128
+ The parsed output looks like this:
117
129
 
118
- ![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/list.png)
130
+ ![Definition list example](assets/definition-list.png)
119
131
 
120
- ### 1.3 Link
132
+ ### 1.4 Link
121
133
 
122
- A mardown link:
134
+ A markdown link:
123
135
 
124
136
  ```markdown
125
- [I'm an inline-style link](https://www.google.com)
137
+ [An inline-style link](https://ttytoolkit.org)
138
+
139
+ [An inline-style link with title](https://ttytoolkit.org "TTY Toolkit Homepage")
126
140
  ```
127
141
 
128
- will be rendered with actual link content next to it:
142
+ The link text will be rendered with the link next to it:
129
143
 
130
- ![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/link.png)
144
+ ![Link example](assets/link.png)
131
145
 
132
- ### 1.4 Blockquote
146
+ ### 1.5 Blockquote
133
147
 
134
148
  Given a markdown quote:
135
149
 
@@ -139,19 +153,15 @@ Given a markdown quote:
139
153
  > *Oh*, you can put **Markdown** into a blockquote.
140
154
  ```
141
155
 
142
- and transforming it:
156
+ The rendered output looks like this:
143
157
 
144
- ```ruby
145
- parsed = TTY::Markdown.parse(markdown_string)
146
- ```
147
-
148
- `puts parsed` will output:
158
+ ![Blockquote example](assets/quote.png)
149
159
 
150
- ![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/quote.png)
160
+ ### 1.6 Code and Syntax Highlighting
151
161
 
152
- ### 1.5 Code and Syntax Highlighting
162
+ The parser can highlight syntax of many programming languages.
153
163
 
154
- The parser can highlight syntax of many programming languages. Given the markdown codeblock with language specification:
164
+ Given a markdown codeblock with a language specification:
155
165
 
156
166
  ````markdown
157
167
  ```ruby
@@ -163,17 +173,11 @@ end
163
173
  ```
164
174
  ````
165
175
 
166
- and converting this snippet:
167
-
168
- ```ruby
169
- parsed = TTY::Markdown.parse(code_snippet)
170
- ```
176
+ The terminal output will look like this:
171
177
 
172
- `puts parsed` will produce:
178
+ ![Code highlighting example](assets/codeblock.png)
173
179
 
174
- ![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/syntax_highlight.png)
175
-
176
- ### 1.6 Table
180
+ ### 1.7 Table
177
181
 
178
182
  You can transform tables which understand the markdown alignment.
179
183
 
@@ -187,17 +191,11 @@ For example, given the following table:
187
191
  | col 3 is | right-aligned | $1 |
188
192
  ```
189
193
 
190
- and transforming it:
191
-
192
- ```ruby
193
- parsed = TTY::Markdown.parse(markdown_string)
194
- ```
195
-
196
- `puts parsed` will output:
194
+ Then the terminal output will look like this:
197
195
 
198
- ![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/table.png)
196
+ ![Table example](assets/table.png)
199
197
 
200
- ### 1.7 Horizontal Rule
198
+ ### 1.8 Horizontal Rule
201
199
 
202
200
  You can specify a horizontal rule in markdown:
203
201
 
@@ -213,19 +211,38 @@ parsed = TTY::Markdown.parse(markdown_string)
213
211
 
214
212
  `puts parsed` will output:
215
213
 
216
- ![Code highlight](https://cdn.rawgit.com/piotrmurach/tty-markdown/master/assets/hr.png)
214
+ ![Horizontal rule example](assets/hr.png)
215
+
216
+ ### 1.9 Footnotes
217
+
218
+ You can create footnote references:
219
+
220
+ ```markdown
221
+ It is not down on any map[^foo]; true places[^bar] never are.
222
+
223
+ [^foo]: A diagrammatic representation of an area of land or sea.
224
+ [^bar]: A particular position, point, or area in space; a location.
225
+ ```
226
+
227
+ All footnotes will be displayed with a sequential number and rendered in the terminal like this:
228
+
229
+ ![Footnotes example](assets/footnotes.png)
217
230
 
218
231
  ## 2. Options
219
232
 
220
- ### 2.1 `:colors`
233
+ ### 2.1 `:mode`
221
234
 
222
- By default the `256` colors scheme is used to render code block elements. You can change that by specifying desired number of colors:
235
+ By default the `256` color scheme is used to render code block elements.
236
+
237
+ You can change this by specifying maximum number of colors to be `16` ANSI colors:
223
238
 
224
239
  ```ruby
225
- TTY::Markdown.pasre(markdown_string, colors: 16)
240
+ TTY::Markdown.pasre(markdown_string, mode: 16)
226
241
  ```
227
242
 
228
- 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.
243
+ This feature may be handy when working in terminals with limited color support.
244
+
245
+ By default, **TTY::Markdown** detects your terminal color mode and adjusts output automatically.
229
246
 
230
247
  ### 2.2 `:theme`
231
248
 
@@ -241,6 +258,9 @@ THEME = {
241
258
  strong: [:yellow, :bold],
242
259
  table: :yellow,
243
260
  quote: :yellow,
261
+ image: :bright_black,
262
+ note: :yellow,
263
+ comment: :bright_black
244
264
  }
245
265
  ```
246
266
 
@@ -260,6 +280,44 @@ TTY::Markdown.parse(markdown_string, width: 80)
260
280
 
261
281
  By default the terminal screen width is used.
262
282
 
283
+ ### 2.4 `:symbols`
284
+
285
+ By default formatting will include various Unicode symbols. You can switch to an included ASCII set and/or override individually with the `:symbols` key:
286
+
287
+ ```ruby
288
+ TTY::Markdown.parse(markdown_string, symbols: :ascii)
289
+ TTY::Markdown.parse(markdown_string, symbols: {base: :ascii})
290
+ TTY::Markdown.parse(markdown_string, symbols: {override: {bullet: "x"}})
291
+ ```
292
+
293
+ ### 2.5 `:indent`
294
+
295
+ 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:
296
+
297
+ ```ruby
298
+ TTY::Markdown.parse(markdown_string, indent: 0)
299
+ ```
300
+
301
+ ### 2.6 `:color`
302
+
303
+ You can control when to apply coloring to various document elements.
304
+
305
+ Valid values are `:never`, `:always` or `:auto`. By default `:auto` is used which auto detects if coloring can be applied.
306
+
307
+ For example, to always color content regardless of terminal support do:
308
+
309
+ ```ruby
310
+ TTY::Markdown.parse(markdown_string, color: :always)
311
+ ```
312
+
313
+ ### 3. Command line tool
314
+
315
+ You can install [tty-markdown-cli](https://github.com/piotrmurach/tty-markdown-cli) to use `tty-markdown` executable in terminal:
316
+
317
+ ```bash
318
+ $ tty-markdown README.md
319
+ ```
320
+
263
321
  ## Development
264
322
 
265
323
  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.
@@ -1 +1 @@
1
- require_relative 'tty/markdown'
1
+ require_relative "tty/markdown"
@@ -1,95 +1,127 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'kramdown'
3
+ require "kramdown/document"
4
+ require "tty-color"
5
+ require "tty-screen"
4
6
 
5
- require_relative 'markdown/parser'
6
- require_relative 'markdown/version'
7
+ require_relative "markdown/converter"
8
+ require_relative "markdown/version"
9
+ require_relative "markdown/kramdown_ext"
7
10
 
8
11
  module TTY
9
12
  module Markdown
10
13
  SYMBOLS = {
11
- arrow: '»',
12
- bullet: '',
13
- bar: '',
14
- diamond: '',
15
- pipe: '',
16
- line: '',
17
- hellip: '',
18
- laquo: '«',
19
- laquo_space: '« ',
20
- raquo: '»',
21
- raquo_space: ' »',
22
- ndash: '-',
14
+ arrow: "»",
15
+ bullet: "",
16
+ bar: "",
17
+ diamond: "",
18
+ pipe: "",
19
+ line: "",
20
+ hellip: "",
21
+ laquo: "«",
22
+ laquo_space: "« ",
23
+ raquo: "»",
24
+ raquo_space: " »",
25
+ ndash: "-",
23
26
  mdash: "\u2014",
24
- lsquo: '',
25
- rsquo: '',
26
- ldquo: '',
27
- rdquo: '',
28
- top_left: '',
29
- top_right: '',
30
- top_center: '',
31
- mid_left: '',
32
- mid_right: '',
33
- mid_center: '',
34
- bottom_right: '',
35
- bottom_left: '',
36
- bottom_center: '',
27
+ lsquo: "",
28
+ rsquo: "",
29
+ ldquo: "",
30
+ rdquo: "",
31
+ top_left: "",
32
+ top_right: "",
33
+ top_center: "",
34
+ mid_left: "",
35
+ mid_right: "",
36
+ mid_center: "",
37
+ bottom_right: "",
38
+ bottom_left: "",
39
+ bottom_center: "",
40
+ paren_left: "(",
41
+ paren_right: ")",
42
+ bracket_left: "[",
43
+ bracket_right: "]",
44
+ hash: "#",
45
+ delete: "\u0336"
37
46
  }.freeze
38
47
 
39
- WIN_SYMBOLS = {
40
- arrow: '->',
41
- bullet: '*',
42
- diamond: '*',
43
- bar: '',
44
- pipe: '|',
45
- line: '─',
46
- hellip: '...',
47
- laquo: '<<',
48
- laquo_space: '<< ',
49
- raquo: '>>',
50
- raquo_space: ' >>',
51
- ndash: '-',
48
+ ASCII_SYMBOLS = {
49
+ arrow: "->",
50
+ bullet: "*",
51
+ diamond: "*",
52
+ bar: "",
53
+ pipe: "|",
54
+ line: "-",
55
+ hellip: "...",
56
+ laquo: "<<",
57
+ laquo_space: "<< ",
58
+ raquo: ">>",
59
+ raquo_space: " >>",
60
+ ndash: "-",
52
61
  mdash: "--",
53
- lsquo: ''',
54
- rsquo: ''',
55
- ldquo: '"',
56
- rdquo: '"',
57
- top_left: '+',
58
- top_right: '+',
59
- top_center: '+',
60
- mid_left: '+',
61
- mid_right: '+',
62
- mid_center: '+',
63
- bottom_right: '+',
64
- bottom_left: '+',
65
- bottom_center: '+'
62
+ lsquo: "\"",
63
+ rsquo: "\"",
64
+ ldquo: "\"",
65
+ rdquo: "\"",
66
+ top_left: "+",
67
+ top_right: "+",
68
+ top_center: "+",
69
+ mid_left: "+",
70
+ mid_right: "+",
71
+ mid_center: "+",
72
+ bottom_right: "+",
73
+ bottom_left: "+",
74
+ bottom_center: "+",
75
+ paren_left: "(",
76
+ paren_right: ")",
77
+ bracket_left: "[",
78
+ bracket_right: "]",
79
+ hash: "#",
80
+ delete: "\u0336"
66
81
  }.freeze
67
82
 
68
83
  THEME = {
69
84
  em: :yellow,
70
- header: [:cyan, :bold],
85
+ header: %i[cyan bold],
71
86
  hr: :yellow,
72
- link: [:yellow, :underline],
87
+ link: %i[yellow underline],
73
88
  list: :yellow,
74
- strong: [:yellow, :bold],
89
+ strong: %i[yellow bold],
75
90
  table: :yellow,
76
91
  quote: :yellow,
92
+ image: :bright_black,
93
+ note: :yellow,
94
+ comment: :bright_black
77
95
  }.freeze
78
96
 
79
97
  # Parse a markdown string
80
98
  #
81
- # @param [Hash] options
82
- # @option options [String] :colors
83
- # a number of colors supported
84
- # @option options [String] :width
85
- #
86
99
  # @param [String] source
87
100
  # the source with markdown
101
+ # @param [Integer] :mode
102
+ # a number of colors supported
103
+ # @param [Integer] :indent
104
+ # the indent of the converted output
105
+ # @param [Hash<Symbol, String>] :symbols
106
+ # the symbols to use when generating output
107
+ # @param [Hash<Symbol, Symbol>] :theme
108
+ # the color names for markdown elements
109
+ # @param [Integer] :width
110
+ # the width at which to wrap content
111
+ # @param [Boolean] :color
112
+ # when to enable coloring out of always, never or auto
113
+ # @param [Hash] :doc_opts
114
+ # the markdown document parser options
88
115
  #
89
116
  # @api public
90
- def parse(source, **options)
91
- doc = Kramdown::Document.new(source, options)
92
- Parser.convert(doc.root, doc.options).join
117
+ def parse(source, width: TTY::Screen.width, theme: THEME, indent: 2,
118
+ mode: TTY::Color.mode, symbols: {}, color: :auto,
119
+ **doc_opts)
120
+ convert_options = { width: width, indent: indent, theme: theme,
121
+ mode: mode, symbols: build_symbols(symbols),
122
+ input: "KramdownExt", enabled: color_enabled(color) }
123
+ doc = Kramdown::Document.new(source, convert_options.merge(doc_opts))
124
+ Converter.convert(doc.root, doc.options).join
93
125
  end
94
126
  module_function :parse
95
127
 
@@ -97,18 +129,41 @@ module TTY
97
129
  #
98
130
  # @api public
99
131
  def parse_file(path, **options)
100
- parse(::File.read(path), options)
132
+ parse(::File.read(path), **options)
101
133
  end
102
134
  module_function :parse_file
103
135
 
104
- def symbols
105
- @symbols ||= windows? ? WIN_SYMBOLS : SYMBOLS
136
+ # Convert color setting to Pastel setting
137
+ #
138
+ # @api private
139
+ def color_enabled(color)
140
+ case color.to_s
141
+ when "always" then true
142
+ when "never" then false
143
+ else nil
144
+ end
106
145
  end
107
- module_function :symbols
146
+ module_function :color_enabled
147
+ private_class_method :color_enabled
108
148
 
109
- def windows?
110
- ::File::ALT_SEPARATOR == "\\"
149
+ # Extract and build symbols
150
+ #
151
+ # @api private
152
+ def build_symbols(options)
153
+ if options == :ascii
154
+ ASCII_SYMBOLS
155
+ elsif options.is_a?(Hash)
156
+ base_symbols = options[:base] == :ascii ? ASCII_SYMBOLS : SYMBOLS
157
+ if options[:override].is_a?(Hash)
158
+ base_symbols.merge(options[:override])
159
+ else
160
+ base_symbols
161
+ end
162
+ else
163
+ SYMBOLS
164
+ end
111
165
  end
112
- module_function :windows?
166
+ module_function :build_symbols
167
+ private_class_method :build_symbols
113
168
  end # Markdown
114
169
  end # TTY