coradoc-markdown 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f645b393312f1c1dac03f7986da00e8165c28a08fa10e656284dfd0fa8b024e
-  data.tar.gz: f90f52be5816d785860b14615ed5aff2588f6a061ed8006753adc030111f5c05
+  metadata.gz: e84594b2f47a9d07086b781a843c5b1f7b2ddb34303bbe32114ea1c9e7ac1aec
+  data.tar.gz: 7fd311efb6eef499247c37bacb8357d3b6349eabc1347c6a875d21c6b315fa18
 SHA512:
-  metadata.gz: 29d1fa6b132ff28425d7ccfd7eeacfc782f9d648a07802fdbfb434134e13a2a0ee40489e207ca6ea4d1f92358feb0c94097dc168024339b833cf558e7e6bcab3
-  data.tar.gz: 92960c95e653cc2c0c16ccfb1e23563db3d1ebe7a931b4c3a28f88c8be87d922e604b6448c53d493661e42c1bbcdeb8b2b08ce0847300cee624948accebacc92
+  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/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/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/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/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/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/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

data/lib/coradoc/markdown/serializer/builder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'config'
+require_relative 'context'
+require_relative 'registry'
+require_relative 'registrations'
+require_relative 'runner'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Fluent builder for a configured serializer runner.
+      #
+      # Usage:
+      #
+      #   Serializer.build(:gfm) do |config|
+      #     config.admonition_style = :container
+      #     config.suppress_comments = false
+      #   end.call(element)
+      #
+      # The block yields the Builder itself; assignments accumulate as
+      # overrides and are frozen into a Config when `runner` (or `call`)
+      # is invoked.
+      class Builder
+        attr_reader :flavor, :overrides
+
+        def initialize(flavor = Flavor::DEFAULT_FLAVOR)
+          @flavor = flavor
+          @overrides = {}
+        end
+
+        Config::ATTRIBUTES.each do |attr|
+          define_method("#{attr}=") do |value|
+            @overrides[attr] = value
+          end
+        end
+
+        def apply(hash)
+          hash.each { |k, v| @overrides[k.to_sym] = v }
+          self
+        end
+
+        def config
+          @config ||= Config.new(flavor: flavor, **overrides)
+        end
+
+        def runner
+          @runner ||= Runner.new(config: config, registry: Registrations.default_registry)
+        end
+
+        def call(element)
+          runner.call(element)
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/config.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'flavor'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Immutable serialization configuration.
+      #
+      # Created via `Serializer.build` with a flavor and overrides. Once
+      # built, the Config is frozen and resolves capability strategies
+      # (admonitions, autolinks, comments, etc.) by combining flavor
+      # defaults with caller overrides.
+      #
+      # SSOT: the 5 spec-mandated options live here and nowhere else.
+      # Strategy classes read their mode via `config.strategy_for(:capability)`.
+      class Config
+        ATTRIBUTES = %i[
+          markdown_flavor
+          admonition_style
+          definition_list_nested
+          suppress_comments
+          autolinks
+        ].freeze
+
+        attr_reader(*ATTRIBUTES)
+
+        def initialize(flavor: :gfm, **overrides)
+          unless Flavor.known?(flavor)
+            raise ArgumentError, "Unknown markdown_flavor: #{flavor.inspect}. " \
+                                 "Known: #{Flavor.names.inspect}"
+          end
+
+          resolved = Flavor.resolve(flavor).merge(symbolize(overrides))
+          validate_options!(resolved)
+
+          @markdown_flavor = resolved.fetch(:markdown_flavor)
+          @admonition_style = resolved.fetch(:admonition_style)
+          @definition_list_nested = resolved.fetch(:definition_list_nested)
+          @suppress_comments = resolved.fetch(:suppress_comments)
+          @autolinks = resolved.fetch(:autolinks)
+
+          freeze
+        end
+
+        def to_h
+          ATTRIBUTES.to_h { |k| [k, public_send(k)] }
+        end
+
+        def with(overrides)
+          self.class.new(**to_h.merge(symbolize(overrides)))
+        end
+
+        private
+
+        def symbolize(hash)
+          hash.to_h { |k, v| [k.to_sym, v] }
+        end
+
+        def validate_options!(resolved)
+          unless %i[github container html gfm_alert].include?(resolved.fetch(:admonition_style))
+            raise ArgumentError, "Unknown admonition_style: #{resolved[:admonition_style].inspect}"
+          end
+          unless %i[html flatten].include?(resolved.fetch(:definition_list_nested))
+            raise ArgumentError, "Unknown definition_list_nested: #{resolved[:definition_list_nested].inspect}"
+          end
+          unless [true, false].include?(resolved.fetch(:suppress_comments))
+            raise ArgumentError, 'suppress_comments must be boolean'
+          end
+          return if [true, false].include?(resolved.fetch(:autolinks))
+
+          raise ArgumentError, 'autolinks must be boolean'
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/context.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Per-document mutable state threaded through every serializer call,
+      # AND the single dispatch interface element serializers use to
+      # recurse into child elements.
+      #
+      # Threading dispatch through the context (not the runner) means
+      # serializers stay stateless and don't need a back-reference to
+      # the runner — they call `ctx.serialize(child)` and `ctx.serialize_inline(child)`.
+      #
+      # Holds counters (footnotes, link references) and accumulators
+      # (footnote definitions emitted at document end, etc.). Created
+      # fresh per top-level `call` — never shared between documents.
+      class Context
+        attr_reader :config, :registry, :runner,
+                    :footnote_defs, :link_refs,
+                    :footnote_counter, :link_counter
+
+        def initialize(config:, registry:, runner:)
+          @config = config
+          @registry = registry
+          @runner = runner
+          @footnote_defs = []
+          @link_refs = []
+          @footnote_counter = 0
+          @link_counter = 0
+        end
+
+        def serialize(element)
+          runner.serialize(element, self)
+        end
+
+        def serialize_inline(element)
+          runner.serialize_inline(element, self)
+        end
+
+        def serialize_inline_join(elements)
+          Array(elements).map { |e| serialize_inline(e) }.join
+        end
+
+        def next_footnote_id
+          @footnote_counter += 1
+          "fn#{@footnote_counter}"
+        end
+
+        def next_link_ref_id
+          @link_counter += 1
+          @link_counter.to_s
+        end
+
+        def register_footnote_def(definition_text)
+          @footnote_defs << definition_text unless @footnote_defs.include?(definition_text)
+        end
+
+        def register_link_ref(id, url, title: nil)
+          @link_refs << LinkRef.new(id: id, url: url, title: title)
+        end
+
+        LinkRef = Struct.new(:id, :url, :title)
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/element_serializer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Base class for element serializers. Subclasses declare:
+      # - `handles_type TypeClass` — the model class (or ancestor) they accept
+      # - `call(element, ctx)` — the actual serialization
+      #
+      # `handles?` defaults to `is_a?(handles_type)`; override for finer
+      # conditional dispatch (e.g. "I handle DefinitionList only when nested").
+      class ElementSerializer
+        class << self
+          def handles_type(klass = nil)
+            if klass
+              @handles_type = klass
+              self
+            else
+              @handles_type || (superclass.respond_to?(:handles_type) ? superclass.handles_type : nil)
+            end
+          end
+
+          def handles?(_element)
+            true
+          end
+
+          def call(...)
+            new.call(...)
+          end
+        end
+
+        def call(_element, _ctx)
+          raise NotImplementedError, "#{self.class.name}#call not implemented"
+        end
+
+        def handles?(element)
+          self.class.handles?(element)
+        end
+
+        def handles_type
+          self.class.handles_type
+        end
+      end
+    end
+  end
+end