coradoc-markdown 1.0.0 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e985a5efd633ee5e945c01d6f9465316f36ed682e8a65fa1c6c33304f8af453c
-  data.tar.gz: ece9f3be5276f6ef0c1c325fa59a3f43452472b8aa5e2350ad690381b5b7a173
+  metadata.gz: e84594b2f47a9d07086b781a843c5b1f7b2ddb34303bbe32114ea1c9e7ac1aec
+  data.tar.gz: 7fd311efb6eef499247c37bacb8357d3b6349eabc1347c6a875d21c6b315fa18
 SHA512:
-  metadata.gz: 531bc6952f8a55ccbd3b86190ced905b60242bebe6dd65873fee5cc0715fcdaa802147473fb897fb818bdec611937e48eb3b995db4844cd4c7c08a4f575bdbf7
-  data.tar.gz: 022055b32982e6a661bcbcca4e6044e8ccb4f36d265d7f4bbe1575c07e9a424acb711d8dc532a8ba49bc4afd2d56423f0c9be127bb9a996d1cdd5c9e1e738d26
+  metadata.gz: ee32797ed75c3659d6e21fd9041d4f9a193497c50417f1f2ca986bd23459bf83b5a3cab47540f417d34014d806b1f20671e132ca4b0c0195b7b23870cb4aff37
+  data.tar.gz: 2cfc83d2fa5c1e732283d6efa0d37f05b5f9ea4c8970217f64cbb6771084c4aa2f6fa0aaaba4049aceb9ed9fb611d6395d210a5c8ce8c199a3bbf1768e4d4665

data/lib/coradoc/markdown/model/admonition.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Markdown
+    # Admonition block — a callout like NOTE, WARNING, TIP, etc.
+    #
+    # Markdown has no native admonition syntax (GFM Alerts since Dec 2023
+    # notwithstanding — see admonition/gfm_alert strategy). The
+    # `admonition_style` config option selects the output form:
+    #
+    #   :github   → > **NOTE:** text         (broad compat)
+    #   :gfm_alert → > [!NOTE]\n> text        (GFM native since 2024)
+    #   :container → :::note\n... \n:::        (VitePress / markdown-it)
+    #   :html     → <div class="note">...</div>
+    #
+    # Type is stored lowercase. Content is raw Markdown text (already
+    # serialized). Title is optional.
+    class Admonition < Base
+      ALLOWED_TYPES = %w[note tip warning important caution].freeze
+
+      attribute :admonition_type, :string
+      attribute :content, :string
+      attribute :title, :string
+
+      def initialize(admonition_type:, content:, title: nil, **rest)
+        super
+        @admonition_type = admonition_type.to_s.downcase
+        @content = content
+        @title = title
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/attribute_list.rb

@@ -16,7 +16,7 @@ module Coradoc
     class AttributeList < Base
       attribute :id, :string
       attribute :classes, :string, collection: true, default: []
-      attribute :attributes, :hash, default: {}
+      attribute :attributes, NamedValue, collection: true, default: []
       attribute :name, :string # For ALD - the reference name
 
       # Parse an IAL string into an AttributeList
@@ -50,7 +50,9 @@ module Coradoc
 
         self.id = other.id if other.id
         self.classes = (classes + other.classes).uniq
-        self.attributes = attributes.merge(other.attributes)
+        merged = {}
+        (attributes + other.attributes).each { |nv| merged[nv.name] = nv }
+        self.attributes = merged.values
         self
       end
 
@@ -67,19 +69,6 @@ module Coradoc
         id.nil? && classes.empty? && attributes.empty?
       end
 
-      # Convert to Markdown IAL syntax
-      # @return [String]
-      def to_md
-        return '' if empty?
-
-        parts = []
-        parts << "##{id}" if id
-        parts += classes.map { |c| ".#{c}" }
-        parts += attributes.map { |k, v| %(#{k}="#{v}") }
-
-        "{:#{parts.join(' ')}}"
-      end
-
       def self.parse_attributes(content, attr_list)
         # Use shared IalParser for consistent parsing
         ParserUtil::IalParser.tokenize(content).each do |token|
@@ -89,7 +78,7 @@ module Coradoc
           when :id
             attr_list.id = token[:value]
           when :attribute
-            attr_list.attributes[token[:key]] = token[:value]
+            attr_list.attributes << NamedValue.new(name: token[:key], value: token[:value])
           end
         end
       end

data/lib/coradoc/markdown/model/base.rb

@@ -18,8 +18,8 @@ module Coradoc
       # Classes from IAL (for convenience)
       attribute :classes, :string, collection: true
 
-      # Additional attributes from IAL
-      attribute :attributes, :hash, default: {}
+      # Additional attributes from IAL (typed key-value pairs)
+      attribute :attributes, NamedValue, collection: true, default: []
 
       # Visit pattern for traversing the document tree
       def self.visit(element, &block)
@@ -49,38 +49,6 @@ module Coradoc
         end
         self
       end
-
-      # Serialize polymorphic content to Markdown string
-      def serialize_content(content)
-        case content
-        when Array
-          content.map { |elem| serialize_content(elem) }.join
-        when String
-          content
-        when nil
-          ''
-        else
-          if content.is_a?(Base)
-            content.to_md
-          else
-            raise ArgumentError,
-                  "Cannot serialize #{content.class.name} to Markdown. " \
-                  'Expected String or Base subclass.'
-          end
-        end
-      end
-
-      # Does a shallow attribute dump of the object
-      def to_h
-        self.class.attributes.keys.each_with_object({}) do |attribute, acc|
-          acc[attribute] = public_send(attribute)
-        end
-      end
-
-      # Serialize this model element to Markdown
-      def to_md
-        Coradoc::Markdown::Serializer.serialize(self)
-      end
     end
   end
 end

data/lib/coradoc/markdown/model/comment.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # HTML comment in Markdown source (`<!-- text -->`).
+    #
+    # Markdown has no native comment syntax; HTML comments are the conventional
+    # mechanism for non-rendered authoring notes. Both AsciiDoc single-line
+    # (`//`) and block (`//// ... ////`) comments collapse to this type.
+    class Comment < Base
+      attribute :text, :string
+    end
+  end
+end

data/lib/coradoc/markdown/model/cross_reference.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class CrossReference < Base
+      attribute :text, :string
+      attribute :target, :string
+    end
+  end
+end

data/lib/coradoc/markdown/model/definition_list.rb

@@ -30,18 +30,6 @@ module Coradoc
     class DefinitionList < Base
       # Terms with their definitions
       attribute :items, Coradoc::Markdown::DefinitionTerm, collection: true
-
-      # Serialize to Markdown
-      def to_md
-        items.map do |term|
-          term_text = term.text.to_s
-          defs = term.definitions.map do |defn|
-            content = defn.content.to_s
-            ": #{content}"
-          end.join("\n")
-          "#{term_text}\n#{defs}"
-        end.join("\n\n")
-      end
     end
   end
 end

data/lib/coradoc/markdown/model/definition_term.rb

@@ -7,15 +7,25 @@ module Coradoc
     # A term can have multiple definitions and can span multiple lines.
     # Terms can also have IAL attributes attached.
     #
-    # @example Simple term
-    #   term = Coradoc::Markdown::DefinitionTerm.new(text: "kramdown")
-    #
+    # A term can carry a nested DefinitionList when the original document
+    # had structured sub-entries (e.g. glossary sub-terms). When `nested`
+    # is present, the serializer's nested_html strategy kicks in to emit
+    # HTML `<dl>` structure that Markdown syntax cannot express.
     class DefinitionTerm < Base
-      # The term text content
       attribute :text, :string
-
-      # Definitions for this term
       attribute :definitions, Coradoc::Markdown::DefinitionItem, collection: true, default: []
+
+      # Optional nested definition list under this term.
+      # When present, the flat-PHP-Markdown-Extra syntax is no longer
+      # sufficient and the serializer falls back to HTML <dl>/<dt>/<dd>.
+      attribute :nested, Coradoc::Markdown::DefinitionList
+
+      def initialize(text: '', definitions: [], nested: nil, **rest)
+        super
+        @text = text
+        @definitions = definitions
+        @nested = nested
+      end
     end
   end
 end

data/lib/coradoc/markdown/model/document.rb

@@ -18,6 +18,15 @@ module Coradoc
     class Document < Base
       attribute :blocks, Coradoc::Markdown::Base, collection: true
 
+      # Raw YAML frontmatter text, or nil if absent.
+      #
+      # Markdown treats frontmatter as opaque text — the YAML is only
+      # parsed/emitted at the CoreModel boundary by
+      # CoreModel::FrontmatterBlock::Codec (single source of truth).
+      # Storing raw text keeps Markdown's parser/serializer symmetric
+      # without dragging YAML semantics into the Markdown model (MECE).
+      attribute :frontmatter, :string
+
       # @param [Integer] index The index of the block to retrieve
       # @return [Coradoc::Markdown::Base] The block at the specified index
       def [](index)

data/lib/coradoc/markdown/model/example_block.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Markdown
+    # Example block — an illustrative container, optionally with a caption.
+    #
+    # Markdown has no native example syntax. Default rendering is an
+    # HTML fallback that preserves the caption as an `<h4>` heading
+    # inside a `<div class="example">` wrapper.
+    #
+    # When `admonition_style == :container` (VitePress), the serializer
+    # emits `:::details Caption\n...\n:::`.
+    class ExampleBlock < Base
+      attribute :content, :string
+      attribute :caption, :string
+
+      def initialize(content:, caption: nil, **rest)
+        super
+        @content = content
+        @caption = caption
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/extension.rb

@@ -13,7 +13,7 @@ module Coradoc
     #
     class Extension < Base
       attribute :name, :string
-      attribute :options, :hash, default: {}
+      attribute :options, NamedValue, collection: true, default: []
       attribute :content, :string  # For block extensions with content
       attribute :body, :string     # Alias for content
 
@@ -32,14 +32,14 @@ module Coradoc
       # @param options [Hash] TOC options (levels, etc.)
       # @return [Extension]
       def self.toc(options = {})
-        new(name: :toc, options: options)
+        new(name: :toc, options: hash_to_named(options))
       end
 
       # Create an options extension
       # @param options [Hash] Parser options
       # @return [Extension]
       def self.options(options = {})
-        new(name: :options, options: options)
+        new(name: :options, options: hash_to_named(options))
       end
 
       # Create a comment extension
@@ -69,23 +69,14 @@ module Coradoc
         content.nil? || content.empty?
       end
 
-      # Convert to Markdown
-      # @return [String]
-      def to_md
-        opts = options.empty? ? '' : " #{options_to_s}"
-        if self_closing?
-          "{::#{name}#{opts} /}"
-        else
-          "{::#{name}#{opts}}#{content}{:/}"
-        end
-      end
+      class << self
+        private
 
-      private
+        def hash_to_named(hash)
+          return [] if hash.nil? || hash.empty?
 
-      def options_to_s
-        options.map do |k, v|
-          %(#{k}="#{v}")
-        end.join(' ')
+          hash.map { |k, v| NamedValue.new(name: k.to_s, value: v.to_s) }
+        end
       end
     end
   end

data/lib/coradoc/markdown/model/footnote_reference.rb

@@ -12,11 +12,6 @@ module Coradoc
     class FootnoteReference < Base
       # The footnote identifier
       attribute :id, :string
-
-      # Serialize to Markdown
-      def to_md
-        "[^#{id}]"
-      end
     end
   end
 end

data/lib/coradoc/markdown/model/hard_line_break.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Markdown
+    # Hard line break — forces a line break within a paragraph, distinct
+    # from a new paragraph.
+    #
+    # Two strategy modes (configurable via the serializer config):
+    #   - `:trailing_space` (CommonMark default): two trailing spaces
+    #   - `:backslash` (GFM alternative): backslash before newline
+    #
+    # AsciiDoc `+` line-continuation maps to this element.
+    class HardLineBreak < Base
+      def initialize(**_rest)
+        super
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/highlight.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-
 module Coradoc
   module Markdown
     # Represents highlighted text using == syntax (extended Markdown).
@@ -9,10 +8,6 @@ module Coradoc
     #
     class Highlight < Base
       attribute :text, :string
-
-      def to_md
-        "==#{text}=="
-      end
     end
   end
 end

data/lib/coradoc/markdown/model/horizontal_rule.rb

@@ -5,12 +5,7 @@ module Coradoc
     # HorizontalRule model representing a Markdown horizontal rule (---, ***, ___).
     #
     class HorizontalRule < Base
-      attribute :style, :string, default: '---' # ---, ***, or ___
-
-      def initialize(style: '---')
-        super()
-        @style = style
-      end
+      attribute :style, :string, default: '---'
     end
   end
 end

data/lib/coradoc/markdown/model/list_item.rb

@@ -18,7 +18,7 @@ module Coradoc
         @text = args[:text] || ''
         @checked = args[:checked]
         @sublist = args[:sublist]
-        @children = args[:children] || []
+        @children = args.fetch(:children, [])
       end
 
       def children=(value)

data/lib/coradoc/markdown/model/literal.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Markdown
+    # Literal block — preformatted text with no syntax highlighting and
+    # no inline formatting. Distinct from a code block (which carries a
+    # language for highlighting).
+    #
+    # Markdown: indented code block (4 leading spaces per line).
+    class Literal < Base
+      attribute :content, :string
+
+      def initialize(content:, **rest)
+        super
+        @content = content
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/math.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-
 module Coradoc
   module Markdown
     # Represents a math block (block or inline)
@@ -29,22 +28,9 @@ module Coradoc
         new(content: content, inline: true)
       end
 
-      # Create a block math element
-      # @param content [String] The math content
-      # @return [Math]
       def self.block(content)
         new(content: content, inline: false)
       end
-
-      # Convert to Markdown
-      # @return [String]
-      def to_md
-        if inline?
-          "$$#{content}$$"
-        else
-          "$$\n#{content}\n$$"
-        end
-      end
     end
   end
 end

data/lib/coradoc/markdown/model/named_value.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    # A typed key-value pair used wherever Markdown models need arbitrary
+    # attributes (IAL key="value" pairs, extension options, etc.).
+    #
+    # Replaces raw Hash attributes so that every attribute on a model is
+    # a typed lutaml-model declaration.
+    #
+    # @example
+    #   NamedValue.new(name: "data-role", value: "main")
+    class NamedValue < Base
+      attribute :name, :string
+      attribute :value, :string
+    end
+  end
+end

data/lib/coradoc/markdown/model/open_block.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Markdown
+    # Open block — generic container that groups content without semantic
+    # formatting. Used in AsciiDoc to apply IDs/attributes to a group.
+    #
+    # Markdown has no native container. The serializer's OpenBlock strategy:
+    #   - Without id/classes → emit children as siblings (no wrapper)
+    #   - With id/classes    → emit `<div id="...">...</div>` wrapper
+    class OpenBlock < Base
+      attribute :children, Coradoc::Markdown::Base, collection: true, default: []
+
+      def initialize(children: [], **rest)
+        super
+        @children = Array(children)
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/paragraph.rb

@@ -14,10 +14,10 @@ module Coradoc
       # @return [Array] mixed content array
       attr_reader :children
 
-      def initialize(text: '', children: nil)
+      def initialize(text: '', children: [])
         super()
         @text = text
-        @children = children || []
+        @children = children
       end
 
       def children=(value)

data/lib/coradoc/markdown/model/pass.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Markdown
+    # Pass block — raw content passed through verbatim, never rendered as
+    # Markdown. Used for embedding HTML or other markup directly.
+    #
+    # Markdown has no native pass concept; the content is emitted as-is
+    # inside a `nomarkdown` kramdown extension or raw HTML passthrough.
+    class Pass < Base
+      attribute :content, :string
+
+      def initialize(content:, **rest)
+        super
+        @content = content
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/sidebar.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Markdown
+    # Sidebar block — a tangential aside, visually distinct from main flow.
+    #
+    # Markdown has no native sidebar. Serialized as an HTML fallback:
+    #   <div class="sidebar">...</div>
+    class Sidebar < Base
+      attribute :content, :string
+      attribute :title, :string
+
+      def initialize(content:, title: nil, **rest)
+        super
+        @content = content
+        @title = title
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/model/strikethrough.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-
 module Coradoc
   module Markdown
     # Represents strikethrough text using GFM ~~ syntax.
@@ -9,10 +8,6 @@ module Coradoc
     #
     class Strikethrough < Base
       attribute :text, :string
-
-      def to_md
-        "~~#{text}~~"
-      end
     end
   end
 end

data/lib/coradoc/markdown/model/subscript.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class Subscript < Base
+      attribute :text, :string
+    end
+  end
+end

data/lib/coradoc/markdown/model/superscript.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class Superscript < Base
+      attribute :text, :string
+    end
+  end
+end

data/lib/coradoc/markdown/model/underline.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class Underline < Base
+      attribute :text, :string
+    end
+  end
+end

data/lib/coradoc/markdown/model/verse.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Markdown
+    # Verse block — preformatted text preserving line breaks but allowing
+    # inline formatting. Distinct from a literal block (no formatting)
+    # or a code block (no formatting + language hint).
+    #
+    # Markdown has no native verse. Serialized as a blockquote with the
+    # understanding that verse semantics are lost but line breaks are
+    # preserved via hard line breaks.
+    class Verse < Base
+      attribute :content, :string
+      attribute :attribution, :string
+      attribute :citetitle, :string
+
+      def initialize(content:, attribution: nil, citetitle: nil, **rest)
+        super
+        @content = content
+        @attribution = attribution
+        @citetitle = citetitle
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/parser/block_parser.rb

@@ -424,7 +424,7 @@ module Coradoc
             table_separator_row.as(:table_separator) >>
             line_ending >>
             (
-              table_row.as(:table_body_row) >> line_ending
+              table_row.as(:table_body_row) >> (line_ending | any.absent?)
             ).repeat(1).as(:table_body)
         end
 

data/lib/coradoc/markdown/parser/frontmatter_parser.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    module Parser
+      # Markdown frontmatter extractor.
+      #
+      # Delegates to the shared +Coradoc::CoreModel::FrontmatterBlock::TextSplitter+
+      # — the single source of truth for the `---\n...\n---\n` convention
+      # (DRY). Format gems retain a local parser module for discoverability
+      # and as the seam for any format-specific extensions should they arise.
+      module FrontmatterParser
+        class << self
+          def call(text)
+            Coradoc::CoreModel::FrontmatterBlock::TextSplitter.call(text)
+          end
+        end
+
+        Result = Coradoc::CoreModel::FrontmatterBlock::TextSplitter::Result
+      end
+    end
+  end
+end