markdown_helper 0.1.8 → 0.1.9

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
  SHA1:
3
- metadata.gz: f20468d3adaf8f70c7e5ca62a12d3796d11bf615
4
- data.tar.gz: 01d3ae966a7217a012eaa2d32e603b233690ea8c
3
+ metadata.gz: 28b04055b3976d51cdb7324ab249edeb204fe73d
4
+ data.tar.gz: e28fd32accb586372b69bffb44e15d39665a5397
5
5
  SHA512:
6
- metadata.gz: f36d06b2272e6d662288040ba56ee9536c617496516606bf304f9f2d890af3d34dfb8fb200fa8de88f10b4f9341e0162688a33060bc34569280ec937b23a5c63
7
- data.tar.gz: a5e5ddb4973689fbcee65d977c1c85edb3090d4c2cc74d7b3f8353ccd2b63ef4af3d03b15ed0c006ad40b6ab21f13510a9b176dc5897b6c6d3f1901acd481db1
6
+ metadata.gz: 977604ef93870d3ae68665c2ca79c5798551a91beb624f364bc73d73d89cccd98b0f8397800faae5707544a4c457ecab2bc782263ffbaa96f32f4262909904dc
7
+ data.tar.gz: 3a2f4b3bdc24210d883469c4f0694a2d83cba8c9be3e16ab0537918d79a14d85ab77275604ebb1b178875a89be4c63a1125ad4727ce92217fff73fe6e358e803
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- markdown_helper (0.1.8)
4
+ markdown_helper (0.1.9)
5
5
 
6
6
  GEM
7
7
  remote: https://rubygems.org/
data/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  ## File Inclusion
6
6
 
7
- <img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/include.png" width="50">
7
+ <img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/include.png" alt="include_icon" width="50">
8
8
 
9
9
  This markdown helper enables file inclusion in GitHub markdown.
10
10
 
@@ -65,13 +65,13 @@ Usage:
65
65
 
66
66
  #### API
67
67
 
68
- <code>usage.rb</code>
68
+ <code>include_usage.rb</code>
69
69
  ```ruby
70
70
  require 'markdown_helper'
71
71
 
72
72
  markdown_helper = MarkdownHelper.new
73
73
  template_file_path = 'highlight_ruby_template.md'
74
- markdown_file_path = 'highlighted_ruby.rb'
74
+ markdown_file_path = 'highlighted_ruby.md'
75
75
  markdown_helper.include(template_file_path, markdown_file_path)
76
76
  ```
77
77
 
@@ -92,7 +92,7 @@ where:
92
92
  ##### Example Include Pragmas
93
93
 
94
94
  <code>include.md</code>
95
- ```verbatim
95
+ ```code_block
96
96
  @[ruby](my_ruby.rb)
97
97
 
98
98
  @[:code_block](my_language.xyzzy)
@@ -100,4 +100,71 @@ where:
100
100
  @[:verbatim](my_markdown.md)
101
101
  ```
102
102
 
103
+ ## Image Path Resolution
104
+
105
+ <img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/image.png" alt="image_icon" width="50">
106
+
107
+ This markdown helper enables image path resolution in GitHub markdown.
108
+
109
+ (Actually, this README file itself is built using image path resolution.)
110
+
111
+ Use the markdown helper to resolve image relative paths in a markdown (</code>.md</code>) file.
112
+
113
+ This matters because when markdown becomes part of a Ruby gem, its images will have been relocated in the documentation at RubyDoc.info, breaking the relative paths. The resolved (absolute) urls, however, will still be valid.
114
+
115
+ ### Usage
116
+
117
+ #### CLI
118
+
119
+ <code>resolve_image_urls.txt</code>
120
+ ```
121
+ Usage:
122
+
123
+ resolve_image_urls template_file_path markdown_file_page
124
+
125
+ where
126
+
127
+ * template_file_path is the path to an existing file.
128
+ * markdown_file_path is the path to a file to be created.
129
+
130
+ Typically:
131
+
132
+ * Both file types are .md.
133
+ * The template file contains image relative file paths. See README.md.
134
+ ```
135
+
136
+ #### API
137
+
138
+ <code>resolve_image_urls_usage.rb</code>
139
+ ```ruby
140
+ require 'markdown_helper'
141
+
142
+ markdown_helper = MarkdownHelper.new
143
+ template_file_path = 'template.md'
144
+ markdown_file_path = 'markdown.md'
145
+ markdown_helper.resolve_image_urls(template_file_path, markdown_file_path)
146
+ ```
147
+
148
+ #### Image Pragmas
149
+
150
+ Specify each image file via an *image pragma*, which has the form:
151
+
152
+ <code>![*alt_text*]\(</code>*relative_file_path* <code>|</code> *attributes*<code>)</code>
153
+
154
+ where:
155
+
156
+ * *alt_text* is the usual alt text for an HTML image.
157
+ * *relative_file_path* points to the file to be included.
158
+ * *attributes* are whitespace-separated name-value pairs in the form *name*<code>=</code>*value*. These are passed through to the generated <code>img</code> HTML element.
159
+
160
+ ##### Example Image Pragmas
161
+
162
+ <code>resolve_image_urls.md</code>
163
+ ```code_block
164
+ ![my_alt](image/image.png)
165
+
166
+ ![my_alt](image/image.png | width=50)
167
+
168
+ ![my_alt](image/image.png| width=50 height=50)
169
+ ```
103
170
 
data/Rakefile CHANGED
@@ -15,6 +15,7 @@ namespace :build do
15
15
  markdown_helper = MarkdownHelper.new
16
16
  markdown_helper.include('readme_files/highlight_ruby_template.md', 'readme_files/highlighted_ruby.md')
17
17
  markdown_helper.include('readme_files/README.template.md', 'README.md')
18
+ markdown_helper.resolve_image_urls('README.md', 'README.md')
18
19
  end
19
20
 
20
21
  end
@@ -0,0 +1,22 @@
1
+ #!/usr/bin/env ruby
2
+
3
+ require 'markdown_helper'
4
+
5
+ def usage
6
+ dir_path = File.dirname(File.absolute_path(__FILE__))
7
+ file_path = File.join(
8
+ dir_path,
9
+ 'usage',
10
+ 'resolve_image_urls.txt'
11
+ )
12
+ puts File.read(file_path)
13
+ exit
14
+ end
15
+
16
+ template_file_path, markdown_file_path = ARGV
17
+
18
+ usage unless ARGV.size == 2
19
+ usage unless File.readable?(template_file_path)
20
+ usage unless File.writable?(File.dirname(markdown_file_path))
21
+
22
+ MarkdownHelper.new.resolve_image_urls(template_file_path, markdown_file_path)
@@ -0,0 +1,13 @@
1
+ Usage:
2
+
3
+ resolve_image_urls template_file_path markdown_file_page
4
+
5
+ where
6
+
7
+ * template_file_path is the path to an existing file.
8
+ * markdown_file_path is the path to a file to be created.
9
+
10
+ Typically:
11
+
12
+ * Both file types are .md.
13
+ * The template file contains image relative file paths. See README.md.
data/images/image.png ADDED
Binary file
@@ -0,0 +1,96 @@
1
+ # MarkdownHelper
2
+
3
+ [![Gem Version](https://badge.fury.io/rb/markdown_helper.svg)](https://badge.fury.io/rb/markdown_helper)
4
+
5
+ ## File Inclusion
6
+
7
+ <img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/include.png" alt="include_icon" width="50">
8
+
9
+ This markdown helper enables file inclusion in GitHub markdown.
10
+
11
+ (Actually, this README file itself is built using file inclusion.)
12
+
13
+ Use the markdown helper to merge external files into a markdown (</code>.md</code>) file.
14
+
15
+ ### Merged Text Formats
16
+
17
+ #### Highlighted Code Block
18
+
19
+ @[ruby](include.rb)
20
+
21
+ #### Plain Code Block
22
+
23
+ @[:code_block](include.rb)
24
+
25
+ [Note: In the gem documentation, RubyDoc.info chooses to highlight this code block regardless. Go figure.]
26
+
27
+ #### Verbatim
28
+
29
+ Verbatim text is included unadorned. Most often, verbatim text is markdown to be rendered as part of the markdown page.
30
+
31
+ ### Usage
32
+
33
+ #### CLI
34
+
35
+ @[:code_block](../bin/usage/include.txt)
36
+
37
+ #### API
38
+
39
+ @[ruby](include_usage.rb)
40
+
41
+ #### Include Pragmas
42
+
43
+ Specify each file inclusion via an *include pragma*, which has the form:
44
+
45
+ <code>@[</code>*format*<code>]\(</code>*relative_file_path*<code>)</code>
46
+
47
+ where:
48
+
49
+ * *format* (in square brackets) is one of the following:
50
+ * Highlighting mode such as <code>[ruby]</code>, to include a highlighted code block. This can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
51
+ * <code>[:code_block]</code>, to include a plain code block.
52
+ * <code>[:verbatim]</code>, to include text verbatim (to be rendered as markdown).
53
+ * *relative_file_path* points to the file to be included.
54
+
55
+ ##### Example Include Pragmas
56
+
57
+ @[code_block](include.md)
58
+
59
+ ## Image Path Resolution
60
+
61
+ <img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/image.png" alt="image_icon" width="50">
62
+
63
+ This markdown helper enables image path resolution in GitHub markdown.
64
+
65
+ (Actually, this README file itself is built using image path resolution.)
66
+
67
+ Use the markdown helper to resolve image relative paths in a markdown (</code>.md</code>) file.
68
+
69
+ This matters because when markdown becomes part of a Ruby gem, its images will have been relocated in the documentation at RubyDoc.info, breaking the relative paths. The resolved (absolute) urls, however, will still be valid.
70
+
71
+ ### Usage
72
+
73
+ #### CLI
74
+
75
+ @[:code_block](../bin/usage/resolve_image_urls.txt)
76
+
77
+ #### API
78
+
79
+ @[ruby](resolve_image_urls_usage.rb)
80
+
81
+ #### Image Pragmas
82
+
83
+ Specify each image file via an *image pragma*, which has the form:
84
+
85
+ <code>![*alt_text*]\(</code>*relative_file_path* <code>|</code> *attributes*<code>)</code>
86
+
87
+ where:
88
+
89
+ * *alt_text* is the usual alt text for an HTML image.
90
+ * *relative_file_path* points to the file to be included.
91
+ * *attributes* are whitespace-separated name-value pairs in the form *name*<code>=</code>*value*. These are passed through to the generated <code>img</code> HTML element.
92
+
93
+ ##### Example Image Pragmas
94
+
95
+ @[code_block](resolve_image_urls.md)
96
+
@@ -1,3 +1,3 @@
1
1
  class MarkdownHelper
2
- VERSION = '0.1.8'
2
+ VERSION = '0.1.9'
3
3
  end
@@ -6,29 +6,36 @@ require 'markdown_helper/version'
6
6
  # @author Burdette Lamar
7
7
  class MarkdownHelper
8
8
 
9
- INCLUDE_REGEXP = /^@\[(:code_block|:verbatim|\w+)\]/
9
+ IMAGE_REGEXP = /^!\[([^\[]+)\]\(([^)]+)\)/
10
+ INCLUDE_REGEXP = /^@\[([^\[]+)\]\(([^)]+)\)/
11
+
12
+ # Get the user name and repository name from ENV.
13
+ def repo_user_and_name
14
+ repo_user = ENV['REPO_USER']
15
+ repo_name = ENV['REPO_NAME']
16
+ unless repo_user and repo_name
17
+ message = 'ENV values for both REPO_USER and REPO_NAME must be defined.'
18
+ raise RuntimeError.new(message)
19
+ end
20
+ [repo_user, repo_name]
21
+ end
10
22
 
11
23
  # Merges external files into markdown text.
12
24
  # @param template_file_path [String] the path to the input template markdown file, usually containing include pragmas.
13
25
  # @param markdown_file_path [String] the path to the output merged markdown file.
14
- # @raise [RuntimeError] if an include pragma parsing error occurs.
15
26
  # @return [String] the resulting markdown text.
16
27
  #
17
- # @example Pragma to include text as a highlighted code block.
28
+ # @example pragma to include text as a highlighted code block.
18
29
  # @[ruby](foo.rb)
19
30
  #
20
- # @example Pragma to include text as a plain code block.
31
+ # @example pragma to include text as a plain code block.
21
32
  # @[:code_block](foo.xyz)
22
33
  #
23
- # @example Pragma to include text verbatim, to be rendered as markdown.
34
+ # @example pragma to include text verbatim, to be rendered as markdown.
24
35
  # @[:verbatim](foo.md)
25
36
  def include(template_file_path, markdown_file_path)
26
37
  output_lines = []
27
38
  File.open(template_file_path, 'r') do |template_file|
28
- # For later.
29
- # if tag_as_generated
30
- # output_lines.push("<!--- GENERATED FILE, DO NOT EDIT --->\n")
31
- # end
32
39
  template_file.each_line do |input_line|
33
40
  match_data = input_line.match(INCLUDE_REGEXP)
34
41
  unless match_data
@@ -43,11 +50,7 @@ class MarkdownHelper
43
50
  else
44
51
  match_data[1]
45
52
  end
46
- file_path_in_parens = input_line.sub(INCLUDE_REGEXP, '')
47
- unless file_path_in_parens.start_with?('(') && file_path_in_parens.end_with?(")\n")
48
- raise RuntimeError.new(file_path_in_parens.inspect)
49
- end
50
- relative_file_path = file_path_in_parens.sub('(', '').sub(")\n", '')
53
+ relative_file_path = match_data[2]
51
54
  include_file_path = File.join(
52
55
  File.dirname(template_file_path),
53
56
  relative_file_path,
@@ -57,10 +60,6 @@ class MarkdownHelper
57
60
  message = "Warning: Included file has no trailing newline: #{include_file_path}"
58
61
  warn(message)
59
62
  end
60
- # For later.
61
- # extname = File.extname(include_file_path)
62
- # file_ext_key = extname.sub('.', '').to_sym
63
- # treatment ||= @treatment_for_file_ext[file_ext_key]
64
63
  if treatment == :verbatim
65
64
  # Pass through unadorned.
66
65
  output_lines.push(included_text)
@@ -83,4 +82,60 @@ class MarkdownHelper
83
82
  output
84
83
  end
85
84
 
86
- end
85
+ # Resolves relative image paths to absolute urls in markdown text.
86
+ # @param template_file_path [String] the path to the input template markdown file, usually containing image pragmas.
87
+ # @param markdown_file_path [String] the path to the output resolved markdown file.
88
+ # @return [String] the resulting markdown text.
89
+ #
90
+ # This matters because when markdown becomes part of a Ruby gem,
91
+ # its images will have been relocated in the documentation at RubyDoc.info, breaking the paths.
92
+ # The resolved (absolute) urls, however, will still be valid.
93
+ #
94
+ # ENV['REPO_USER'] and ENV['REPO_NAME'] must give the user name and repository name of the relevant GitHub repository.
95
+ # must give the repo name of the relevant GitHub repository.
96
+ #
97
+ # @example pragma for an image:
98
+ # ![image_icon](images/image.png)
99
+ #
100
+ # The path resolves to:
101
+ #
102
+ # absolute_file_path = File.join(
103
+ # "https://raw.githubusercontent.com/#{repo_user}/#{repo_name}/master",
104
+ # relative_file_path,
105
+ # )
106
+ def resolve_image_urls(template_file_path, markdown_file_path)
107
+ output_lines = []
108
+ File.open(template_file_path, 'r') do |template_file|
109
+ output_lines = []
110
+ template_file.each_line do |input_line|
111
+ match_data = input_line.match(IMAGE_REGEXP)
112
+ unless match_data
113
+ output_lines.push(input_line)
114
+ next
115
+ end
116
+ alt_text = match_data[1]
117
+ relative_file_path, attributes_s = match_data[2].split(/\s?\|\s?/, 2)
118
+ attributes = attributes_s ? attributes_s.split(/\s+/) : []
119
+ formatted_attributes = ['']
120
+ attributes.each do |attribute|
121
+ name, value = attribute.split('=', 2)
122
+ formatted_attributes.push(format('%s="%s"', name, value))
123
+ end
124
+ formatted_attributes_s = formatted_attributes.join(' ')
125
+ repo_user, repo_name = repo_user_and_name
126
+ absolute_file_path = File.join(
127
+ "https://raw.githubusercontent.com/#{repo_user}/#{repo_name}/master",
128
+ relative_file_path,
129
+ )
130
+ line = format('<img src="%s" alt="%s"%s>', absolute_file_path, alt_text, formatted_attributes_s) + "\n"
131
+ output_lines.push(line)
132
+ end
133
+ end
134
+ output = output_lines.join('')
135
+ File.open(markdown_file_path, 'w') do |md_file|
136
+ md_file.write(output)
137
+ end
138
+ output
139
+ end
140
+
141
+ end
@@ -4,7 +4,7 @@
4
4
 
5
5
  ## File Inclusion
6
6
 
7
- <img src="https://raw.githubusercontent.com/BurdetteLamar/MarkdownHelper/master/images/include.png" width="50">
7
+ ![include_icon](images/include.png | width=50)
8
8
 
9
9
  This markdown helper enables file inclusion in GitHub markdown.
10
10
 
@@ -36,7 +36,7 @@ Verbatim text is included unadorned. Most often, verbatim text is markdown to b
36
36
 
37
37
  #### API
38
38
 
39
- @[ruby](usage.rb)
39
+ @[ruby](include_usage.rb)
40
40
 
41
41
  #### Include Pragmas
42
42
 
@@ -54,6 +54,43 @@ where:
54
54
 
55
55
  ##### Example Include Pragmas
56
56
 
57
- @[verbatim](include.md)
57
+ @[code_block](include.md)
58
58
 
59
+ ## Image Path Resolution
60
+
61
+ ![image_icon](images/image.png | width=50)
62
+
63
+ This markdown helper enables image path resolution in GitHub markdown.
64
+
65
+ (Actually, this README file itself is built using image path resolution.)
66
+
67
+ Use the markdown helper to resolve image relative paths in a markdown (</code>.md</code>) file.
68
+
69
+ This matters because when markdown becomes part of a Ruby gem, its images will have been relocated in the documentation at RubyDoc.info, breaking the relative paths. The resolved (absolute) urls, however, will still be valid.
70
+
71
+ ### Usage
72
+
73
+ #### CLI
74
+
75
+ @[:code_block](../bin/usage/resolve_image_urls.txt)
76
+
77
+ #### API
78
+
79
+ @[ruby](resolve_image_urls_usage.rb)
80
+
81
+ #### Image Pragmas
82
+
83
+ Specify each image file via an *image pragma*, which has the form:
84
+
85
+ <code>![*alt_text*]\(</code>*relative_file_path* <code>|</code> *attributes*<code>)</code>
86
+
87
+ where:
88
+
89
+ * *alt_text* is the usual alt text for an HTML image.
90
+ * *relative_file_path* points to the file to be included.
91
+ * *attributes* are whitespace-separated name-value pairs in the form *name*<code>=</code>*value*. These are passed through to the generated <code>img</code> HTML element.
92
+
93
+ ##### Example Image Pragmas
94
+
95
+ @[code_block](resolve_image_urls.md)
59
96
 
@@ -2,5 +2,5 @@ require 'markdown_helper'
2
2
 
3
3
  markdown_helper = MarkdownHelper.new
4
4
  template_file_path = 'highlight_ruby_template.md'
5
- markdown_file_path = 'highlighted_ruby.rb'
5
+ markdown_file_path = 'highlighted_ruby.md'
6
6
  markdown_helper.include(template_file_path, markdown_file_path)
@@ -0,0 +1,5 @@
1
+ ![my_alt](image/image.png)
2
+
3
+ ![my_alt](image/image.png | width=50)
4
+
5
+ ![my_alt](image/image.png| width=50 height=50)
@@ -0,0 +1,6 @@
1
+ require 'markdown_helper'
2
+
3
+ markdown_helper = MarkdownHelper.new
4
+ template_file_path = 'template.md'
5
+ markdown_file_path = 'markdown.md'
6
+ markdown_helper.resolve_image_urls(template_file_path, markdown_file_path)
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: markdown_helper
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.8
4
+ version: 0.1.9
5
5
  platform: ruby
6
6
  authors:
7
7
  - burdettelamar
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2018-03-06 00:00:00.000000000 Z
11
+ date: 2018-03-09 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: bundler
@@ -84,9 +84,13 @@ files:
84
84
  - Rakefile
85
85
  - bin/console
86
86
  - bin/include
87
+ - bin/resolve_image_urls
87
88
  - bin/setup
88
89
  - bin/usage/include.txt
90
+ - bin/usage/resolve_image_urls.txt
91
+ - images/image.png
89
92
  - images/include.png
93
+ - images_resolved.md
90
94
  - lib/markdown_helper.rb
91
95
  - lib/markdown_helper/version.rb
92
96
  - markdown_helper.gemspec
@@ -96,7 +100,9 @@ files:
96
100
  - readme_files/highlighted_ruby.md
97
101
  - readme_files/include.md
98
102
  - readme_files/include.rb
99
- - readme_files/usage.rb
103
+ - readme_files/include_usage.rb
104
+ - readme_files/resolve_image_urls.md
105
+ - readme_files/resolve_image_urls_usage.rb
100
106
  - readme_files/verbatim_ruby_template.md
101
107
  homepage: https://github.com/BurdetteLamar/MarkdownHelper
102
108
  licenses: