markbridge 0.4.3 → 0.5.0

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

@@ -4,21 +4,86 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering sized text
-        # Note: Discourse doesn't support inline size changes by default
-        # Renders as plain text with HTML comment noting the size was lost
+        # Tag for rendering sized text.
+        #
+        # Discourse core removes the style of a span. Only the
+        # discourse-bbcode plugin can show sizes, and it reads
+        # +[size=…]+ as a percentage, as phpBB 3.x writes it. So the tag
+        # needs to know two things: whether the site has the plugin, and
+        # how the values of the source forum map to percent. Until it
+        # knows the first, a size raises {UndecidedFeatureError}.
+        #
+        # - +bbcode: nil+ (the default): a size raises.
+        # - +bbcode: false+: the text only, as inline tokens that the
+        #   serializer joins with the neighbors.
+        # - +bbcode: true+: +[size=…]…[/size]+, with the value mapped
+        #   through +sizes:+. Without a mapping the value is taken as it
+        #   is. A value that is not a whole number from 1 to 999 after the
+        #   mapping raises ArgumentError; a mapping that returns nil drops
+        #   the size on purpose.
+        #
+        # Inside a link the text is written without BBCode in every case,
+        # Discourse doesn't render BBCode in the text of a link.
         class SizeTag < Tag
+          # A whole number from 1 to 999, the range the plugin lets through.
+          VALUE = /\A[1-9]\d{0,2}\z/
+          private_constant :VALUE
+
+          UNDECIDED =
+            "a [size] tag needs a decision: pass features: { bbcode: false } to " \
+              "Markbridge.discourse_renderer to write the text only, or " \
+              "features: { bbcode: true } with sizes: for the discourse-bbcode plugin"
+          private_constant :UNDECIDED
+
+          # @param bbcode [Boolean, nil] whether the site has discourse-bbcode
+          # @param sizes [Hash, #call, nil] the mapping from the source value
+          #   to percent. A Hash is read with +fetch+, so an unknown value
+          #   raises KeyError.
+          def initialize(bbcode: nil, sizes: nil)
+            @bbcode = bbcode
+            @sizes = sizes
+          end
+
           def render(element, interface)
-            child_context = interface.with_parent(element)
-            content = interface.render_children(element, context: child_context)
-
-            if element.size
-              # Render as HTML span with style - requires HTML to be enabled
-              # Alternative: just output the text without size
-              "<span style=\"font-size: #{element.size}px\">#{content}</span>"
-            else
-              content
-            end
+            context = interface.with_parent(element)
+            percent = bbcode_percent(element.size, interface)
+            return interface.render_tokens(element, context:) if percent.nil?
+
+            content = interface.render_children(element, context:)
+            # The style that the discourse-bbcode plugin lets through.
+            return %(<span style="font-size:#{percent}%">#{content}</span>) if interface.html_mode?
+
+            Paragraphs.wrap(content, "[size=#{percent}]", "[/size]")
+          end
+
+          private
+
+          # @return [String, nil] the percent to write, nil for the text only
+          def bbcode_percent(value, interface)
+            return if text_only?(value, interface)
+            raise UndecidedFeatureError, UNDECIDED if @bbcode.nil?
+
+            mapped = @sizes ? apply(@sizes, value) : value
+            return if mapped.nil?
+
+            text = mapped.to_s
+            return text if VALUE.match?(text)
+
+            raise ArgumentError,
+                  "size #{value.inspect} maps to #{mapped.inspect}, discourse-bbcode accepts a " \
+                    "whole number from 1 to 999 (percent); pass sizes: to map it, or to drop " \
+                    "it with nil"
+          end
+
+          def apply(mapping, value)
+            mapping.respond_to?(:call) ? mapping.call(value) : mapping.fetch(value)
+          end
+
+          # No value, the plugin decided against, or a link around it: the
+          # text is all there can be, and no decision changes that.
+          def text_only?(value, interface)
+            value.to_s.match?(/\A[[:space:]]*\z/) || @bbcode == false ||
+              interface.has_parent?(AST::Url) || interface.has_parent?(AST::Email)
           end
         end
       end

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

@@ -4,31 +4,89 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering spoilers
-        # Renders to Discourse BBCode spoiler format
+        # Renders a spoiler as the `[spoiler]…[/spoiler]` BBCode of the
+        # spoiler-alert plugin. Discourse never reads an attribute of the
+        # tag, so a title is written as text in front of the spoiler:
+        # `title: [spoiler]…[/spoiler]`.
+        #
+        # With +bbcode: false+, for a site without the plugin, the content
+        # is written as it is, so the hidden text shows.
         class SpoilerTag < Tag
+          # @param bbcode [Boolean] write the BBCode of the plugin
+          def initialize(bbcode: true)
+            @bbcode = bbcode
+          end
+
           def render(element, interface)
             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?
+            # A spoiler with nothing to hide gets no tags, like the
+            # serializer's markers: an empty [spoiler] shell would only
+            # add noise to the output.
+            return content unless content.match?(/[^[:space:]]/)
 
-            return render_html(element.title, content) if interface.html_mode?
+            title = title_text(element, interface)
+            # Discourse doesn't cook BBCode in the text of a link.
+            return "#{title}#{content}" if !@bbcode || inside_link?(interface)
+            return "#{title}#{render_html(content)}" if interface.html_mode?
 
-            if element.title
-              "[spoiler=#{element.title}]#{content}[/spoiler]"
-            else
-              "[spoiler]#{content}[/spoiler]"
-            end
+            # `[spoiler]:x` at the start of a line reads as a link
+            # reference definition, the backslash keeps the colon text.
+            content = "\\#{content}" if content.start_with?(":")
+            output = "#{title}[spoiler]#{content}[/spoiler]"
+            # A line that starts with `[spoiler]` and ends with `[/spoiler]`
+            # is one block spoiler to Discourse, whatever stands between, so
+            # two spoilers on it show their inner tags as text. A comment
+            # after the second one ends the line with something else.
+            output << Inline::Joins::BOUNDARY_COMMENT if after_spoiler?(element, interface)
+            output
           end
 
           private
 
-          def render_html(title, content)
-            summary = "<summary>#{title ? HtmlEscaper.escape(title) : "Spoiler"}</summary>"
-            "<details>#{summary}#{content}</details>"
+          # Whether a spoiler stands in front of +element+ on the same line,
+          # with anything inline between. A text that has something visible
+          # after its last newline starts the line, so the search ends
+          # there. A spoiler with a title starts its line with the title,
+          # not with `[spoiler]`, and is looked over like text.
+          def after_spoiler?(element, interface)
+            offset = -1
+            loop do
+              node = interface.sibling(element, offset:)
+              return false if node.nil?
+              return true if node.is_a?(AST::Spoiler) && !titled?(node)
+              return false if node.is_a?(AST::Text) && starts_line?(node.text)
+
+              offset -= 1
+            end
+          end
+
+          def starts_line?(text)
+            text.include?("\n") && text.rpartition("\n").last.match?(/[^[:space:]]/)
+          end
+
+          def titled?(element)
+            element.title.to_s.match?(/[^[:space:]]/)
+          end
+
+          # The title with a colon and a space after it, escaped like any
+          # text, or nil without a title.
+          def title_text(element, interface)
+            return unless titled?(element)
+
+            "#{interface.render_node(AST::Text.new(element.title.strip))}: "
+          end
+
+          # The inline form Discourse cooks the BBCode to. A <details>
+          # would be a block, which an HTML parser moves out of the
+          # emphasis around it.
+          def render_html(content)
+            %(<span class="spoiler">#{content}</span>)
+          end
+
+          def inside_link?(interface)
+            interface.has_parent?(AST::Url) || interface.has_parent?(AST::Email)
           end
         end
       end

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

@@ -4,14 +4,13 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering strikethrough text
+        # Strikethrough. The serializer writes the tildes, or an s tag
+        # where a tilde at the edge of the content would make the marker
+        # three tildes long.
         class StrikethroughTag < Tag
           def render(element, interface)
-            child_context = interface.with_parent(element)
-            content = interface.render_children(element, context: child_context)
-            return "<s>#{content}</s>" if interface.html_mode?
-
-            interface.wrap_inline(content, "~~")
+            tokens = interface.render_tokens(element, context: interface.with_parent(element))
+            tokens.unshift(Inline::Tokens.open(:s)) << Inline::Tokens.close(:s)
           end
         end
       end

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

@@ -4,13 +4,19 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering subscript text
-        # Renders to HTML <sub> tag
+        # Tag for rendering subscript text as the HTML tag, which Markdown
+        # has no form for. The tags are inline tokens so that the
+        # serializer sees them as neighbors: a newline right after the
+        # opening tag would leave it alone on its line, where it opens an
+        # HTML block.
         class SubscriptTag < Tag
+          OPEN = Inline::Tokens.html("<sub>")
+          CLOSE = Inline::Tokens.html("</sub>")
+          private_constant :OPEN, :CLOSE
+
           def render(element, interface)
-            child_context = interface.with_parent(element)
-            content = interface.render_children(element, context: child_context)
-            "<sub>#{content}</sub>"
+            tokens = interface.render_tokens(element, context: interface.with_parent(element))
+            tokens.unshift(OPEN) << CLOSE
           end
         end
       end

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

@@ -4,13 +4,19 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering superscript text
-        # Renders to HTML <sup> tag
+        # Tag for rendering superscript text as the HTML tag, which Markdown
+        # has no form for. The tags are inline tokens so that the
+        # serializer sees them as neighbors: a newline right after the
+        # opening tag would leave it alone on its line, where it opens an
+        # HTML block.
         class SuperscriptTag < Tag
+          OPEN = Inline::Tokens.html("<sup>")
+          CLOSE = Inline::Tokens.html("</sup>")
+          private_constant :OPEN, :CLOSE
+
           def render(element, interface)
-            child_context = interface.with_parent(element)
-            content = interface.render_children(element, context: child_context)
-            "<sup>#{content}</sup>"
+            tokens = interface.render_tokens(element, context: interface.with_parent(element))
+            tokens.unshift(OPEN) << CLOSE
           end
         end
       end

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

@@ -6,19 +6,37 @@ module Markbridge
       module Tags
         # Tag for rendering tables as Markdown pipe tables with HTML fallback
         class TableTag < Tag
+          # Nodes a Markdown table cell cannot hold: they render with a
+          # marker that a cell reads as text. A block of code is not here,
+          # its fence lines make the cell content more than one line.
+          BLOCK_NODES = [
+            AST::List,
+            AST::Quote,
+            AST::Heading,
+            AST::HorizontalRule,
+            AST::Table,
+            AST::Details,
+            AST::Align,
+            AST::Poll,
+            AST::Event,
+          ].freeze
+          private_constant :BLOCK_NODES
+
           def render(element, interface)
             child_context = interface.with_parent(element)
             rows_data = extract_rows(element, interface, child_context)
 
             return "" if rows_data.empty?
 
-            if markdown_compatible?(rows_data, interface)
+            if markdown_compatible?(element, rows_data, interface)
               render_markdown(rows_data)
             else
               # Re-render cells in html_mode so inline Markdown like **bold** becomes
               # <strong>bold</strong>; CommonMark would not parse Markdown inside an HTML block.
               html_rows = extract_rows(element, interface, child_context.with_html_mode(true))
-              render_html(html_rows)
+              html = render_html(html_rows)
+              # Inside an HTML block a blank line would end the block.
+              interface.html_mode? ? html : "\n\n#{html}\n\n"
             end
           end
 
@@ -45,9 +63,15 @@ module Markbridge
             end
           end
 
-          # Check if the table can be rendered as Markdown
-          def markdown_compatible?(rows_data, interface)
+          # Check if the table can be rendered as Markdown: not nested in a
+          # table, no block in a cell, the header row (when there is one)
+          # first, every row as wide as the first, no cell on two lines.
+          def markdown_compatible?(element, rows_data, interface)
             return false if interface.has_parent?(AST::Table)
+            return false if block_in_cell?(element)
+
+            header_idx = rows_data.index { |r| r[:cells].all? { |c| c[:header] } }
+            return false if header_idx&.positive?
 
             cell_count = rows_data.first[:cells].length
             rows_data.all? do |row|
@@ -56,18 +80,15 @@ module Markbridge
             end
           end
 
-          # Render as Markdown pipe table
+          def block_in_cell?(element)
+            element.descendants.any? { |node| BLOCK_NODES.include?(node.class) }
+          end
+
+          # Render as Markdown pipe table. The first row is the header
+          # row: markdown_compatible? lets no other header row through.
           def render_markdown(rows_data)
-            header_idx = rows_data.index { |r| r[:cells].all? { |c| c[:header] } }
-            header_row = header_idx ? rows_data[header_idx] : rows_data.first
-            data_rows =
-              (
-                if header_idx
-                  rows_data[0...header_idx] + rows_data[(header_idx + 1)..]
-                else
-                  rows_data[1..]
-                end
-              )
+            header_row = rows_data.first
+            data_rows = rows_data[1..]
 
             col_count = header_row[:cells].length
             lines = []
@@ -84,23 +105,22 @@ module Markbridge
             "| #{cells.map { |c| c[:content] }.join(" | ")} |"
           end
 
-          # Render as HTML table
+          # Render as HTML table. The header rows at the top go into a
+          # <thead>, the rest into a <tbody>; the rows keep their order, a
+          # header row further down stays where it is.
           def render_html(rows_data)
-            has_header = rows_data.any? { |r| r[:cells].any? { |c| c[:header] } }
+            header_count =
+              rows_data.index { |r| !r[:cells].all? { |c| c[:header] } } || rows_data.length
             lines = ["<table>"]
 
-            if has_header
-              header_rows, body_rows = rows_data.partition { |r| r[:cells].all? { |c| c[:header] } }
+            if header_count.positive?
+              lines << "<thead>"
+              rows_data[0...header_count].each { |row| lines << html_row(row) }
+              lines << "</thead>"
 
-              unless header_rows.empty?
-                lines << "<thead>"
-                header_rows.each { |row| lines << html_row(row) }
-                lines << "</thead>"
-              end
-
-              unless body_rows.empty?
+              if header_count < rows_data.length
                 lines << "<tbody>"
-                body_rows.each { |row| lines << html_row(row) }
+                rows_data[header_count..].each { |row| lines << html_row(row) }
                 lines << "</tbody>"
               end
             else
@@ -108,7 +128,7 @@ module Markbridge
             end
 
             lines << "</table>"
-            "\n\n#{lines.join("\n")}\n\n"
+            lines.join("\n")
           end
 
           # Render a single HTML table row

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

@@ -14,17 +14,10 @@ module Markbridge
         # literally. Drop the wrapper when rendering under a link ancestor.
         class UnderlineTag < Tag
           def render(element, interface)
-            child_context = interface.with_parent(element)
-            content = interface.render_children(element, context: child_context)
-            return content unless content.match?(/[^[:space:]]/)
+            tokens = interface.render_tokens(element, context: interface.with_parent(element))
+            return tokens if inside_link?(interface)
 
-            if interface.html_mode?
-              %(<span class="bbcode-u">#{content}</span>)
-            elsif inside_link?(interface)
-              content
-            else
-              "[u]#{content}[/u]"
-            end
+            tokens.unshift(Inline::Tokens.open(:u)) << Inline::Tokens.close(:u)
           end
 
           private

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

@@ -11,9 +11,15 @@ module Markbridge
         # to render uploads as placeholders or resolve upload:// URLs.
         #
         # @example Custom renderer with placeholder
+        #   # An upload is inline, so the placeholder token says what the
+        #   # importer will put there (see "Placeholders" in the migration
+        #   # guide): the renderer joins it with its neighbors like that.
+        #   Tokens = Markbridge::Renderers::Discourse::Inline::Tokens
+        #
         #   class MyUploadTag < Markbridge::Renderers::Discourse::Tags::UploadTag
         #     def render(element, interface)
-        #       "<<UPLOAD:#{element.sha1}>>"
+        #       like = "![image](upload://#{element.sha1})"
+        #       [Tokens.placeholder("<<UPLOAD:#{element.sha1}>>", like:)]
         #     end
         #   end
         #
@@ -29,76 +35,117 @@ module Markbridge
         #     end
         #   end
         class UploadTag < Tag
+          # An upload is always written in one of Discourse's Markdown
+          # forms, through RenderingInterface#markdown_island: Discourse
+          # reads the dimensions and the `attachment` marker only from the
+          # Markdown, and its sanitizer drops the `upload://` href of a
+          # raw HTML link.
           def render(element, interface)
-            return build_upload_html(element) if interface.html_mode?
-
-            # Return raw Markdown if available, otherwise reconstruct
-            return element.raw if element.raw
+            return name_in_link(element, interface) if attachment_in_link?(element, interface)
 
-            build_upload_markdown(element)
+            interface.markdown_island(build_upload_markdown(element, interface), block: false)
           end
 
           private
 
-          def build_upload_markdown(element)
+          # A file attachment is a link, and a link cannot hold a link:
+          # Markdown reads the inner one and leaves the brackets of the
+          # outer one as text. Like the normalizer unwraps a link inside a
+          # link, the attachment inside a link label is its file name. An
+          # image inside a link label is fine.
+          def attachment_in_link?(element, interface)
+            element.type == :attachment && element.raw.nil? &&
+              (interface.has_parent?(AST::Url) || interface.has_parent?(AST::Email))
+          end
+
+          # The file name and the size as text, in the mode of the link
+          # around it: Markdown in a label, HTML inside an HTML block. The
+          # link is on the parent chain already, which is all the text
+          # needs for the escaping of a label.
+          def name_in_link(element, interface)
+            name = interface.render_node(AST::Text.new(element.filename || "attachment"))
+            size_part = " (#{element.size})" if element.size
+
+            "#{name}#{size_part}"
+          end
+
+          def build_upload_markdown(element, interface)
+            return raw(element, interface) if element.raw
+
             if element.type == :image
-              build_image_markdown(element)
+              build_image_markdown(element, interface)
             else
-              build_attachment_markdown(element)
+              build_attachment_markdown(element, interface)
             end
           end
 
-          def build_image_markdown(element)
-            alt = build_alt(element)
-            url = build_upload_url(element)
+          # The raw Markdown of the source, with the pipes escaped in a
+          # table cell. One that is escaped already stays as it is.
+          def raw(element, interface)
+            return element.raw unless markdown_cell?(interface)
+
+            element.raw.gsub(/(?<!\\)\|/, "\\\\|")
+          end
+
+          # A `|` ends the cell of a Markdown table. Discourse keeps the
+          # pipes inside a link or an image since August 2026, plain
+          # markdown-it and older Discourse versions do not, and `\|` works
+          # in all of them: Discourse reads the dimensions and the attachment
+          # marker all the same.
+          def pipe(interface)
+            markdown_cell?(interface) ? "\\|" : "|"
+          end
+
+          # The cell of a table written in Markdown. Inside a table written
+          # as HTML the island is a paragraph of its own, where a pipe ends
+          # nothing.
+          def markdown_cell?(interface)
+            interface.has_parent?(AST::TableCell) && !interface.html_mode?
+          end
+
+          def build_image_markdown(element, interface)
+            alt = build_alt(element, interface)
+            url = destination(element)
 
             "![#{alt}](#{url})"
           end
 
-          def build_attachment_markdown(element)
-            filename = element.filename || "attachment"
-            url = build_upload_url(element)
+          def build_attachment_markdown(element, interface)
+            filename = label(element.filename || "attachment", element, interface)
+            url = destination(element)
             size_part = " (#{element.size})" if element.size
 
-            "[#{filename}|attachment](#{url})#{size_part}"
+            "[#{filename}#{pipe(interface)}attachment](#{url})#{size_part}"
           end
 
-          def build_alt(element)
+          # The alt text is escaped for a link label, the dimensions are
+          # ours and stay as they are.
+          def build_alt(element, interface)
             parts = []
-            parts << element.alt if element.alt
+            parts << label(element.alt, element, interface) if element.alt
             parts << element.dimensions if element.dimensions
 
-            parts.join("|")
+            parts.join(pipe(interface))
           end
 
-          def build_upload_url(element)
-            filename = element.filename || element.sha1
-            "upload://#{filename}"
+          # Text inside the brackets goes through the renderer like any
+          # text, so a `]` or Markdown in it is escaped. The label is
+          # Markdown inside an HTML table as well, so html_mode is off for
+          # it there.
+          def label(text, element, interface)
+            context = interface.with_html_mode(false).with_parent(element)
+            interface.render_node(AST::Text.new(text), context:)
           end
 
-          # html_mode reconstructs from the AST fields rather than reusing
-          # element.raw — raw is Markdown, which CommonMark passes through
-          # unchanged inside an HTML block (so the user would see the
-          # literal "![…](upload://…)" string instead of an image).
-          def build_upload_html(element)
-            if element.type == :image
-              build_image_html(element)
-            else
-              build_attachment_html(element)
-            end
-          end
-
-          def build_image_html(element)
-            src = HtmlEscaper.escape(build_upload_url(element))
-            alt = HtmlEscaper.escape(element.alt)
-            %(<img src="#{src}" alt="#{alt}">)
+          # The destination gets the same treatment as the one of a link:
+          # a file name with a space or a parenthesis would end it early.
+          def destination(element)
+            LinkDestination.escape(build_upload_url(element))
           end
 
-          def build_attachment_html(element)
-            href = HtmlEscaper.escape(build_upload_url(element))
-            filename = HtmlEscaper.escape(element.filename || "attachment")
-            size_part = " (#{HtmlEscaper.escape(element.size)})" if element.size
-            %(<a href="#{href}">#{filename}</a>#{size_part})
+          def build_upload_url(element)
+            filename = element.filename || element.sha1
+            "upload://#{filename}"
           end
         end
       end