tty-markdown 0.6.0 → 0.7.0

Sign up to get free protection for your applications and to get access to all the features.
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