markdown-rails 2.0.0.alpha1 → 2.0.0.alpha3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 332076319e0211f26f2f3fe8ddb43864df474a0f746baac13bd7ad157224ba98
-  data.tar.gz: e331da478c55aeb4169457f3e79c13a396e2af439c079ebd36252653f9f413a4
+  metadata.gz: 9028694bb249a0368da3f54c2c14f2d73df7409ca7440dd6fdd7b9b3ff2241cb
+  data.tar.gz: 82eb901cbf4a4a1f378bcbc5631ea054c4ec2b0bbc9af605ef1298aa09cfd0b6
 SHA512:
-  metadata.gz: ba18f8f0ae1b4f7af5b113355aaa3f43a58f366e177118d4506ac6b16d317520044a86ce69a3436da6cb1b7f96e3ef225557996fbb309ac9fb7e16c7f8823734
-  data.tar.gz: f7d859e209008e71bdc8c6c1ba5ae5f63b1f0f4b71ce43b36b8682af5b96761f49c842cc255fe9cef05d33d71d8820247461078698d62678a4aa8763523b26df
+  metadata.gz: ff5d28ec913cec33a99cd5475652af7528599c649ccb2fed0922b9e25ed7bad40b5eac0fdb57e2db8415533ac18f6442612d8a22a872420bd0b66193db986fe0
+  data.tar.gz: 43ffda25ea19dca4acabb9a1a7dcdd7e83a4e3aa5fbe08a035466031ac5e7a63566ba938edbd7bcfbc96f2c0deddaa37baacb7078db9862880cae8a6424e21b3

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.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.
 
 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!
 
@@ -30,71 +29,110 @@ Then from the root of your Rails project, run:
 $ bin/rails g markdown:install
 ```
 
-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`.
+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`.
 
 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 handler 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::Handler::Erb` handler.
+
+```ruby
+# ./config/initializers/markdown.rb
+Markdown::Rails.handle :markerb, with: Markdown::Rails::Handler::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 handler 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::Handler::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 renderer
+
+You might want to customize your Markdown handler 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

@@ -1,13 +1,13 @@
 # You should read the docs at https://github.com/vmg/redcarpet and probably
 # delete a bunch of stuff below if you don't need it.
 
-class ApplicationMarkdown < Markdown::Rails::Renderers::Rails
+class ApplicationMarkdown < Markdown::Rails::Renderer::Rails
   # Reformats your boring punctation like " and " into “ and ” so you can look
   # and feel smarter. Read the docs at https://github.com/vmg/redcarpet#also-now-our-pants-are-much-smarter
   include Redcarpet::Render::SmartyPants
 
   # If you need access to ActionController::Base.helpers, you can delegate by uncommenting
-  # and adding to the list below. Several are already included for you in the `Markdown::Rails::Renderers::Rails`,
+  # and adding to the list below. Several are already included for you in the `Markdown::Rails::Renderer::Rails`,
   # but you can add more here.
   #
   # 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
     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

@@ -1,6 +1,6 @@
 # Restart the server to see changes made to this file.
 
-# Setup markdown stacks to work with different template handlers in Rails.
+# Setup markdown stacks to work with different template handler in Rails.
 Markdown::Rails.handle :md, :markdown do
   ApplicationMarkdown.new
 end
@@ -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::Handler::Erb do
+  ApplicationMarkdown.new
+end

data/lib/markdown/rails/{handlers → handler}/erb.rb

@@ -1,6 +1,6 @@
 module Markdown
   module Rails
-    module Handlers
+    module Handler
       class Erb < Markdown
         def call(template, source = template.source)
           compiled_source = compile_erb template, source

data/lib/markdown/rails/{handlers → handler}/markdown.rb

@@ -1,6 +1,6 @@
 module Markdown
   module Rails
-    module Handlers
+    module Handler
       # We cannot use Markdown::Rails because it conflicts with RDiscount's Markdown class
       class Markdown
         def initialize(&block)

data/lib/markdown/rails/{renderers → renderer}/base.rb

@@ -1,10 +1,10 @@
 module Markdown
   module Rails
-    module Renderers
+    module Renderer
       class Base < Redcarpet::Render::HTML
         def enable
           # This is a very restrictive Markdown renderer that errs on the side of safety.
-          # For more details read the docs at https://github.com/vmg/redcarpet#darling-i-packed-you-a-couple-renderers-for-lunch
+          # For more details read the docs at https://github.com/vmg/redcarpet#darling-i-packed-you-a-couple-renderer-for-lunch
           [
             :filter_html,
             :no_images,

data/lib/markdown/rails/{renderers → renderer}/rails.rb

@@ -1,6 +1,6 @@
 module Markdown
   module Rails
-    module Renderers
+    module Renderer
       class Rails < Base
         include ::Rails.application.routes.url_helpers
 
@@ -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.alpha3"
   end
 end

data/lib/markdown/rails.rb

@@ -3,18 +3,18 @@ require "markdown/rails/engine"
 
 module Markdown
   module Rails
-    def self.handle(*extensions, with: Handlers::Markdown, &block)
+    def self.handle(*extensions, with: Handler::Markdown, &block)
       with.handle *extensions, &block
     end
 
-    module Handlers
-      autoload :Markdown,   "markdown/rails/handlers/markdown"
-      autoload :Erb,        "markdown/rails/handlers/erb"
+    module Handler
+      autoload :Markdown,   "markdown/rails/handler/markdown"
+      autoload :Erb,        "markdown/rails/handler/erb"
     end
 
-    module Renderers
-      autoload :Base,       "markdown/rails/renderers/base"
-      autoload :Rails,      "markdown/rails/renderers/rails"
+    module Renderer
+      autoload :Base,       "markdown/rails/renderer/base"
+      autoload :Rails,      "markdown/rails/renderer/rails"
     end
   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.alpha3
 platform: ruby
 authors:
 - Brad Gessler
@@ -57,11 +57,11 @@ files:
 - lib/markdown-rails.rb
 - lib/markdown/rails.rb
 - lib/markdown/rails/engine.rb
-- lib/markdown/rails/handlers/erb.rb
-- lib/markdown/rails/handlers/markdown.rb
+- lib/markdown/rails/handler/erb.rb
+- lib/markdown/rails/handler/markdown.rb
 - lib/markdown/rails/railtie.rb
-- lib/markdown/rails/renderers/base.rb
-- lib/markdown/rails/renderers/rails.rb
+- lib/markdown/rails/renderer/base.rb
+- lib/markdown/rails/renderer/rails.rb
 - lib/markdown/rails/version.rb
 - lib/tasks/markdown/rails_tasks.rake
 homepage: https://github.com/sitepress/markdown-rails