markdown-rails 2.0.0.alpha1 → 2.0.0.alpha2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 332076319e0211f26f2f3fe8ddb43864df474a0f746baac13bd7ad157224ba98
-  data.tar.gz: e331da478c55aeb4169457f3e79c13a396e2af439c079ebd36252653f9f413a4
+  metadata.gz: ff3573eb380c93787dd4df94e7244809402da5a8bd59482aa2b6606b6294f154
+  data.tar.gz: 7de29bab934217a0a8f38ff868d6fe7d0fa87d8c9a3b2de8c93a27d5f61496d8
 SHA512:
-  metadata.gz: ba18f8f0ae1b4f7af5b113355aaa3f43a58f366e177118d4506ac6b16d317520044a86ce69a3436da6cb1b7f96e3ef225557996fbb309ac9fb7e16c7f8823734
-  data.tar.gz: f7d859e209008e71bdc8c6c1ba5ae5f63b1f0f4b71ce43b36b8682af5b96761f49c842cc255fe9cef05d33d71d8820247461078698d62678a4aa8763523b26df
+  metadata.gz: b4f738f2f721f7d542f8986d0c63a7f1ac27f266d46091d938afa086b1c08ed967a8e77ebd9a4c8964787d3bddf396ba9eb86e9dd78bf511b937c182f9ce7127
+  data.tar.gz: 85496233bed31fabcc2585f9e9ef30f92a295b456058bce2d35228ac4e284bc276804570cedddbbfb399cac8f7594d3f69f40d0f1332e8c35d2afa1f39a67762

data/README.md

@@ -1,8 +1,7 @@
 # markdown-rails
 
 > **Note**
-> **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.
-> You can start using this by adding to `gem "markdown-rails", github: "sitepress/markdown-rails"` to your Gemfile.
+> **Everything below is implemented in 2.0.0.alpha1.** . 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.
 
 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!
 
@@ -34,67 +33,106 @@ This adds a `config/initializers/markdown.rb` file where you can register templa
 
 Now add views or partials ending in `.md` in your `./app/views/**/**` directories and behold!
 
+### Upgrading from 1.x
+
+Change your applications Gemfile to read:
+
+```ruby
+gem "markdown-rails", "~> 2.0.0"
+```
+
+Then from the root of your Rails project, run:
+
+```sh
+$ bin/rails g markdown:install
+```
+
+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.
+
 ## Configuration
 
 Applications commonly need various markdown variants within one application. For example,
 
+```ruby
+# ./config/initializers/markdown.rb
+# Restart the server to see changes made to this file.
+
+# Setup markdown stacks to work with different template handlers in Rails.
+Markdown::Rails.handle :md do
+  ApplicationMarkdown.new
+end
+
+Markdown::Rails.handle :crazymd do
+  MyCrazyMarkdown.new
+end
+```
+
+### Enable Erb in Markdown
+
+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.
+
+To enable Erb, you can tell Rails to render all view files ending with `.markerb` using the `Markdown::Rails::Handlers::Erb` handler.
+
+```ruby
+# ./config/initializers/markdown.rb
+Markdown::Rails.handle :markerb, with: Markdown::Rails::Handlers::Erb do
+  ApplicationMarkdown.new
+end
+```
+
+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:
 
 ```ruby
 # ./config/initializers/markdown.rb
-# Restart your server after making changes to these files.
+# Restart the server to see changes made to this file.
 
-# Renders markdown without Erb, which is safe for user inputs
-# unless you have some crazy unsafe blocks in the `ApplicationMarkdown` stack.
-MarkdownRails::Handler.register :md do
+# Setup markdown stacks to work with different template handlers in Rails.
+Markdown::Rails.handle :md do
   ApplicationMarkdown.new
 end
 
-# Use Erb in markdown templates, which is NOT safe for untrusted inputs
-# like blog post from a user. You should only use this for content that
-# you trust won't execute arbitrary Ruby code like views and templates in
-# your repo.
-MarkdownRails::ErbHandler.register :markerb do
+Markdown::Rails.handle :markerb, with: Markdown::Rails::Handlers::Erb do
   ApplicationMarkdown.new
 end
 ```
 
-You might want to customize your Markdown handlers to do things like syntax code highlighting, etc. Here's what that looks like:
+## Customizing renderers
+
+You might want to customize your Markdown handlers to do things like syntax code highlighting, etc.
 
 ```ruby
 # ./app/markdown/application_markdown.rb
+require "rouge"
+
 class ApplicationMarkdown < RailsMarkdown
   include Redcarpet::Render::SmartyPants
 
+  FORMATTER = Rouge::Formatters::HTMLInline.new("monokai.sublime")
+
   def enable
     [:fenced_code_blocks]
   end
 
   def block_code(code, language)
-    render Views::CodeBlock.new(code, syntax: language)
-  end
-
-  def image(link, title, alt)
-    url = URI(link)
-    case url.host
-    when "www.youtube.com"
-      render Views::YoutubeEmbed.new(url)
-    else
-      super
+    lexer = Rouge::Lexer.find(language)
+    content_tag :pre, class: language do
+      raw FORMATTER.format(lexer.lex(code))
     end
   end
-
-  private
-    def render(component)
-      component.call
-    end
 end
 ```
 
+Consider using a componet farmework, like [phlex](https://www.phlex.fun) to generate tags outside of the Rails view context.
+
 ## Examples
 
+There's a lot of ways to use Markdown in your Rails app.
+
+### The easy way
+
 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.
 
-### Static View
+### Static view
 
 In `app/views/home/about.html.md`:
 
@@ -106,7 +144,7 @@ In `app/views/home/about.html.md`:
 
 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.
 
-### Static Partial
+### Static partial
 
 In `app/views/posts/edit.html.erb`:
 
@@ -125,12 +163,7 @@ In `app/views/posts/_edit_help.html.md`:
 This text is written in **Markdown**. :-)
 ```
 
-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`.
-
+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`.
 
 ## Security
 

data/lib/generators/markdown/install/templates/app/markdown/application_markdown.rb

@@ -40,7 +40,7 @@ class ApplicationMarkdown < Markdown::Rails::Renderers::Rails
     url = URI(link)
     case url.host
     when "www.youtube.com"
-      youtube_tag url
+      youtube_tag url, alt
     else
       super
     end
@@ -48,13 +48,14 @@ class ApplicationMarkdown < Markdown::Rails::Renderers::Rails
 
   private
     # This is provided as an example; there's many more YouTube URLs that this wouldn't catch.
-    def youtube_tag(url)
+    def youtube_tag(url, alt)
       embed_url = "https://www.youtube-nocookie.com/embed/#{CGI.parse(url.query).fetch("v").first}"
-      tag :iframe,
+      content_tag :iframe,
+        src: embed_url,
         width: 560,
         height: 325,
-        src: embed_url,
         allow: "encrypted-media; picture-in-picture",
-        allowfullscreen: true
+        allowfullscreen: true \
+          do alt end
     end
 end

data/lib/generators/markdown/install/templates/config/initializers/markdown.rb

@@ -8,10 +8,6 @@ end
 # Don't use Erb for untrusted markdown content created by users; otherwise they
 # can execute arbitrary code on your server. This should only be used for input you
 # trust, like content files from your code repo.
-#
-# Make sure you know what you're doing before you uncomment the block below to get
-# Erb working with Markdown.
-
-# Markdown::Rails.handle :markerb, with: Markdown::Rails::Handlers::Erb do
-#   ApplicationMarkdown.new
-# end
+Markdown::Rails.handle :markerb, with: Markdown::Rails::Handlers::Erb do
+  ApplicationMarkdown.new
+end

data/lib/markdown/rails/renderers/rails.rb

@@ -25,6 +25,7 @@ module Markdown
           :request,
           :turbo_frame_tag,
           :controller,
+          :raw,
         to: :helpers
 
         def image(link, title, alt)

data/lib/markdown/rails/version.rb

@@ -1,5 +1,5 @@
 module Markdown
   module Rails
-    VERSION = "2.0.0.alpha1"
+    VERSION = "2.0.0.alpha2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markdown-rails
 version: !ruby/object:Gem::Version
-  version: 2.0.0.alpha1
+  version: 2.0.0.alpha2
 platform: ruby
 authors:
 - Brad Gessler