markbridge 0.4.3 → 0.5.0

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

@@ -4,27 +4,49 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Placeholder tag for rendering events.
+        # Renders {AST::Event} as the +[event]+ BBCode of the discourse-events
+        # plugin: the raw BBCode of the source when the parser kept it,
+        # otherwise the BBCode built from the attributes.
         #
-        # This is a STUB implementation that outputs the original raw BBCode.
-        # Applications using Markbridge should provide their own custom tag
-        # to render events as placeholders or convert them to another format.
+        # With +bbcode: false+, for a site without the plugin, the event is
+        # a paragraph with the name and the dates, so the reader still sees
+        # it.
         #
-        # @example Custom renderer with placeholder
+        # The BBCode has no HTML form, so it goes through
+        # RenderingInterface#markdown_island: a block with blank lines
+        # around it, and a Markdown island in a `<div>` inside an HTML
+        # table. A placeholder for an event is written the same way (see
+        # "Placeholders" in the migration guide).
+        #
+        # @example A placeholder for the importer
         #   class MyEventTag < Markbridge::Renderers::Discourse::Tags::EventTag
         #     def render(element, interface)
         #       id = register_event(element)
-        #       "<<EVENT:#{id}>>"
+        #       interface.markdown_island("<<EVENT:#{id}>>", block: true)
         #     end
         #   end
         class EventTag < Tag
-          def render(element, _interface)
-            body = element.raw || build_event_bbcode(element)
-            "\n\n#{body}\n\n"
+          # @param bbcode [Boolean] write the BBCode of the plugin
+          def initialize(bbcode: true)
+            @bbcode = bbcode
+          end
+
+          def render(element, interface)
+            return without_plugin(element, interface) unless @bbcode
+
+            interface.markdown_island(element.raw || build_event_bbcode(element), block: true)
           end
 
           private
 
+          def without_plugin(element, interface)
+            dates = [element.starts_at, element.ends_at].map(&:to_s).reject(&:empty?).join(" to ")
+            text = [element.name.to_s, dates].reject(&:empty?).join(", ")
+            return "" if text.empty?
+
+            interface.render_node(AST::Paragraph.new << AST::Text.new(text))
+          end
+
           def build_event_bbcode(element)
             attrs = build_attributes(element)
             "[event#{attrs}]\n[/event]"

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

@@ -5,6 +5,17 @@ module Markbridge
     module Discourse
       module Tags
         class HeadingTag < Tag
+          # A run of # at the end of an ATX heading, after whitespace, is
+          # the optional closing sequence and disappears when cooked. The
+          # space after the prefix counts, so a run that is the whole
+          # content is one too.
+          CLOSING_SEQUENCE = /(?:\A|(?<=[ \t]))#+[ \t]*\z/
+          # A heading is one line. A newline in its content, from a text
+          # node, is a soft break and becomes a space; LineBreakTag writes
+          # a hard break in a heading as <br>.
+          LINE_BREAK = /[ \t]*\n[ \t]*/
+          private_constant :CLOSING_SEQUENCE, :LINE_BREAK
+
           def render(element, interface)
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
@@ -16,7 +27,15 @@ module Markbridge
 
             prefix = "#" * element.level
 
-            "\n\n#{prefix} #{content}\n\n"
+            "\n\n#{prefix} #{keep_trailing_hashes(content.gsub(LINE_BREAK, " "))}\n\n"
+          end
+
+          private
+
+          # A backslash in front of the run keeps it as text. The escaper
+          # does not do this, it only knows about # at the start of a line.
+          def keep_trailing_hashes(content)
+            content.sub(CLOSING_SEQUENCE) { |run| "\\#{run}" }
           end
         end
       end

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

@@ -7,7 +7,18 @@ module Markbridge
         # Tag for rendering horizontal rules
         class HorizontalRuleTag < Tag
           def render(_element, interface)
-            interface.html_mode? ? "<hr>" : "\n\n---\n\n"
+            return "<hr>" if interface.html_mode?
+
+            list = interface.find_parent(AST::List)
+            return "\n\n---\n\n" unless list
+
+            # `- ---` is a thematic break that ends the list, because the
+            # marker and the dashes together are one run of dashes and
+            # spaces. `- * * *` is a list item that holds a thematic break
+            # (CommonMark example 61), so inside a list item the rule is
+            # written with the character the list's marker does not use;
+            # `* * * *` would be the rule alone again.
+            interface.list_marker(list)&.start_with?("*") ? "\n\n- - -\n\n" : "\n\n* * *\n\n"
           end
         end
       end

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

@@ -4,34 +4,20 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering images
-        # Renders to Markdown image syntax with optional Discourse sizing
+        # Images: an image token. The serializer writes
+        # `![alt|WIDTHxHEIGHT](url)`, `![alt|WIDTH](url)` or `![alt](url)`
+        # with the alt text escaped like a link label, and <img> in an
+        # HTML block.
         class ImageTag < Tag
-          def render(element, interface)
-            src = element.src
-            width = element.width
-            height = element.height
-
-            return render_html(src, width, height) if interface.html_mode?
-
-            # Build Discourse image syntax with dimensions
-            # Format: ![alt|WIDTHxHEIGHT](url) or ![alt|WIDTH](url)
-            if width && height
-              "![|#{width}x#{height}](#{src})"
-            elsif width
-              "![|#{width}](#{src})"
-            else
-              "![](#{src})"
-            end
-          end
-
-          private
-
-          def render_html(src, width, height)
-            attrs = %(src="#{HtmlEscaper.escape(src)}" alt="")
-            attrs << %( width="#{width}") if width
-            attrs << %( height="#{height}") if height
-            "<img #{attrs}>"
+          def render(element, _interface)
+            [
+              Inline::Tokens.image(
+                src: element.src,
+                alt: element.alt,
+                width: element.width,
+                height: element.height,
+              ),
+            ]
           end
         end
       end

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

@@ -4,14 +4,12 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering italic text
+        # Emphasis. The serializer writes the markers, or the HTML tags
+        # where the markers would not work.
         class ItalicTag < Tag
           def render(element, interface)
-            child_context = interface.with_parent(element)
-            content = interface.render_children(element, context: child_context)
-            return "<em>#{content}</em>" if interface.html_mode?
-
-            interface.wrap_inline(content, "*")
+            tokens = interface.render_tokens(element, context: interface.with_parent(element))
+            tokens.unshift(Inline::Tokens.open(:em)) << Inline::Tokens.close(:em)
           end
         end
       end

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

@@ -4,10 +4,17 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering line breaks
+        # Line breaks: a hard break token, which the serializer writes as a
+        # newline, as <br> on a line that holds nothing else (a newline
+        # there would be a blank line, which ends the paragraph and makes
+        # a list loose), and as <br> in an HTML block. A heading is one
+        # line, so a break in a heading is <br> as well.
         class LineBreakTag < Tag
+          HARD_BREAK = [Inline::Tokens.hard_break].freeze
+          private_constant :HARD_BREAK
+
           def render(_element, interface)
-            interface.html_mode? ? "<br>" : "\n"
+            interface.has_parent?(AST::Heading) ? "<br>" : HARD_BREAK
           end
         end
       end

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

@@ -12,6 +12,16 @@ module Markbridge
         # lands at the content column of the item that holds it, whatever
         # the nesting depth is.
         class ListItemTag < Tag
+          # Ends a nested list in front of more content of the item.
+          COMMENT = "<!---->"
+          LIST_END = "\n<!---->"
+          NEWLINE = 10
+          SPACE = 32
+          # Whitespace and the <br> the serializer writes for a line break
+          # on a line that holds nothing else.
+          TRAILING_BREAKS = /(?:[[:space:]]|<br>)+\z/
+          private_constant :COMMENT, :LIST_END, :NEWLINE, :SPACE, :TRAILING_BREAKS
+
           def initialize
             @builder = Builders::ListItemBuilder.new
           end
@@ -24,7 +34,7 @@ module Markbridge
             return "" if content.empty?
 
             parent_list = interface.find_parent(AST::List)
-            @builder.build(content, marker: determine_marker(parent_list))
+            @builder.build(content, marker: determine_marker(parent_list, interface))
           end
 
           private
@@ -39,28 +49,84 @@ module Markbridge
           # 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.
+          #
+          # Text after a nested list would become a continuation line of
+          # its last item, and a blank line in between would make the
+          # list loose again. An empty HTML comment on a line of its own
+          # ends the nested list without one; the whitespace between the
+          # list and the text goes.
           # @return [String]
           def render_content(element, interface, child_context)
+            after_list = false
             content =
               interface.render_children(element, context: child_context) do |buffer, child|
-                tighten(buffer) if child.is_a?(AST::List)
+                if child.is_a?(AST::List)
+                  tighten(buffer)
+                  after_list = true
+                elsif after_list && visible?(child)
+                  end_list(buffer, before: child)
+                  after_list = false
+                end
               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.
+          # The comment needs a line of its own: after it on the same line,
+          # the text would be part of the HTML block. Text that starts with
+          # a newline brings the line break itself. +before+ is the child
+          # that comes next.
+          def end_list(buffer, before:)
+            buffer.sub!(TRAILING_BREAKS, "")
+            buffer << LIST_END
+            buffer << "\n" unless text_of(before)&.start_with?("\n")
+          end
+
+          # Whitespace and line breaks between a nested list and the text
+          # after it do not count, the text does.
+          def visible?(child)
+            text = text_of(child)
+            return text.match?(/[^[:space:]]/) if text
+
+            !child.is_a?(AST::LineBreak)
+          end
+
+          # The text of a text child, as it is written to the output.
+          def text_of(child)
+            child.text if child.is_a?(AST::Text) || child.is_a?(AST::MarkdownText)
+          end
+
+          # Drops the blank lines in front of a nested list. A blank line
+          # is what ends an HTML block, so a line in front that opens one
+          # gets a different treatment: a line that starts a block of its
+          # own (the line in front of it is blank, as with the `</div>` of
+          # an aligned block) gets an empty comment in front, which makes
+          # the line a comment block that ends on the same line; a line
+          # inside a block an earlier line opened (the `</table>` of a
+          # table) keeps the blank line, and the outer list is loose.
           def tighten(buffer)
             buffer.rstrip!
-            last_line = buffer[(buffer.rindex("\n") || -1) + 1..]
-            buffer << "\n" if HtmlBlock.opens?(last_line)
+            # Byte offsets throughout: the content in front may hold
+            # multi-byte characters.
+            start = (buffer.byterindex("\n") || -1) + 1
+            return unless HtmlBlock.opens?(buffer.byteslice(start..))
+
+            if start.zero? || buffer.getbyte(start - 2) == NEWLINE
+              # After the indentation of the line: a nested list has
+              # indented its lines already.
+              start += 1 while buffer.getbyte(start) == SPACE
+              buffer.bytesplice(start, 0, COMMENT)
+            else
+              buffer << "\n"
+            end
           end
 
           # @param parent_list [AST::List, nil]
           # @return [String]
-          def determine_marker(parent_list)
-            parent_list&.ordered? ? "1. " : "- "
+          # The marker the renderer chose for the list (see
+          # RenderingInterface#choose_list_marker), or the first one of
+          # its kind for an item rendered without its list.
+          def determine_marker(parent_list, interface)
+            interface.list_marker(parent_list) || (parent_list&.ordered? ? "1. " : "- ")
           end
         end
       end

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

@@ -5,27 +5,49 @@ module Markbridge
     module Discourse
       module Tags
         class ListTag < Tag
+          # The output is the list, see Tag#leading_list.
+          def leading_list(element, _interface)
+            element
+          end
+
+          def trailing_list(element, _interface)
+            element
+          end
+
           def render(element, interface)
             child_context = interface.with_parent(element)
 
+            # Two lists of the same kind in a row would cook as one list,
+            # and the blank line between them would make it loose. A
+            # different marker starts a new list, so the renderer picks
+            # the one the list in front did not use, and the items write
+            # it (ListItemTag). In html_mode nothing reads it.
+            interface.choose_list_marker(element, ordered: element.ordered?)
+
             content =
               element
                 .children
                 .map { |child| interface.render_node(child, context: child_context) }
                 .join
 
+            # A list without items renders to nothing, like the other
+            # containers. Blank lines alone would still count as a list
+            # for the separator between two lists of the same kind.
+            return "" if content.empty?
+
             if interface.html_mode?
               tag_name = element.ordered? ? "ol" : "ul"
               return "<#{tag_name}>#{content}</#{tag_name}>"
             end
 
-            nested = interface.has_parent?(AST::List) || interface.has_parent?(AST::ListItem)
-
-            if nested
-              "\n#{content}"
-            else
-              "\n\n#{content}\n\n"
-            end
+            # A list right inside a list item starts on the line after the
+            # item text, so the list stays tight. ListItemTag takes care of
+            # what follows it in the item. Everywhere else (also inside a
+            # quote or an aligned block that sits in an item) the list is a
+            # block with blank lines on both sides.
+            parent = interface.context.element
+            nested = parent.is_a?(AST::ListItem) || parent.is_a?(AST::List)
+            nested ? "\n#{content}" : "\n\n#{content}\n\n"
           end
         end
       end

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

@@ -17,6 +17,18 @@ module Markbridge
         #     end
         #   end
         #
+        # @example Custom renderer with placeholder
+        #   # The importer replaces the placeholder with the mention, so the
+        #   # renderer joins it with its neighbors like a mention (see
+        #   # "Placeholders" in the migration guide).
+        #   Tokens = Markbridge::Renderers::Discourse::Inline::Tokens
+        #
+        #   class MyMentionTag < Markbridge::Renderers::Discourse::Tags::MentionTag
+        #     def render(element, interface)
+        #       [Tokens.placeholder("[mention|#{element.name}]", like: "@#{element.name}")]
+        #     end
+        #   end
+        #
         # @example Custom renderer that links to user
         #   class MyMentionTag < Markbridge::Renderers::Discourse::Tags::MentionTag
         #     def render(element, interface)

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

@@ -7,17 +7,20 @@ module Markbridge
         # Tag for rendering paragraphs
         # Paragraphs are separated by blank lines in Markdown
         class ParagraphTag < Tag
+          # Spaces and tabs at the start of the paragraph. Not a no-break
+          # space: the escaper writes one where it wants indentation kept.
+          LEADING_BLANKS = /\A[ \t]+/
+          private_constant :LEADING_BLANKS
+
           def render(element, interface)
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
 
             if interface.html_mode?
-              # Inside a table cell the surrounding <td> already provides the
-              # block context, so a <p> wrapper just adds vertical margin —
-              # and if the paragraph contains a block element (e.g. a list),
-              # `<p><ul>…</ul></p>` is invalid per HTML5. Drop the wrapper.
-              return content if interface.has_parent?(AST::TableCell)
-
+              # Also inside a table cell: without the <p> the paragraph
+              # runs into the text next to it. A block inside the
+              # paragraph closes the <p> early in the HTML parser, which
+              # is what the Markdown form does as well.
               return "<p>#{content}</p>"
             end
 
@@ -25,6 +28,10 @@ module Markbridge
             # non-block content (raw text, inline elements) stays separated
             # from the paragraph. cleanup_markdown collapses any duplicate
             # newlines that result when neighbours are themselves block tags.
+            # Spaces at the start go: CommonMark drops up to three of them
+            # anyway, and after a list they would make the paragraph part
+            # of the last item.
+            content = content.sub(LEADING_BLANKS, "") if content.match?(LEADING_BLANKS)
             "\n\n#{content}\n\n"
           end
         end

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

@@ -4,27 +4,70 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Placeholder tag for rendering polls.
+        # Renders {AST::Poll} as the +[poll]+ BBCode of the poll plugin: the
+        # raw BBCode of the source when the parser kept it, otherwise the
+        # BBCode built from the attributes and the options.
         #
-        # This is a STUB implementation that outputs the original raw BBCode.
-        # Applications using Markbridge should provide their own custom tag
-        # to render polls as placeholders or convert them to another format.
+        # With +bbcode: false+, for a site without the plugin, the options
+        # are written as a bullet list. The raw BBCode is of no use there.
         #
-        # @example Custom renderer with placeholder
+        # The BBCode has no HTML form, so it goes through
+        # RenderingInterface#markdown_island: a block with blank lines
+        # around it, and a Markdown island in a `<div>` inside an HTML
+        # table. A placeholder for a poll is written the same way (see
+        # "Placeholders" in the migration guide).
+        #
+        # @example A placeholder for the importer
         #   class MyPollTag < Markbridge::Renderers::Discourse::Tags::PollTag
         #     def render(element, interface)
         #       id = register_poll(element)
-        #       "<<POLL:#{id}>>"
+        #       interface.markdown_island("<<POLL:#{id}>>", block: true)
         #     end
         #   end
         class PollTag < Tag
-          def render(element, _interface)
-            body = element.raw || build_poll_bbcode(element)
-            "\n\n#{body}\n\n"
+          # @param bbcode [Boolean] write the BBCode of the plugin
+          def initialize(bbcode: true)
+            @bbcode = bbcode
+          end
+
+          def render(element, interface)
+            return without_plugin(element, interface) unless @bbcode
+
+            interface.markdown_island(element.raw || build_poll_bbcode(element), block: true)
+          end
+
+          # The plain form is a bullet list, so a bullet list next to the
+          # poll would continue it (see Tag#leading_list). The poll stands
+          # for the list, the marker is chosen for it.
+          def leading_list(element, _interface)
+            element unless @bbcode
+          end
+
+          def trailing_list(element, _interface)
+            element unless @bbcode
           end
 
           private
 
+          # The options as the items of a bullet list, one line each; a
+          # poll without options renders to nothing, like an empty list.
+          # The poll writes the lines itself, with the marker the renderer
+          # picks for it against the list in front.
+          def without_plugin(element, interface)
+            return "" if element.options.empty?
+            if interface.html_mode?
+              items = element.options.map { |option| "<li>#{HtmlEscaper.escape(option)}</li>" }
+              return "<ul>#{items.join}</ul>"
+            end
+
+            marker = interface.choose_list_marker(element, ordered: false)
+            lines =
+              element.options.map do |option|
+                "#{marker}#{interface.render_node(AST::Text.new(option))}"
+              end
+            "\n\n#{lines.join("\n")}\n\n"
+          end
+
           def build_poll_bbcode(element)
             attrs = build_attributes(element)
             options = element.options.map { |opt| "* #{opt}" }.join("\n")

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

@@ -10,9 +10,15 @@ module Markbridge
           def render(element, interface)
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
-
+            # An empty quote shows nothing, but it is still a block: the
+            # blank line keeps the text in front and after it apart. In an
+            # HTML block a blank line would end the block.
+            return interface.html_mode? ? "" : "\n\n" if content.empty?
             return "<blockquote>#{content}</blockquote>" if interface.html_mode?
 
+            # A block at the start or the end brings its own blank lines.
+            content = content.gsub(/\A\n+|\n+\z/, "")
+
             # Build Discourse quote BBCode
             # Format: [quote="username, post:2, topic:456"]content[/quote]
             # (post: is the post number within the topic, topic: the topic id)
@@ -24,6 +30,10 @@ module Markbridge
                 # Name-only attribution; a bare post_id/user_id can't
                 # produce a valid Discourse post reference.
                 "[quote=\"#{element.author || element.username}\"]\n#{content}\n[/quote]"
+              elsif nests_attributed_quote?(element)
+                # Discourse doesn't render a [quote="…"] inside a Markdown
+                # blockquote, so the outer quote is BBCode too.
+                "[quote]\n#{content}\n[/quote]"
               else
                 # Plain quote rendered as Markdown blockquote
                 content.split("\n").map { |line| "> #{line}" }.join("\n")
@@ -34,6 +44,21 @@ module Markbridge
             # inline elements) starts a new paragraph against the quote.
             "\n\n#{body}\n\n"
           end
+
+          private
+
+          # @param element [AST::Element]
+          # @return [Boolean] whether a quote that renders as [quote="…"]
+          #   is somewhere inside +element+
+          def nests_attributed_quote?(element)
+            element.children.any? do |child|
+              child.is_a?(AST::Element) &&
+                (
+                  (child.is_a?(AST::Quote) && (child.author || child.username)) ||
+                    nests_attributed_quote?(child)
+                )
+            end
+          end
         end
       end
     end