rails_markdown_templates 0.0.1 → 1.0.0

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