markbridge 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bb47b7959df5ce79179a7edbe11ffff2126d6769ed70af335fa12f62467a7f9
-  data.tar.gz: e959d0e4c9e9f05abf66d2c57e79ac4ffa123b88304addcd2b2cfc18a8d4734d
+  metadata.gz: fa422d5e0a05eee7f32524e42823d02a552111132025fd9ede1fc5045a79412e
+  data.tar.gz: cc7af6319a7c9dde74a764dc9edaab186ef2cca92bc6fabd842a147216adaec0
 SHA512:
-  metadata.gz: 49ee985843ccb441d18b680a8e9aa3983f8f3ab37d0831462a71959c356d7cd993495bc5d4b777d3aa5ec58ace53d995d9b57aacda198d6ee95f2d11b97038cc
-  data.tar.gz: 9a6551d169ac4b2ee9211a7ee460ac6247cc5f9c00ef8fe1fced7139cd1836959c03110da020a7b37f23b735ca348070bb378da1bfc8083246a98718c0116d67
+  metadata.gz: 2eb57814326cf0fbaf2e356290d962a0a9e8bf2b9c38aa4e41ad7526d9494574162fc5384473b15c833b4e34bd7f322bf464098337bf9d535662f615590c19e4
+  data.tar.gz: d4fc22c47cc54ab91a0d29b140bf69317c5c10aae3358758b0036b213f96ddca9318d723016854819a8a80dcf03ea5f66180eaccc8df2d550d06ab69b8f25a87

data/lib/markbridge/renderers/discourse/builders/list_item_builder.rb

@@ -4,78 +4,30 @@ module Markbridge
   module Renderers
     module Discourse
       module Builders
-        # Builder for list item formatting
-        # Handles complex multi-line formatting with proper indentation
-        # and preservation of blank lines and nested list items
+        # Formats one list item: the marker goes in front of the first
+        # line, every other line moves right by the width of the marker.
+        # The content is indented as one unit, so nested lists, code
+        # fences and HTML blocks inside it keep the shape they already
+        # have. Blank lines stay blank; the postprocessor clears
+        # whitespace-only lines anyway.
         class ListItemBuilder
-          # Build a formatted list item string
           # @param content [String] the item content
           # @param marker [String] the list marker ("- " or "1. ")
-          # @param indent [String] the indentation string
           # @return [String]
-          def build(content, marker:, indent:)
+          # @example
+          #   builder.build("a\nb", marker: "- ") # => "- a\n  b\n"
+          def build(content, marker:)
             lines = content.split("\n")
-            first_line = "#{indent}#{marker}#{lines.first}"
-
+            first_line = "#{marker}#{lines.first}"
             return "#{first_line}\n" if lines.size < 2
 
-            format_multiline(lines, first_line, indent)
-          end
-
-          private
-
-          # Format multi-line content with proper indentation
-          # @param lines [Array<String>] content lines
-          # @param first_line [String] the formatted first line
-          # @param indent [String] base indentation
-          # @return [String]
-          def format_multiline(lines, first_line, indent)
-            continuation_indent = "#{indent}  "
-            continuation_lines = lines[1..]
-
-            rest =
-              continuation_lines.each_with_index.filter_map do |line, idx|
-                format_continuation_line(line, idx, continuation_lines, continuation_indent)
-              end
-
+            indent = " " * marker.length
+            # An empty line maps to nil, and join turns that back into
+            # an empty line. Indenting it instead would leave a line
+            # with nothing but spaces on it.
+            rest = lines[1..].map { |line| "#{indent}#{line}" unless line.empty? }
             "#{([first_line] + rest).join("\n")}\n"
           end
-
-          # Format a single continuation line
-          # @param line [String] the line to format
-          # @param idx [Integer] index in continuation_lines array
-          # @param continuation_lines [Array<String>] all continuation lines
-          # @param continuation_indent [String] indent for continuation
-          # @return [String, nil] formatted line or nil to skip
-          def format_continuation_line(line, idx, continuation_lines, continuation_indent)
-            # Handle empty lines
-            return handle_empty_line(idx, continuation_lines, continuation_indent) if line.empty?
-
-            # Check if line is already a list item (has indentation + marker)
-            if line.match?(/\A\s*(?:-|\d+\.)\s/)
-              # Already a list item - don't add extra indentation
-              line
-            else
-              # Regular continuation line - add indentation
-              "#{continuation_indent}#{line}"
-            end
-          end
-
-          # Handle empty lines in continuation. Caller (format_continuation_line)
-          # only invokes this when `line.empty?`, and `content.split("\n")`
-          # trims trailing empty strings, so the LAST continuation line is
-          # never empty — `idx + 1` is always in bounds when we get here.
-          # @param idx [Integer] index in continuation_lines
-          # @param continuation_lines [Array<String>] all continuation lines
-          # @param continuation_indent [String] indent for continuation
-          # @return [String, nil] formatted line or nil to skip
-          def handle_empty_line(idx, continuation_lines, continuation_indent)
-            # Skip empty lines that come before nested list items (structural blanks)
-            return nil if continuation_lines[idx + 1].match?(/\A\s*(?:-|\d+\.)\s/)
-
-            # Preserve empty lines within text content (paragraph breaks) with indentation
-            continuation_indent
-          end
         end
       end
     end

data/lib/markbridge/renderers/discourse/html_block.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Renderers
+    module Discourse
+      # The one place that knows how CommonMark HTML blocks (spec §4.6)
+      # and Markdown meet in the rendered output.
+      #
+      # Inside an HTML block the content passes through as raw HTML.
+      # Markdown is parsed again only across blank lines. A tag that
+      # renders into such a block therefore picks one of two forms:
+      #
+      # 1. raw HTML — an HTML equivalent of the tag's Markdown, spliced
+      #    into the block as it is;
+      # 2. a Markdown island — the tag's normal Markdown surrounded by
+      #    blank lines, which end the block and start it again:
+      #
+      #        <div align="center">
+      #
+      #        [a link](https://example.com)
+      #
+      #        </div>
+      module HtmlBlock
+        # Tag names that start a type 6 HTML block when a line begins
+        # with `<name` or `</name` followed by a space, a tab, `>`, `/>`
+        # or the end of the line.
+        BLOCK_TAGS = %w[
+          address
+          article
+          aside
+          base
+          basefont
+          blockquote
+          body
+          caption
+          center
+          col
+          colgroup
+          dd
+          details
+          dialog
+          dir
+          div
+          dl
+          dt
+          fieldset
+          figcaption
+          figure
+          footer
+          form
+          frame
+          frameset
+          h1
+          h2
+          h3
+          h4
+          h5
+          h6
+          head
+          header
+          hr
+          html
+          iframe
+          legend
+          li
+          link
+          main
+          menu
+          menuitem
+          nav
+          noframes
+          ol
+          optgroup
+          option
+          p
+          param
+          search
+          section
+          summary
+          table
+          tbody
+          td
+          tfoot
+          th
+          thead
+          title
+          tr
+          track
+          ul
+        ].freeze
+
+        # The spec allows up to three leading spaces. We match any amount
+        # of leading whitespace instead, because the lines this runs on
+        # are item content that the list builder has not indented yet.
+        OPENER = %r{\A[ \t]*</?(?:#{Regexp.union(BLOCK_TAGS).source})(?:[ \t>]|/>|\z)}i
+
+        # Markdown sigils that would surface as literal text inside an
+        # HTML block: emphasis (`*`, `_`, `~`) and link middles (`](`).
+        MARKDOWN_SIGILS = /[*_~]|\]\(/
+
+        # Blank lines at the start or at the end of a fragment. The first
+        # content line keeps its own indentation, e.g. a nested `  - a`.
+        BLANK_EDGES = /\A(?:[ \t]*\n)+|(?:\n[ \t]*)+\z/
+
+        private_constant :BLOCK_TAGS, :OPENER, :MARKDOWN_SIGILS, :BLANK_EDGES
+
+        # Whether +line+ starts an HTML block. A closing tag such as
+        # `</div>` starts one too. The block runs until the next blank
+        # line.
+        # @param line [String]
+        # @return [Boolean]
+        def self.opens?(line)
+          OPENER.match?(line)
+        end
+
+        # Wrap Markdown so that CommonMark parses it even inside an HTML
+        # block. Blank lines that the fragment already has at its edges
+        # are folded into the wrap.
+        # @param markdown [String]
+        # @return [String]
+        # @example
+        #   HtmlBlock.island("- a\n") # => "\n\n- a\n\n"
+        def self.island(markdown)
+          "\n\n#{markdown.gsub(BLANK_EDGES, "")}\n\n"
+        end
+
+        # Whether a fragment can be spliced into an HTML block: raw HTML
+        # or plain text without Markdown sigils, or an island.
+        #
+        # Used by the html_mode contract check that ships in
+        # +markbridge/rspec+ and by this repo's own contract spec.
+        # @param output [String] a tag's html_mode render result
+        # @return [Boolean]
+        def self.safe?(output)
+          return true if output.start_with?("\n\n") && output.end_with?("\n\n")
+
+          !output.match?(MARKDOWN_SIGILS)
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/renderers/discourse/renderer.rb

@@ -87,19 +87,38 @@ module Markbridge
         end
 
         # Render all children of a node
+        #
+        # With a block, the block runs at every join point, right before
+        # a non-empty child output is appended. It receives the buffer
+        # built so far and the child about to be rendered into it, and
+        # may change the buffer in place. A tag uses this to adjust the
+        # text in front of a specific child without iterating the
+        # children itself, which would lose the emphasis-boundary rule
+        # below.
+        #
         # @param node [AST::Element]
         # @param context [RenderContext] rendering context
+        # @yieldparam result [String] the buffer built so far
+        # @yieldparam child [AST::Node] the child about to be appended
         # @return [String]
+        # @example Attach a nested list directly to the text in front of it
+        #   interface.render_children(item, context:) do |buffer, child|
+        #     buffer.rstrip! if child.is_a?(AST::List)
+        #   end
         def render_children(node, context:)
           result = +""
           node.children.each do |child|
             part = render(child, context:)
             next if part.empty?
 
+            yield(result, child) if block_given?
+
             # Integer-byte check avoids allocating substrings for the
             # per-child adjacency probe. EMPHASIS_DELIMITER_BYTES.include?
-            # over a 4-element Set is O(1).
-            if !result.empty? && (last_byte = result.getbyte(-1)) == part.getbyte(0) &&
+            # over a 4-element Set is O(1). On an empty buffer getbyte
+            # returns nil, which matches no byte of a non-empty part, so
+            # the first child needs no extra guard.
+            if (last_byte = result.getbyte(-1)) == part.getbyte(0) &&
                  EMPHASIS_DELIMITER_BYTES.include?(last_byte)
               result << EMPHASIS_BOUNDARY
             end
@@ -168,7 +187,7 @@ module Markbridge
         # parses the content as Markdown before the closing tags reopen another
         # HTML block.
         def render_markdown_text(node, context)
-          context.html_mode? ? "\n\n#{node.text}\n\n" : node.text
+          context.html_mode? ? HtmlBlock.island(node.text) : node.text
         end
 
         def render_text(node, context)

data/lib/markbridge/renderers/discourse/rendering_interface.rb

@@ -26,8 +26,10 @@ module Markbridge
           @renderer.render_default(node, context:)
         end
 
-        def render_children(element, context: @context)
-          @renderer.render_children(element, context:)
+        # An optional block runs at every join point, before a non-empty
+        # child output is appended — see Renderer#render_children.
+        def render_children(element, context: @context, &block)
+          @renderer.render_children(element, context:, &block)
         end
 
         # Context operations

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

@@ -20,10 +20,30 @@ module Markbridge
 
             return content unless ALLOWED_ALIGNMENTS.include?(element.alignment)
 
-            wrapper = %(<div align="#{element.alignment}">#{content}</div>)
-            # Skip the blank-line bracketing in html_mode: a blank line would
-            # terminate the surrounding HTML block (e.g. an enclosing <table>).
-            interface.html_mode? ? wrapper : "\n\n#{wrapper}\n\n"
+            return html_block_form(element, content) if interface.html_mode?
+
+            # Keeps consecutive aligned blocks from merging.
+            "\n\n#{markdown_island_form(element, content)}\n\n"
+          end
+
+          private
+
+          # Children already render as raw HTML here, and a blank line
+          # would terminate the enclosing block (e.g. a <table>).
+          def html_block_form(element, content)
+            %(<div align="#{element.alignment}">#{content}</div>)
+          end
+
+          # A `<div>` opens an HTML block (CommonMark §4.6), and Markdown
+          # inside one is only parsed across blank lines. Without them a
+          # link in the content shows up as its own source text. The blank
+          # lines do mean CommonMark wraps the content in a `<p>`, so
+          # inline content picks up a paragraph margin.
+          def markdown_island_form(element, content)
+            open_tag = %(<div align="#{element.alignment}">)
+            return "#{open_tag}</div>" if content.match?(/\A\s*\z/)
+
+            "#{open_tag}#{HtmlBlock.island(content)}</div>"
           end
         end
       end

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

@@ -4,7 +4,13 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering list items
+        # Tag for rendering list items.
+        #
+        # An item does not indent itself. It renders its content at
+        # column zero and hands it to the builder, which moves the whole
+        # content right by the width of the marker. A nested list then
+        # lands at the content column of the item that holds it, whatever
+        # the nesting depth is.
         class ListItemTag < Tag
           def initialize
             @builder = Builders::ListItemBuilder.new
@@ -12,50 +18,49 @@ module Markbridge
 
           def render(element, interface)
             child_context = interface.with_parent(element)
-            content = interface.render_children(element, context: child_context).strip
-            return "" if content.empty?
+            return render_html(element, interface, child_context) if interface.html_mode?
 
-            return "<li>#{content}</li>" if interface.html_mode?
+            content = render_content(element, interface, child_context)
+            return "" if content.empty?
 
             parent_list = interface.find_parent(AST::List)
-            @builder.build(
-              content,
-              marker: determine_marker(parent_list),
-              indent: calculate_indent(interface),
-            )
+            @builder.build(content, marker: determine_marker(parent_list))
           end
 
           private
 
-          # @param parent_list [AST::List, nil]
           # @return [String]
-          def determine_marker(parent_list)
-            parent_list&.ordered? ? "1. " : "- "
+          def render_html(element, interface, child_context)
+            content = interface.render_children(element, context: child_context).strip
+            content.empty? ? "" : "<li>#{content}</li>"
           end
 
-          # Each ancestor List (excluding the direct parent) contributes
-          # indentation matching its own marker width:
-          # ordered = "   " (3 chars for "1. "), unordered = "  " (2 chars for "- ").
-          # @param interface [RenderingInterface]
+          # A nested list is attached directly to the content in front of
+          # it. A blank line there would make the whole list loose, and
+          # CommonMark then wraps every item in a <p>. Blank lines inside
+          # the output of a child are never touched.
           # @return [String]
-          def calculate_indent(interface)
-            list_count = interface.count_parents(AST::List)
-            # Top-level list — no ancestor lists contribute indent. The
-            # common case; short-circuit before any array allocations.
-            return "" if list_count <= 1
+          def render_content(element, interface, child_context)
+            content =
+              interface.render_children(element, context: child_context) do |buffer, child|
+                tighten(buffer) if child.is_a?(AST::List)
+              end
+            content.strip
+          end
+
+          # Drops the blank lines in front of a nested list, but keeps one
+          # when the line before it opens an HTML block (for example a
+          # `</table>`), because only a blank line ends such a block.
+          def tighten(buffer)
+            buffer.rstrip!
+            last_line = buffer[(buffer.rindex("\n") || -1) + 1..]
+            buffer << "\n" if HtmlBlock.opens?(last_line)
+          end
 
-            indent = +""
-            found = 0
-            interface.context.parents.each do |parent|
-              next unless parent.instance_of?(AST::List)
-              found += 1
-              # The immediate parent List is the LAST one in parents; its
-              # marker width is already accounted for by the item's own
-              # marker, so it doesn't contribute to indent.
-              break if found == list_count
-              indent << (parent.ordered? ? "   " : "  ")
-            end
-            indent
+          # @param parent_list [AST::List, nil]
+          # @return [String]
+          def determine_marker(parent_list)
+            parent_list&.ordered? ? "1. " : "- "
           end
         end
       end

data/lib/markbridge/renderers/discourse.rb

@@ -7,7 +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/html_block"
 require_relative "discourse/postprocessor"
 
 # Builders

data/lib/markbridge/rspec.rb

@@ -39,7 +39,7 @@ RSpec.shared_examples "an html_mode safe tag" do
   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),
+    expect(Markbridge::Renderers::Discourse::HtmlBlock.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

data/lib/markbridge/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markbridge
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Discourse Team
@@ -138,7 +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_block.rb
 - lib/markbridge/renderers/discourse/html_escaper.rb
 - lib/markbridge/renderers/discourse/identity_escaper.rb
 - lib/markbridge/renderers/discourse/markdown_escaper.rb

data/lib/markbridge/renderers/discourse/html_block_safety.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Markbridge
-  module Renderers
-    module Discourse
-      # Decides whether a rendered fragment is safe to splice into a
-      # CommonMark HTML block (spec §4.6). Inside such a block the
-      # content passes through as raw HTML; Markdown is only parsed
-      # again across blank lines. Safe output is therefore: a raw HTML
-      # or plain-text fragment without Markdown sigils, or a
-      # +\n\n…\n\n+ wrap — a deliberate Markdown island.
-      #
-      # Used by the html_mode contract check that ships in
-      # +markbridge/rspec+ and by this repo's own contract spec.
-      module HtmlBlockSafety
-        # Markdown sigils that would surface as literal text inside an
-        # HTML block: emphasis (`*`, `_`, `~`) and link middles (`](`).
-        MARKDOWN_SIGILS = /[*_~]|\]\(/
-        private_constant :MARKDOWN_SIGILS
-
-        # @param output [String] a tag's html_mode render result
-        # @return [Boolean]
-        def self.safe?(output)
-          return true if output.start_with?("\n\n") && output.end_with?("\n\n")
-
-          !output.match?(MARKDOWN_SIGILS)
-        end
-      end
-    end
-  end
-end