markbridge 0.3.0 → 0.4.0

data/lib/markbridge/renderers/discourse/tags/poll_tag.rb

@@ -18,11 +18,9 @@ module Markbridge
         #     end
         #   end
         class PollTag < Tag
-          def render(element, interface)
+          def render(element, _interface)
             body = element.raw || build_poll_bbcode(element)
-            return "\n\n#{body}\n\n" if interface.html_mode?
-
-            "#{body}\n\n"
+            "\n\n#{body}\n\n"
           end
 
           private

data/lib/markbridge/renderers/discourse/tags/spoiler_tag.rb

@@ -11,6 +11,10 @@ module Markbridge
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
 
+            # A spoiler with nothing to hide renders to nothing — an empty
+            # [spoiler] shell would only add noise to the output.
+            return "" if content.empty?
+
             return render_html(element.title, content) if interface.html_mode?
 
             if element.title

data/lib/markbridge/renderers/discourse.rb

@@ -7,6 +7,7 @@ require_relative "discourse/rendering_interface"
 require_relative "discourse/markdown_escaper"
 require_relative "discourse/identity_escaper"
 require_relative "discourse/html_escaper"
+require_relative "discourse/html_block_safety"
 require_relative "discourse/postprocessor"
 
 # Builders

data/lib/markbridge/rspec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../markbridge"
+
+# Shared RSpec examples for consumers who write their own renderer
+# tags. Require this file from your spec setup (RSpec itself must
+# already be loaded):
+#
+#     require "markbridge/rspec"
+#
+# and put a custom tag under the html_mode contract:
+#
+#     RSpec.describe MyQuoteTag do
+#       it_behaves_like "an html_mode safe tag" do
+#         let(:tag) { described_class.new }
+#         let(:element) do
+#           element = MyQuote.new
+#           element << Markbridge::AST::Text.new("body *with* sigils")
+#           element
+#         end
+#       end
+#     end
+#
+# The example renders +element+ with +tag+ in html_mode and fails when
+# the output would break inside a CommonMark HTML block — the same
+# check Markbridge runs against its own tags. Give +element+ children
+# whose text contains Markdown sigils, so a tag that passes them
+# through unprotected is caught. When the tag needs a customized
+# renderer to resolve its children (for example a custom tag library),
+# override +markbridge_renderer+ with your configured renderer.
+RSpec.shared_examples "an html_mode safe tag" do
+  let(:markbridge_renderer) { Markbridge::Renderers::Discourse::Renderer.new }
+
+  let(:markbridge_html_mode_interface) do
+    context = Markbridge::Renderers::Discourse::RenderContext.new([], html_mode: true)
+    Markbridge::Renderers::Discourse::RenderingInterface.new(markbridge_renderer, context)
+  end
+
+  it "renders html_mode output that is safe inside an HTML block" do
+    output = tag.render(element, markbridge_html_mode_interface)
+
+    expect(Markbridge::Renderers::Discourse::HtmlBlockSafety.safe?(output)).to be(true),
+    "Expected #{tag.class} to render raw HTML or a \\n\\n-wrapped " \
+      "Markdown island in html_mode, got: #{output.inspect}"
+  end
+end

data/lib/markbridge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Markbridge
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/markbridge.rb

@@ -5,6 +5,7 @@ require_relative "markbridge/parse"
 require_relative "markbridge/conversion"
 
 require_relative "markbridge/ast"
+require_relative "markbridge/normalizer"
 require_relative "markbridge/renderers/discourse"
 
 module Markbridge
@@ -44,11 +45,21 @@ module Markbridge
     #   {Conversion} with an empty +markdown+ string, and surface the
     #   exceptions via {Conversion#errors}.
     # @yieldparam ast [AST::Document] mutate before rendering (optional)
+    # @param normalize [Boolean, Normalizer] apply target-format nesting
+    #   rules between the +yield+ hook and render. +true+ (default) uses the
+    #   shared default normalizer; a {Normalizer} is used as-is; +false+
+    #   skips normalization. See {Normalizer}.
     # @return [Conversion]
-    def bbcode_to_markdown(input, handlers: nil, renderer: nil, raise_on_error: true)
+    def bbcode_to_markdown(
+      input,
+      handlers: nil,
+      renderer: nil,
+      raise_on_error: true,
+      normalize: true
+    )
       parse = parse_bbcode(input, handlers:)
       yield(parse.ast) if block_given?
-      build_conversion(parse, renderer:, raise_on_error:)
+      build_conversion(parse, renderer:, raise_on_error:, normalize:)
     end
 
     # Parse HTML to AST.
@@ -85,11 +96,12 @@ module Markbridge
     #   {Conversion} with an empty +markdown+ string, and surface the
     #   exceptions via {Conversion#errors}.
     # @yieldparam ast [AST::Document] mutate before rendering (optional)
+    # @param normalize [Boolean, Normalizer] see {.bbcode_to_markdown}
     # @return [Conversion]
-    def html_to_markdown(input, handlers: nil, renderer: nil, raise_on_error: true)
+    def html_to_markdown(input, handlers: nil, renderer: nil, raise_on_error: true, normalize: true)
       parse = parse_html(input, handlers:)
       yield(parse.ast) if block_given?
-      build_conversion(parse, renderer:, raise_on_error:)
+      build_conversion(parse, renderer:, raise_on_error:, normalize:)
     end
 
     # Parse s9e/TextFormatter XML to AST.
@@ -122,11 +134,18 @@ module Markbridge
     # @param renderer [Renderers::Discourse::Renderer, nil] custom renderer
     # @param raise_on_error [Boolean] see {.bbcode_to_markdown}
     # @yieldparam ast [AST::Document] mutate before rendering (optional)
+    # @param normalize [Boolean, Normalizer] see {.bbcode_to_markdown}
     # @return [Conversion]
-    def text_formatter_xml_to_markdown(input, handlers: nil, renderer: nil, raise_on_error: true)
+    def text_formatter_xml_to_markdown(
+      input,
+      handlers: nil,
+      renderer: nil,
+      raise_on_error: true,
+      normalize: true
+    )
       parse = parse_text_formatter_xml(input, handlers:)
       yield(parse.ast) if block_given?
-      build_conversion(parse, renderer:, raise_on_error:)
+      build_conversion(parse, renderer:, raise_on_error:, normalize:)
     end
 
     # Parse MediaWiki wikitext to AST.
@@ -155,11 +174,18 @@ module Markbridge
     # @param renderer [Renderers::Discourse::Renderer, nil] custom renderer
     # @param raise_on_error [Boolean] see {.bbcode_to_markdown}
     # @yieldparam ast [AST::Document] mutate before rendering (optional)
+    # @param normalize [Boolean, Normalizer] see {.bbcode_to_markdown}
     # @return [Conversion]
-    def mediawiki_to_markdown(input, handlers: nil, renderer: nil, raise_on_error: true)
+    def mediawiki_to_markdown(
+      input,
+      handlers: nil,
+      renderer: nil,
+      raise_on_error: true,
+      normalize: true
+    )
       parse = parse_mediawiki(input, handlers:)
       yield(parse.ast) if block_given?
-      build_conversion(parse, renderer:, raise_on_error:)
+      build_conversion(parse, renderer:, raise_on_error:, normalize:)
     end
 
     # Convert input in the given format. Thin dispatcher over the
@@ -211,8 +237,17 @@ module Markbridge
     # @param format [Symbol] :discourse (only renderer currently shipped)
     # @param renderer [Renderers::Discourse::Renderer, nil]
     # @param raise_on_error [Boolean]
+    # @param normalize [Boolean, Normalizer] see {.bbcode_to_markdown}.
+    #   Normalization is idempotent, so re-rendering an already-normalized
+    #   {Parse} is a no-op.
     # @return [Conversion]
-    def render(parse_or_ast, format: :discourse, renderer: nil, raise_on_error: true)
+    def render(
+      parse_or_ast,
+      format: :discourse,
+      renderer: nil,
+      raise_on_error: true,
+      normalize: true
+    )
       raise ArgumentError, "unknown render format #{format.inspect}" unless format == :discourse
 
       parse =
@@ -228,7 +263,7 @@ module Markbridge
           raise ArgumentError, "expected Parse or AST::Node, got #{parse_or_ast.class}"
         end
 
-      build_conversion(parse, renderer:, raise_on_error:)
+      build_conversion(parse, renderer:, raise_on_error:, normalize:)
     end
 
     # Build a configured Discourse {Renderers::Discourse::Renderer}
@@ -241,8 +276,10 @@ module Markbridge
     #   library to start from. Defaults to a fresh {TagLibrary.default}.
     #   When supplied, it is +dup+'d before any +tags:+ / +unregister:+
     #   mutation, so the caller's library is left untouched.
-    # @param unregister [Array<Class>, nil] AST classes to drop from
-    #   the library so they fall through to +render_children+.
+    # @param unregister [Array<Class>, nil] AST classes whose binding to
+    #   drop from the library. A built-in class then renders as just its
+    #   children; a subclass of a bound class falls back to the nearest
+    #   ancestor's tag (see {Renderers::Discourse::TagLibrary#unregister}).
     # @param escaper [#escape, nil] when given, used as-is; +escape:+,
     #   +escape_hard_line_breaks:+, and +allow:+ are then ignored.
     # @param escape [Boolean] when +false+, the renderer is built with
@@ -297,13 +334,28 @@ module Markbridge
       }
     end
 
-    def build_conversion(parse, renderer:, raise_on_error:)
+    def build_conversion(parse, renderer:, raise_on_error:, normalize:)
+      parse = apply_normalization(parse, normalize)
       renderer ||= Renderers::Discourse::Renderer.new
       markdown, errors = render_through(renderer, parse.ast, raise_on_error:)
 
       Conversion.new(parsed: parse, markdown:, errors:)
     end
 
+    # Normalize +parse.ast+ in place (target-format nesting rules) and fold
+    # any report into +diagnostics[:normalization]+. Returns the +parse+ to
+    # render — a new one carrying the report when something changed, else
+    # the original unchanged.
+    def apply_normalization(parse, normalize)
+      return parse unless normalize
+
+      normalizer = normalize.is_a?(Normalizer) ? normalize : Normalizer.shared_default
+      report = normalizer.normalize(parse.ast)
+      return parse if report.empty?
+
+      parse.with(diagnostics: parse.diagnostics.merge(normalization: report))
+    end
+
     def build_escaper(escape:, escape_hard_line_breaks:, allow:)
       if escape == false
         if escape_hard_line_breaks || allow

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markbridge
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Discourse Team
@@ -58,6 +58,11 @@ files:
 - lib/markbridge/gem_loader.rb
 - lib/markbridge/html.rb
 - lib/markbridge/mediawiki.rb
+- lib/markbridge/normalizer.rb
+- lib/markbridge/normalizer/report.rb
+- lib/markbridge/normalizer/rule_set.rb
+- lib/markbridge/normalizer/text_projection.rb
+- lib/markbridge/normalizer/walker.rb
 - lib/markbridge/parse.rb
 - lib/markbridge/parsers/bbcode.rb
 - lib/markbridge/parsers/bbcode/closing_strategies/base.rb
@@ -98,6 +103,7 @@ files:
 - lib/markbridge/parsers/html.rb
 - lib/markbridge/parsers/html/handler_registry.rb
 - lib/markbridge/parsers/html/handlers/base_handler.rb
+- lib/markbridge/parsers/html/handlers/heading_handler.rb
 - lib/markbridge/parsers/html/handlers/image_handler.rb
 - lib/markbridge/parsers/html/handlers/list_handler.rb
 - lib/markbridge/parsers/html/handlers/list_item_handler.rb
@@ -132,6 +138,7 @@ files:
 - lib/markbridge/parsers/text_formatter/parser.rb
 - lib/markbridge/renderers/discourse.rb
 - lib/markbridge/renderers/discourse/builders/list_item_builder.rb
+- lib/markbridge/renderers/discourse/html_block_safety.rb
 - lib/markbridge/renderers/discourse/html_escaper.rb
 - lib/markbridge/renderers/discourse/identity_escaper.rb
 - lib/markbridge/renderers/discourse/markdown_escaper.rb
@@ -171,6 +178,7 @@ files:
 - lib/markbridge/renderers/discourse/tags/underline_tag.rb
 - lib/markbridge/renderers/discourse/tags/upload_tag.rb
 - lib/markbridge/renderers/discourse/tags/url_tag.rb
+- lib/markbridge/rspec.rb
 - lib/markbridge/textformatter.rb
 - lib/markbridge/version.rb
 homepage: https://github.com/discourse/markbridge