coradoc-markdown 1.0.2 → 1.0.3

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Named Markdown flavor profiles.
+      #
+      # Each flavor bundles sensible defaults for the 5 spec options.
+      # Callers can override any option via `Serializer.build`.
+      #
+      # Adding a new flavor = adding one entry here. No serializer code
+      # needs to change — Open/Closed.
+      module Flavor
+        PROFILES = {
+          commonmark: {
+            markdown_flavor: :commonmark,
+            admonition_style: :html,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          },
+          gfm: {
+            markdown_flavor: :gfm,
+            admonition_style: :github,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          },
+          kramdown: {
+            markdown_flavor: :kramdown,
+            admonition_style: :html,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          },
+          pandoc: {
+            markdown_flavor: :pandoc,
+            admonition_style: :html,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          },
+          vitepress: {
+            markdown_flavor: :vitepress,
+            admonition_style: :container,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          },
+          php_markdown_extra: {
+            markdown_flavor: :php_markdown_extra,
+            admonition_style: :html,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          }
+        }.freeze
+
+        DEFAULT_FLAVOR = :gfm
+
+        class << self
+          def names
+            PROFILES.keys
+          end
+
+          def known?(name)
+            PROFILES.key?(name.to_sym)
+          end
+
+          def resolve(name)
+            profile = PROFILES[name.to_sym] || PROFILES[DEFAULT_FLAVOR]
+            profile.dup
+          end
+
+          def default
+            PROFILES[DEFAULT_FLAVOR]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative 'registry'
+require_relative 'serializers/document'
+require_relative 'serializers/heading'
+require_relative 'serializers/paragraph'
+require_relative 'serializers/list'
+require_relative 'serializers/code_block'
+require_relative 'serializers/blockquote'
+require_relative 'serializers/link'
+require_relative 'serializers/image'
+require_relative 'serializers/horizontal_rule'
+require_relative 'serializers/table'
+require_relative 'serializers/emphasis'
+require_relative 'serializers/strong'
+require_relative 'serializers/code'
+require_relative 'serializers/strikethrough'
+require_relative 'serializers/highlight'
+require_relative 'serializers/subscript'
+require_relative 'serializers/superscript'
+require_relative 'serializers/underline'
+require_relative 'serializers/cross_reference'
+require_relative 'serializers/attribute_list'
+require_relative 'serializers/math'
+require_relative 'serializers/extension'
+require_relative 'serializers/definition_list'
+require_relative 'serializers/footnote'
+require_relative 'serializers/footnote_reference'
+require_relative 'serializers/abbreviation'
+require_relative 'serializers/comment'
+require_relative 'serializers/admonition'
+require_relative 'serializers/example_block'
+require_relative 'serializers/open_block'
+require_relative 'serializers/sidebar'
+require_relative 'serializers/verse'
+require_relative 'serializers/pass'
+require_relative 'serializers/literal'
+require_relative 'serializers/hard_line_break'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Auto-registers all built-in element serializers into a fresh
+      # Registry. Called once per Runner (cached via `default_registry`).
+      #
+      # Adding a new element serializer = appending one entry here. No
+      # lookup code changes — Open/Closed.
+      module Registrations
+        SERIALIZEABLE = [
+          Serializers::Document,
+          Serializers::Heading,
+          Serializers::Paragraph,
+          Serializers::List,
+          Serializers::CodeBlock,
+          Serializers::Blockquote,
+          Serializers::Link,
+          Serializers::Image,
+          Serializers::HorizontalRule,
+          Serializers::Table,
+          Serializers::Emphasis,
+          Serializers::Strong,
+          Serializers::Code,
+          Serializers::Strikethrough,
+          Serializers::Highlight,
+          Serializers::Subscript,
+          Serializers::Superscript,
+          Serializers::Underline,
+          Serializers::CrossReference,
+          Serializers::AttributeList,
+          Serializers::Math,
+          Serializers::Extension,
+          Serializers::DefinitionList,
+          Serializers::Footnote,
+          Serializers::FootnoteReference,
+          Serializers::Abbreviation,
+          Serializers::Comment,
+          Serializers::Admonition,
+          Serializers::ExampleBlock,
+          Serializers::OpenBlock,
+          Serializers::Sidebar,
+          Serializers::Verse,
+          Serializers::Pass,
+          Serializers::Literal,
+          Serializers::HardLineBreak
+        ].freeze
+
+        @mutex = Mutex.new
+        @default = nil
+
+        class << self
+          def default_registry
+            @mutex.synchronize do
+              @default ||= register_all(Registry.new)
+            end
+          end
+
+          def fresh_registry
+            register_all(Registry.new)
+          end
+
+          private
+
+          def register_all(registry)
+            SERIALIZEABLE.each { |klass| registry.register(klass.new) }
+            registry
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Type-keyed dispatch table for element serializers.
+      #
+      # Each entry is a tuple of (serializer_instance, priority). Dispatch
+      # resolves the highest-priority entry whose declared `handles?` predicate
+      # accepts the element. This lets specialized serializers (e.g. one that
+      # targets a specific CoreModel subclass) override generic ones without
+      # modifying the registry lookup logic — Open/Closed.
+      class Registry
+        class Entry < Struct.new(:serializer, :priority)
+          include Comparable
+
+          def <=>(other)
+            priority <=> other.priority
+          end
+        end
+
+        def initialize
+          @entries = Hash.new { |h, k| h[k] = [] }
+        end
+
+        def register(serializer, priority: 0)
+          klass = serializer.handles_type
+          raise ArgumentError, "Serializer #{serializer.class} declares no handles_type" unless klass
+
+          @entries[klass] << Entry.new(serializer, priority)
+          @entries[klass].sort!
+          serializer
+        end
+
+        def lookup(element)
+          each_candidate(element).first&.serializer
+        end
+
+        def lookup!(element)
+          lookup(element) || raise(ArgumentError,
+                                   "Unknown element type for serialization: #{element.class}. " \
+                                     'Expected a known Markdown model type.')
+        end
+
+        private
+
+        def each_candidate(element)
+          return enum_for(:each_candidate, element) unless block_given?
+
+          walked = element.class.ancestors
+          walked.each do |klass|
+            @entries[klass].sort_by { |e| -e.priority }.each do |entry|
+              next unless entry.serializer.handles?(element)
+
+              yield entry
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative 'context'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Stateful runner: holds a frozen Config + Registry, exposes `#call`.
+      # Each top-level `call` creates a fresh Context (per-document mutable
+      # state) so the same runner can serialize multiple documents without
+      # cross-document leakage.
+      class Runner
+        attr_reader :config, :registry
+
+        def initialize(config:, registry:)
+          @config = config
+          @registry = registry
+        end
+
+        def call(element)
+          ctx = Context.new(config: config, registry: registry, runner: self)
+          result = serialize(element, ctx)
+          result = append_link_refs(result, ctx)
+          append_footnote_defs(result, ctx).to_s
+        end
+
+        def serialize(element, ctx = nil)
+          ctx ||= Context.new(config: config, registry: registry, runner: self)
+          case element
+          when String
+            element
+          when nil
+            ''
+          when Array
+            element.map { |e| serialize(e, ctx) }.join
+          else
+            serializer = registry.lookup(element)
+            if serializer
+              serializer.call(element, ctx)
+            else
+              raise ArgumentError,
+                    "Unknown element type for serialization: #{element.class}. " \
+                      'Expected a known Markdown model type.'
+            end
+          end
+        end
+
+        def serialize_inline(element, ctx)
+          case element
+          when String
+            element
+          when nil
+            ''
+          when ::Coradoc::Markdown::Base, ::Coradoc::Markdown::Document
+            serialize(element, ctx)
+          when Array
+            element.map { |e| serialize_inline(e, ctx) }.join
+          else
+            raise ArgumentError,
+                  "Cannot serialize inline content of type #{element.class}. " \
+                  'Expected String, known inline model, or Base subclass.'
+          end
+        end
+
+        private
+
+        def append_link_refs(result, ctx)
+          return result if ctx.link_refs.empty?
+
+          refs = ctx.link_refs.map do |ref|
+            "[#{ref.id}]: #{ref.url}#{ref.title ? " \"#{ref.title}\"" : ''}"
+          end.join("\n")
+          "#{result}\n\n#{refs}"
+        end
+
+        def append_footnote_defs(result, ctx)
+          return result if ctx.footnote_defs.empty?
+
+          "#{result}\n\n#{ctx.footnote_defs.join("\n")}"
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/abbreviation.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Abbreviation < ElementSerializer
+          handles_type ::Coradoc::Markdown::Abbreviation
+
+          def call(element, _ctx)
+            "*[#{element.term}]: #{element.definition}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/admonition.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+require_relative '../strategies/admonition/registry'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Admonition < ElementSerializer
+          handles_type ::Coradoc::Markdown::Admonition
+
+          def call(element, ctx)
+            Strategies::Admonition::Registry.render(element, ctx: ctx)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/attribute_list.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class AttributeList < ElementSerializer
+          handles_type ::Coradoc::Markdown::AttributeList
+
+          def call(element, _ctx)
+            return '' if element.empty?
+
+            parts = []
+            parts << "##{element.id}" if element.id
+            parts += element.classes.map { |c| ".#{c}" }
+            parts += element.attributes.map { |nv| %(#{nv.name}="#{nv.value}") }
+            "{:#{parts.join(' ')}}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/blockquote.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Blockquote < ElementSerializer
+          handles_type ::Coradoc::Markdown::Blockquote
+
+          def call(element, _ctx)
+            element.content.to_s.lines.map { |line| "> #{line}" }.join
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/code.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Code < ElementSerializer
+          handles_type ::Coradoc::Markdown::Code
+
+          def call(element, _ctx)
+            "`#{element.text}`"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/code_block.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class CodeBlock < ElementSerializer
+          handles_type ::Coradoc::Markdown::CodeBlock
+
+          def call(element, _ctx)
+            "```#{element.language}\n#{element.code}\n```"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/comment.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        # Comments are editorial annotations, not document content. The
+        # Markdown Serialization Spec (§Comments) requires that comments
+        # be suppressed by default.
+        #
+        # Behavior:
+        #   suppress_comments == true  → '' (no output)
+        #   suppress_comments == false → '<!-- text -->'
+        class Comment < ElementSerializer
+          handles_type ::Coradoc::Markdown::Comment
+
+          def call(element, ctx)
+            return '' if ctx.config.suppress_comments
+
+            text = element.text.to_s.strip
+            return '<!---->' if text.empty?
+
+            "<!-- #{text} -->"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/cross_reference.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class CrossReference < ElementSerializer
+          handles_type ::Coradoc::Markdown::CrossReference
+
+          def call(element, _ctx)
+            "[#{element.text}](##{element.target})"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/definition_list.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+require_relative '../strategies/definition_list/registry'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class DefinitionList < ElementSerializer
+          handles_type ::Coradoc::Markdown::DefinitionList
+
+          def call(element, ctx)
+            Strategies::DefinitionList::Registry.render(element, ctx)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/document.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Document < ElementSerializer
+          handles_type ::Coradoc::Markdown::Document
+
+          def call(element, ctx)
+            body = element.blocks.map { |block| ctx.serialize(block) }.join("\n\n")
+            return body unless element.frontmatter && !element.frontmatter.empty?
+
+            "---\n#{element.frontmatter}---\n\n#{body}".strip
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/emphasis.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Emphasis < ElementSerializer
+          handles_type ::Coradoc::Markdown::Emphasis
+
+          def call(element, _ctx)
+            "*#{element.text}*"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/example_block.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        # Example blocks emit an HTML fallback that preserves the caption
+        # as a heading inside `<div class="example">`.
+        #
+        # When `admonition_style == :container` (VitePress), emits
+        # `:::details Caption\n... \n:::` instead.
+        class ExampleBlock < ElementSerializer
+          handles_type ::Coradoc::Markdown::ExampleBlock
+
+          def call(element, ctx)
+            if ctx.config.admonition_style == :container
+              render_container(element)
+            else
+              render_html(element)
+            end
+          end
+
+          private
+
+          def render_html(element)
+            caption_html = element.caption ? %(<h4>Example: #{element.caption}</h4>\n) : ''
+            %(<div class="example">\n#{caption_html}<p>#{element.content.to_s}</p>\n</div>)
+          end
+
+          def render_container(element)
+            title = element.caption ? " Example: #{element.caption}" : ''
+            ":::details#{title}\n#{element.content.to_s}\n:::"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/extension.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Extension < ElementSerializer
+          handles_type ::Coradoc::Markdown::Extension
+
+          def call(element, _ctx)
+            opts = element.options.empty? ? '' : " #{extension_options_to_s(element.options)}"
+            if element.self_closing?
+              "{::#{element.name}#{opts} /}"
+            else
+              "{::#{element.name}#{opts}}#{element.content}{:/}"
+            end
+          end
+
+          private
+
+          def extension_options_to_s(options)
+            options.map { |nv| %(#{nv.name}="#{nv.value}") }.join(' ')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/footnote.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Footnote < ElementSerializer
+          handles_type ::Coradoc::Markdown::Footnote
+
+          def call(element, _ctx)
+            content = element.content.to_s
+            "[^#{element.id}]: #{content}"
+          end
+        end
+      end
+    end
+  end
+end