rails_markdown_templates 0.0.1 → 1.0.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.
Files changed (7) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +37 -14
  3. data/lib/rails_markdown_templates/core.rb +10 -77
  4. data/lib/rails_markdown_templates/renderer.rb +95 -0
  5. data/lib/rails_markdown_templates/version.rb +1 -1
  6. data/lib/rails_markdown_templates.rb +1 -0
  7. metadata +2 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: ac25c1e0f1676d83301457ac08a463b60fb04ae1
4
- data.tar.gz: 9087ecf083c48b6444835cd7e878fc3ec51491d8
3
+ metadata.gz: 2d38a91c6b397d650055427672919dda346acb70
4
+ data.tar.gz: 62bbed916e1d29ff3f3b4f745287d35b2cb9beea
5
5
  SHA512:
6
- metadata.gz: 2112c73a8f1158514c8759808d91aae74a226fa7fce26c8ea96113038bcea286c7b670d4bd083dab725824a0e87ceac032be87a1f4250dc6bb0839989feda2e4
7
- data.tar.gz: fbc6f562706a07b78ecbcc0f5a1d375ff52519d0c3177cd18c67d286a55d6276d8379e24a1669010f2f68105219a86c4355eba37a69c2d3fea49e7546ec47d62
6
+ metadata.gz: 51dfc8ad276a410d33051a18daa4a25b8723809b605a4486dbf35f0dd36ff368126b2d1109225116cb6485a0dccbd7efa5b4c108b861b1112e8f0ee0d2caa9a4
7
+ data.tar.gz: e125ed4841dc67afed7b44d8a05826efdf835123c317499a84cef232d2583d02ca71c0715dc244a5b7e7c3d5a05245e42fca5509d4d162664f627d040fedd6f8
data/README.md CHANGED
@@ -1,9 +1,11 @@
1
1
  # RailsMarkdownTemplates
2
2
 
3
+ ## Synopsis
4
+
3
5
  The `rails_markdown_templates` gem allows the use of Markdown as a Rails
4
6
  template language. A leading metadata block is parsed, and the metadata
5
- made available via a `content_for` block with a customisable key. Embedded
6
- Ruby may be used in Markdown templates.
7
+ made available as HTML `<meta />` tags via a `content_for` block with a
8
+ customisable key. Embedded Ruby may be used in Markdown templates.
7
9
 
8
10
  ## Installation
9
11
 
@@ -27,13 +29,15 @@ gem install rails_markdown_templates
27
29
 
28
30
  ## Rails configuration
29
31
 
30
- Create the file `config/initializers/rails_markdown_templates.rb`, containing
31
- the following code.
32
+ No configuration is necessary to get started. By default, the keys for the
33
+ `content_for` blocks are `:metadata_tags` and `:metadata_json`; if you wish
34
+ to change these, then create a file in the
35
+ `config/initializers` directory, containing code such as the following.
36
+
32
37
  ```ruby
33
- # Hook up the Markdown template handler
34
- ActionView::Template::Handlers::Markdown.metadata_content_key = :metadata
35
- ActionView::Template.register_template_handler :md,
36
- ActionView::Template::Handlers::Markdown
38
+ # Set the metadata content keys for the Markdown template handler
39
+ ActionView::Template::Handlers::Markdown.metadata_tags_key = :my_metadata_tags
40
+ ActionView::Template::Handlers::Markdown.metadata_json_key = :my_metadata_json
37
41
  ```
38
42
 
39
43
  ## Embedded Ruby handling
@@ -43,7 +47,8 @@ Markdown templates may contain standard erb tags.
43
47
  ## Metadata handling
44
48
 
45
49
  Markdown templates may optionally have a leading YAML metadata block; for
46
- example
50
+ example:
51
+
47
52
  ```md
48
53
  ---
49
54
  title: This is the title
@@ -57,13 +62,31 @@ author: Bob Dylan
57
62
  Here is part of the document; a very meaningful part.
58
63
  ```
59
64
 
60
- The `metadata_content_key` attribute defines the name of the content block
61
- into which metadata will be placed. Metadata can be retrieved in Rails views
62
- using a yield call:
63
- ```ruby
64
- <%= yield :metadata %>
65
+ The `metadata_tags_key` and `metadata_tags_key` attributes define the names
66
+ of the content blocks into which metadata will be placed. Metadata can be
67
+ retrieved in Rails views using yield calls; for example:
68
+
69
+ ```html
70
+ <head>
71
+ <!-- Output meta tags -->
72
+ <%= yield :metadata_tags %>
73
+
74
+ <!-- Use metadata in JavaScript -->
75
+ <script>
76
+ var metadata = <%= yield :metadata_json %>;
77
+ </script>
78
+ </head>
65
79
  ```
66
80
 
81
+ This will output HTML `<meta />` tags: one for each metadata item present in
82
+ the original YAML metadata block.
83
+
84
+ > There is a restriction, however: you cannot `yield` the metadata content
85
+ > block from within the markdown template in which the metadata is defined.
86
+ >
87
+ > This is because the ERB tags are evaluated *before* the template is
88
+ > handed off to the Markdown parser.
89
+
67
90
  ## License
68
91
 
69
92
  Copyright 2015 Simon Dawson <spdawson@gmail.com>
data/lib/rails_markdown_templates/core.rb CHANGED
@@ -16,83 +16,17 @@
16
16
  # along with rails_markdown_templates. If not, see
17
17
  # <http://www.gnu.org/licenses/>.
18
18
 
19
- require 'English'
20
19
  require 'redcarpet'
21
- require 'yaml'
22
-
23
- # Custom Redcarpet HTML renderer for Markdown with a metadata block
24
- class MarkdownHTMLRenderer < Redcarpet::Render::HTML
25
- include Redcarpet::Render::SmartyPants
26
-
27
- attr_accessor :metadata
28
-
29
- def initialize(options={})
30
- redcarpet_options = {
31
- no_intra_emphasis: true,
32
- tables: true,
33
- fenced_code_blocks: true,
34
- autolink: true,
35
- disable_indented_code_blocks: true,
36
- strikethrough: true,
37
- lax_spacing: true,
38
- space_after_headers: true,
39
- superscript: true,
40
- underline: true,
41
- highlight: true,
42
- quote: true,
43
- footnotes: true
44
- }
45
- super options.merge(redcarpet_options)
46
- @metadata = {}
47
- end
48
-
49
- # Get HTML tag(s) for the metadata
50
- def metadata_tags
51
- metadata.map do |k,v|
52
- "<meta name=\"#{k}\" content=\"#{v}\" />"
53
- end.join("\n").html_safe
54
- end
55
-
56
- # Render before any other elements
57
- def doc_header
58
- nil
59
- end
60
-
61
- # Rendered after all the other elements
62
- def doc_footer
63
- nil
64
- end
65
-
66
- # Preprocess the whole document before the rendering process
67
- def preprocess(full_document)
68
- # Extract and store metadata block from start of document
69
- #
70
- # N.B. Implementation "borrowed" from Metadown:
71
- #
72
- # https://github.com/steveklabnik/metadown
73
- full_document =~ /^(---\s*\n.*?\n?)^(---\s*$\n?)/m
74
- self.metadata = YAML.load($1) if $1
75
-
76
- # Return the document without the leading metadata block
77
- $POSTMATCH or full_document
78
- end
79
-
80
- # Postprocess the whole document after the rendering process
81
- #
82
- # N.B. Cannot use postprocess: SmartyPants is using the single callback slot
83
- # def postprocess(full_document)
84
- # full_document
85
- # end
86
- end
20
+ require 'rails_markdown_templates/renderer'
87
21
 
88
22
  module ActionView
89
23
  module Template::Handlers
90
24
  # Rails template handler for markdown
91
25
  class Markdown
92
- class_attribute :default_format
93
- class_attribute :metadata_content_key
26
+ class_attribute :default_format, :metadata_tags_key, :metadata_json_key
94
27
  self.default_format = Mime::HTML
95
- self.metadata_content_key = :metadata
28
+ self.metadata_tags_key = :metadata_tags
29
+ self.metadata_json_key = :metadata_json
96
30
 
97
31
  def self.erb
98
32
  @erb ||= ActionView::Template.registered_template_handler :erb
@@ -105,11 +39,13 @@ module ActionView
105
39
  # Evaluate embedded Ruby
106
40
  compiled_source = erb.call(template)
107
41
 
108
- key = self.metadata_content_key
42
+ tags_key = self.metadata_tags_key
43
+ json_key = self.metadata_json_key
109
44
  <<-RUBY_CODE
110
- markdown = Redcarpet::Markdown.new(MarkdownHTMLRenderer)
45
+ markdown = Redcarpet::Markdown.new(RailsMarkdownTemplates::Renderer)
111
46
  output = markdown.render(begin;#{compiled_source};end)
112
- content_for("#{key}".to_sym, markdown.renderer.metadata_tags)
47
+ content_for("#{tags_key}".to_sym, markdown.renderer.metadata_tags)
48
+ content_for("#{json_key}".to_sym, markdown.renderer.metadata_json)
113
49
  output
114
50
  RUBY_CODE
115
51
  end
@@ -117,9 +53,6 @@ output
117
53
  end
118
54
  end
119
55
 
120
- # This is the "real" initialization code
121
- #
122
- # @todo FIXME: move the above code into library/module/gem
123
- ActionView::Template::Handlers::Markdown.metadata_content_key = :metadata
56
+ # Register the Markdown template handler
124
57
  ActionView::Template.register_template_handler :md,
125
58
  ActionView::Template::Handlers::Markdown
data/lib/rails_markdown_templates/renderer.rb ADDED
@@ -0,0 +1,95 @@
1
+ # Copyright 2015 Simon Dawson <spdawson@gmail.com>
2
+
3
+ # This file is part of rails_markdown_templates.
4
+ #
5
+ # rails_markdown_templates is free software: you can redistribute it and/or
6
+ # modify it under the terms of the GNU General Public License as published by
7
+ # the Free Software Foundation, either version 3 of the License, or
8
+ # (at your option) any later version.
9
+ #
10
+ # rails_markdown_templates is distributed in the hope that it will be useful,
11
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
12
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13
+ # GNU General Public License for more details.
14
+ #
15
+ # You should have received a copy of the GNU General Public License
16
+ # along with rails_markdown_templates. If not, see
17
+ # <http://www.gnu.org/licenses/>.
18
+
19
+ require 'English'
20
+ require 'json'
21
+ require 'redcarpet'
22
+ require 'yaml'
23
+
24
+ module RailsMarkdownTemplates
25
+ # Custom Redcarpet HTML renderer for Markdown with a metadata block
26
+ class Renderer < Redcarpet::Render::HTML
27
+ include Redcarpet::Render::SmartyPants
28
+
29
+ attr_accessor :metadata
30
+
31
+ def initialize(options={})
32
+ redcarpet_options = {
33
+ no_intra_emphasis: true,
34
+ tables: true,
35
+ fenced_code_blocks: true,
36
+ autolink: true,
37
+ disable_indented_code_blocks: true,
38
+ strikethrough: true,
39
+ lax_spacing: true,
40
+ space_after_headers: true,
41
+ superscript: true,
42
+ underline: true,
43
+ highlight: true,
44
+ quote: true,
45
+ footnotes: true
46
+ }
47
+ super options.merge(redcarpet_options)
48
+ @metadata = {}
49
+ end
50
+
51
+ # Get HTML tag(s) for the metadata
52
+ def metadata_tags
53
+ metadata.map do |k,v|
54
+ "<meta name=\"#{k}\" content=\"#{v}\" />"
55
+ end.join("\n").html_safe
56
+ end
57
+
58
+ # Get JSON for the metadata
59
+ def metadata_json
60
+ metadata.to_json.html_safe
61
+ end
62
+
63
+ # Render before any other elements
64
+ def doc_header
65
+ nil
66
+ end
67
+
68
+ # Rendered after all the other elements
69
+ def doc_footer
70
+ nil
71
+ end
72
+
73
+ # Preprocess the whole document before the rendering process
74
+ def preprocess(full_document)
75
+ # Extract and store metadata block from start of document
76
+ #
77
+ # N.B. Implementation "borrowed" from Metadown:
78
+ #
79
+ # https://github.com/steveklabnik/metadown
80
+ full_document =~ /^(---\s*\n.*?\n?)^(---\s*$\n?)/m
81
+ self.metadata = YAML.load($1) if $1
82
+
83
+ # Return the document without the leading metadata block
84
+ $POSTMATCH or full_document
85
+ end
86
+
87
+ # Postprocess the whole document after the rendering process
88
+ #
89
+ # N.B. Cannot use postprocess: SmartyPants is using the single callback
90
+ # slot
91
+ # def postprocess(full_document)
92
+ # full_document
93
+ # end
94
+ end
95
+ end
data/lib/rails_markdown_templates/version.rb CHANGED
@@ -17,5 +17,5 @@
17
17
  # <http://www.gnu.org/licenses/>.
18
18
 
19
19
  module RailsMarkdownTemplates
20
- VERSION = "0.0.1"
20
+ VERSION = "1.0.0"
21
21
  end
data/lib/rails_markdown_templates.rb CHANGED
@@ -17,4 +17,5 @@
17
17
  # <http://www.gnu.org/licenses/>.
18
18
 
19
19
  require 'rails_markdown_templates/core'
20
+ require 'rails_markdown_templates/renderer'
20
21
  require 'rails_markdown_templates/version'
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: rails_markdown_templates
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.1
4
+ version: 1.0.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Simon Dawson
@@ -51,6 +51,7 @@ files:
51
51
  - Rakefile
52
52
  - lib/rails_markdown_templates.rb
53
53
  - lib/rails_markdown_templates/core.rb
54
+ - lib/rails_markdown_templates/renderer.rb
54
55
  - lib/rails_markdown_templates/version.rb
55
56
  - rails_markdown_templates.gemspec
56
57
  homepage: https://github.com/spdawson/rails_markdown_templates