markdown-rails 2.0.0.alpha1 → 2.0.0.alpha3

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: 332076319e0211f26f2f3fe8ddb43864df474a0f746baac13bd7ad157224ba98
4
- data.tar.gz: e331da478c55aeb4169457f3e79c13a396e2af439c079ebd36252653f9f413a4
3
+ metadata.gz: 9028694bb249a0368da3f54c2c14f2d73df7409ca7440dd6fdd7b9b3ff2241cb
4
+ data.tar.gz: 82eb901cbf4a4a1f378bcbc5631ea054c4ec2b0bbc9af605ef1298aa09cfd0b6
5
5
  SHA512:
6
- metadata.gz: ba18f8f0ae1b4f7af5b113355aaa3f43a58f366e177118d4506ac6b16d317520044a86ce69a3436da6cb1b7f96e3ef225557996fbb309ac9fb7e16c7f8823734
7
- data.tar.gz: f7d859e209008e71bdc8c6c1ba5ae5f63b1f0f4b71ce43b36b8682af5b96761f49c842cc255fe9cef05d33d71d8820247461078698d62678a4aa8763523b26df
6
+ metadata.gz: ff5d28ec913cec33a99cd5475652af7528599c649ccb2fed0922b9e25ed7bad40b5eac0fdb57e2db8415533ac18f6442612d8a22a872420bd0b66193db986fe0
7
+ data.tar.gz: 43ffda25ea19dca4acabb9a1a7dcdd7e83a4e3aa5fbe08a035466031ac5e7a63566ba938edbd7bcfbc96f2c0deddaa37baacb7078db9862880cae8a6424e21b3
data/README.md CHANGED
@@ -1,8 +1,7 @@
1
1
  # markdown-rails
2
2
 
3
3
  > **Note**
4
- > **Everything below will be implemented in 2.0.0.alpha1, which is not yet released.** This was written to get feedback about the Dev UX of this gem as the proof-of-concept is brought over from https://github.com/bradgessler/view-playground.
5
- > You can start using this by adding to `gem "markdown-rails", github: "sitepress/markdown-rails"` to your Gemfile.
4
+ > **Everything below is implemented in 2.0.0.alpha.** . You can start using this by adding to `gem "markdown-rails", version: "2.0.0.alpha"` to your Gemfile or by looking at it being used in the https://github.com/bradgessler/view-playground repo.
6
5
 
7
6
  This gem allows you to write static Rails views and partials using the [Markdown](http://daringfireball.net/projects/markdown/syntax) syntax. No more editing prose in HTML!
8
7
 
@@ -30,71 +29,110 @@ Then from the root of your Rails project, run:
30
29
  $ bin/rails g markdown:install
31
30
  ```
32
31
 
33
- This adds a `config/initializers/markdown.rb` file where you can register template handlers for your Markdown renders that are located in `./app/markdown/*.rb`.
32
+ This adds a `config/initializers/markdown.rb` file where you can register template handler for your Markdown renders that are located in `./app/markdown/*.rb`.
34
33
 
35
34
  Now add views or partials ending in `.md` in your `./app/views/**/**` directories and behold!
36
35
 
36
+ ### Upgrading from 1.x
37
+
38
+ Change your applications Gemfile to read:
39
+
40
+ ```ruby
41
+ gem "markdown-rails", "~> 2.0.0"
42
+ ```
43
+
44
+ Then from the root of your Rails project, run:
45
+
46
+ ```sh
47
+ $ bin/rails g markdown:install
48
+ ```
49
+
50
+ If you have an existing file in `config/initializers/markdown.rb` you'll need to move those settings over. Note that 1.x used `RDiscount` as the default renderer, which was replaced by `Redcarpet` in 2.x.
51
+
37
52
  ## Configuration
38
53
 
39
54
  Applications commonly need various markdown variants within one application. For example,
40
55
 
56
+ ```ruby
57
+ # ./config/initializers/markdown.rb
58
+ # Restart the server to see changes made to this file.
59
+
60
+ # Setup markdown stacks to work with different template handler in Rails.
61
+ Markdown::Rails.handle :md do
62
+ ApplicationMarkdown.new
63
+ end
64
+
65
+ Markdown::Rails.handle :crazymd do
66
+ MyCrazyMarkdown.new
67
+ end
68
+ ```
69
+
70
+ ### Enable Erb in Markdown
71
+
72
+ Only enable Erb in Markdown if you trust the source of the file. Do not enable it for markdown provided by users or they will be able to execute arbitrary Ruby code.
73
+
74
+ To enable Erb, you can tell Rails to render all view files ending with `.markerb` using the `Markdown::Rails::Handler::Erb` handler.
75
+
76
+ ```ruby
77
+ # ./config/initializers/markdown.rb
78
+ Markdown::Rails.handle :markerb, with: Markdown::Rails::Handler::Erb do
79
+ ApplicationMarkdown.new
80
+ end
81
+ ```
82
+
83
+ You *could* change `:markerb` to `:md`, but I don't recommend it for all Markdown files or you'll run into problems if you have content like `<%= Time.current %>` inside of an `erb` codefence. You're better off having two configurations: one that handles Erb and another that doesn't, like this:
41
84
 
42
85
  ```ruby
43
86
  # ./config/initializers/markdown.rb
44
- # Restart your server after making changes to these files.
87
+ # Restart the server to see changes made to this file.
45
88
 
46
- # Renders markdown without Erb, which is safe for user inputs
47
- # unless you have some crazy unsafe blocks in the `ApplicationMarkdown` stack.
48
- MarkdownRails::Handler.register :md do
89
+ # Setup markdown stacks to work with different template handler in Rails.
90
+ Markdown::Rails.handle :md do
49
91
  ApplicationMarkdown.new
50
92
  end
51
93
 
52
- # Use Erb in markdown templates, which is NOT safe for untrusted inputs
53
- # like blog post from a user. You should only use this for content that
54
- # you trust won't execute arbitrary Ruby code like views and templates in
55
- # your repo.
56
- MarkdownRails::ErbHandler.register :markerb do
94
+ Markdown::Rails.handle :markerb, with: Markdown::Rails::Handler::Erb do
57
95
  ApplicationMarkdown.new
58
96
  end
59
97
  ```
60
98
 
61
- You might want to customize your Markdown handlers to do things like syntax code highlighting, etc. Here's what that looks like:
99
+ ## Customizing renderer
100
+
101
+ You might want to customize your Markdown handler to do things like syntax code highlighting, etc.
62
102
 
63
103
  ```ruby
64
104
  # ./app/markdown/application_markdown.rb
105
+ require "rouge"
106
+
65
107
  class ApplicationMarkdown < RailsMarkdown
66
108
  include Redcarpet::Render::SmartyPants
67
109
 
110
+ FORMATTER = Rouge::Formatters::HTMLInline.new("monokai.sublime")
111
+
68
112
  def enable
69
113
  [:fenced_code_blocks]
70
114
  end
71
115
 
72
116
  def block_code(code, language)
73
- render Views::CodeBlock.new(code, syntax: language)
74
- end
75
-
76
- def image(link, title, alt)
77
- url = URI(link)
78
- case url.host
79
- when "www.youtube.com"
80
- render Views::YoutubeEmbed.new(url)
81
- else
82
- super
117
+ lexer = Rouge::Lexer.find(language)
118
+ content_tag :pre, class: language do
119
+ raw FORMATTER.format(lexer.lex(code))
83
120
  end
84
121
  end
85
-
86
- private
87
- def render(component)
88
- component.call
89
- end
90
122
  end
91
123
  ```
92
124
 
125
+ Consider using a componet farmework, like [phlex](https://www.phlex.fun) to generate tags outside of the Rails view context.
126
+
93
127
  ## Examples
94
128
 
129
+ There's a lot of ways to use Markdown in your Rails app.
130
+
131
+ ### The easy way
132
+
95
133
  Your best bet is to use this with a content management site like https://sitepress.cc/ if you're going to be dealing with a lot of markdown content on your website.
96
134
 
97
- ### Static View
135
+ ### Static view
98
136
 
99
137
  In `app/views/home/about.html.md`:
100
138
 
@@ -106,7 +144,7 @@ In `app/views/home/about.html.md`:
106
144
 
107
145
  Keep in mind that unlike static files dropped in `public`, you still need a matching route, such as `get ':action', :controller => :home`, to route `/about` to `home#about`. You could also [use Sitepress](https://sitepress.cc) to automatically manage these routes for you if you're dealing with a lot of pages.
108
146
 
109
- ### Static Partial
147
+ ### Static partial
110
148
 
111
149
  In `app/views/posts/edit.html.erb`:
112
150
 
@@ -125,12 +163,7 @@ In `app/views/posts/_edit_help.html.md`:
125
163
  This text is written in **Markdown**. :-)
126
164
  ```
127
165
 
128
- Note: If you are including Markdown partials from a Haml view, `<pre>` blocks
129
- inside your Markdown may be indented when Haml is not in ["ugly" (production)
130
- mode](http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html#ugly-option),
131
- causing leading white-space to appear in development mode. To fix this, set
132
- `Haml::Template.options[:ugly] = true`.
133
-
166
+ Note: If you are including Markdown partials from a Haml view, `<pre>` blocks inside your Markdown may be indented when Haml is not in ["ugly" (production) mode](http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html#ugly-option), causing leading white-space to appear in development mode. To fix this, set `Haml::Template.options[:ugly] = true`.
134
167
 
135
168
  ## Security
136
169
 
@@ -1,13 +1,13 @@
1
1
  # You should read the docs at https://github.com/vmg/redcarpet and probably
2
2
  # delete a bunch of stuff below if you don't need it.
3
3
 
4
- class ApplicationMarkdown < Markdown::Rails::Renderers::Rails
4
+ class ApplicationMarkdown < Markdown::Rails::Renderer::Rails
5
5
  # Reformats your boring punctation like " and " into “ and ” so you can look
6
6
  # and feel smarter. Read the docs at https://github.com/vmg/redcarpet#also-now-our-pants-are-much-smarter
7
7
  include Redcarpet::Render::SmartyPants
8
8
 
9
9
  # If you need access to ActionController::Base.helpers, you can delegate by uncommenting
10
- # and adding to the list below. Several are already included for you in the `Markdown::Rails::Renderers::Rails`,
10
+ # and adding to the list below. Several are already included for you in the `Markdown::Rails::Renderer::Rails`,
11
11
  # but you can add more here.
12
12
  #
13
13
  # To see a list of methods available run `bin/rails runner "puts ActionController::Base.helpers.public_methods.sort"`
@@ -40,7 +40,7 @@ class ApplicationMarkdown < Markdown::Rails::Renderers::Rails
40
40
  url = URI(link)
41
41
  case url.host
42
42
  when "www.youtube.com"
43
- youtube_tag url
43
+ youtube_tag url, alt
44
44
  else
45
45
  super
46
46
  end
@@ -48,13 +48,14 @@ class ApplicationMarkdown < Markdown::Rails::Renderers::Rails
48
48
 
49
49
  private
50
50
  # This is provided as an example; there's many more YouTube URLs that this wouldn't catch.
51
- def youtube_tag(url)
51
+ def youtube_tag(url, alt)
52
52
  embed_url = "https://www.youtube-nocookie.com/embed/#{CGI.parse(url.query).fetch("v").first}"
53
- tag :iframe,
53
+ content_tag :iframe,
54
+ src: embed_url,
54
55
  width: 560,
55
56
  height: 325,
56
- src: embed_url,
57
57
  allow: "encrypted-media; picture-in-picture",
58
- allowfullscreen: true
58
+ allowfullscreen: true \
59
+ do alt end
59
60
  end
60
61
  end
@@ -1,6 +1,6 @@
1
1
  # Restart the server to see changes made to this file.
2
2
 
3
- # Setup markdown stacks to work with different template handlers in Rails.
3
+ # Setup markdown stacks to work with different template handler in Rails.
4
4
  Markdown::Rails.handle :md, :markdown do
5
5
  ApplicationMarkdown.new
6
6
  end
@@ -8,10 +8,6 @@ end
8
8
  # Don't use Erb for untrusted markdown content created by users; otherwise they
9
9
  # can execute arbitrary code on your server. This should only be used for input you
10
10
  # trust, like content files from your code repo.
11
- #
12
- # Make sure you know what you're doing before you uncomment the block below to get
13
- # Erb working with Markdown.
14
-
15
- # Markdown::Rails.handle :markerb, with: Markdown::Rails::Handlers::Erb do
16
- # ApplicationMarkdown.new
17
- # end
11
+ Markdown::Rails.handle :markerb, with: Markdown::Rails::Handler::Erb do
12
+ ApplicationMarkdown.new
13
+ end
@@ -1,6 +1,6 @@
1
1
  module Markdown
2
2
  module Rails
3
- module Handlers
3
+ module Handler
4
4
  class Erb < Markdown
5
5
  def call(template, source = template.source)
6
6
  compiled_source = compile_erb template, source
@@ -1,6 +1,6 @@
1
1
  module Markdown
2
2
  module Rails
3
- module Handlers
3
+ module Handler
4
4
  # We cannot use Markdown::Rails because it conflicts with RDiscount's Markdown class
5
5
  class Markdown
6
6
  def initialize(&block)
@@ -1,10 +1,10 @@
1
1
  module Markdown
2
2
  module Rails
3
- module Renderers
3
+ module Renderer
4
4
  class Base < Redcarpet::Render::HTML
5
5
  def enable
6
6
  # This is a very restrictive Markdown renderer that errs on the side of safety.
7
- # For more details read the docs at https://github.com/vmg/redcarpet#darling-i-packed-you-a-couple-renderers-for-lunch
7
+ # For more details read the docs at https://github.com/vmg/redcarpet#darling-i-packed-you-a-couple-renderer-for-lunch
8
8
  [
9
9
  :filter_html,
10
10
  :no_images,
@@ -1,6 +1,6 @@
1
1
  module Markdown
2
2
  module Rails
3
- module Renderers
3
+ module Renderer
4
4
  class Rails < Base
5
5
  include ::Rails.application.routes.url_helpers
6
6
 
@@ -25,6 +25,7 @@ module Markdown
25
25
  :request,
26
26
  :turbo_frame_tag,
27
27
  :controller,
28
+ :raw,
28
29
  to: :helpers
29
30
 
30
31
  def image(link, title, alt)
@@ -1,5 +1,5 @@
1
1
  module Markdown
2
2
  module Rails
3
- VERSION = "2.0.0.alpha1"
3
+ VERSION = "2.0.0.alpha3"
4
4
  end
5
5
  end
@@ -3,18 +3,18 @@ require "markdown/rails/engine"
3
3
 
4
4
  module Markdown
5
5
  module Rails
6
- def self.handle(*extensions, with: Handlers::Markdown, &block)
6
+ def self.handle(*extensions, with: Handler::Markdown, &block)
7
7
  with.handle *extensions, &block
8
8
  end
9
9
 
10
- module Handlers
11
- autoload :Markdown, "markdown/rails/handlers/markdown"
12
- autoload :Erb, "markdown/rails/handlers/erb"
10
+ module Handler
11
+ autoload :Markdown, "markdown/rails/handler/markdown"
12
+ autoload :Erb, "markdown/rails/handler/erb"
13
13
  end
14
14
 
15
- module Renderers
16
- autoload :Base, "markdown/rails/renderers/base"
17
- autoload :Rails, "markdown/rails/renderers/rails"
15
+ module Renderer
16
+ autoload :Base, "markdown/rails/renderer/base"
17
+ autoload :Rails, "markdown/rails/renderer/rails"
18
18
  end
19
19
  end
20
20
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: markdown-rails
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.0.0.alpha1
4
+ version: 2.0.0.alpha3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Brad Gessler
@@ -57,11 +57,11 @@ files:
57
57
  - lib/markdown-rails.rb
58
58
  - lib/markdown/rails.rb
59
59
  - lib/markdown/rails/engine.rb
60
- - lib/markdown/rails/handlers/erb.rb
61
- - lib/markdown/rails/handlers/markdown.rb
60
+ - lib/markdown/rails/handler/erb.rb
61
+ - lib/markdown/rails/handler/markdown.rb
62
62
  - lib/markdown/rails/railtie.rb
63
- - lib/markdown/rails/renderers/base.rb
64
- - lib/markdown/rails/renderers/rails.rb
63
+ - lib/markdown/rails/renderer/base.rb
64
+ - lib/markdown/rails/renderer/rails.rb
65
65
  - lib/markdown/rails/version.rb
66
66
  - lib/tasks/markdown/rails_tasks.rake
67
67
  homepage: https://github.com/sitepress/markdown-rails