markdown_composer 0.7.0

data/lib/markdown_composer/registries/registry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  RegistryEntry = MarkdownComposer.value_object(:token, :aliases, :label, :tooltip, :meaning, :row_sentence, :support, :source_formats, :condition_fields) do
+    def supports?(consumer, options = {})
+      value = support.fetch(consumer.to_sym, :disabled).to_sym
+      return true if %i[normal advanced output_only include_only].include?(value)
+      return options.fetch(:optional_tokens, false) if value == :optional
+      return options.fetch(:adapter_policy_tokens, false) if value == :adapter_policy
+
+      false
+    end
+
+    def to_h
+      {
+        token: token,
+        aliases: aliases,
+        label: label,
+        tooltip: tooltip,
+        meaning: meaning,
+        row_sentence: row_sentence,
+        support: support,
+        source_formats: source_formats,
+        condition_fields: condition_fields
+      }
+    end
+  end
+
+  class Registry
+    attr_reader :entries
+
+    def initialize(entries)
+      @entries = entries
+      @by_token = entries.to_h { |entry| [ entry.token, entry ] }
+      @aliases = entries.each_with_object({}) do |entry, map|
+        entry.aliases.each { |alias_token| map[alias_token] = entry.token }
+      end
+    end
+
+    def [](token)
+      @by_token[normalise(token)]
+    end
+
+    def key?(token)
+      !self[token].nil?
+    end
+
+    def fetch(token, default = nil)
+      self[token] || default
+    end
+
+    def normalise(token)
+      value = token.to_s
+      @by_token.key?(value) ? value : @aliases[value]
+    end
+
+    def keys
+      tokens
+    end
+
+    def tokens
+      @by_token.keys
+    end
+
+    def to_a
+      @entries.map(&:to_h)
+    end
+  end
+end

data/lib/markdown_composer/registries/source_entries.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  module SourceRegistryEntries
+    private
+
+    def source_entries
+      [
+        [ "current", [], "Current Source", "Use the main source attached to this composer context." ],
+        [ "explicit", [ "md_doc" ], "Explicit Source", "Use a selected source resolved by the host." ],
+        [ "inherited", [ "effective_md_doc", "block_md_doc", "region_md_doc", "page_md_doc" ], "Inherited Source", "Use a host-resolved inherited source." ],
+        [ "previous", [ "previous_source", "same_source" ], "Previous Source", "Use the effective source reference from the previous Composer row." ],
+        [ "buffer", [ "output", "current_output", "composed_output" ], "Previous Output", "Use the current composition buffer." ],
+        [ "inline", [], "Inline Source", "Use inline content stored in this config." ]
+      ].map { |token, aliases, label, tooltip| RegistryEntry.new(token: token, aliases: aliases, label: label, tooltip: tooltip, meaning: label, row_sentence: nil, support: { source: :normal }, source_formats: %i[markdown html], condition_fields: []) }
+    end
+  end
+end

data/lib/markdown_composer/registries/support_values.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  module RegistrySupportValues
+    private
+
+    def all_normal
+      { select: :normal, include: :normal, target: :normal, scope: :normal }
+    end
+
+    def all_advanced
+      { select: :advanced, include: :advanced, target: :advanced, scope: :advanced }
+    end
+
+    def all_optional
+      { select: :optional, include: :optional, target: :optional, scope: :optional }
+    end
+
+    def all_adapter_policy
+      { select: :adapter_policy, include: :adapter_policy, target: :adapter_policy, scope: :adapter_policy }
+    end
+  end
+end

data/lib/markdown_composer/registries/take_entries.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  module TakeRegistryEntries
+    private
+
+    def take_entries
+      @take_entries ||= [
+        [ "all", [], "All", "Keep every matching unit.", "Keep all matches.", :normal, :none, true ],
+        [ "first", [], "First", "Keep the first N matches.", "Keep first matches.", :normal, :positive_integer, true ],
+        [ "last", [], "Last", "Keep the last N matches.", "Keep last matches.", :normal, :positive_integer, true ],
+        [ "position", [], "Position", "Keep one or more 1-based positions.", "Keep selected positions.", :normal, :integer_list, true ],
+        [ "ranges", [ "range" ], "Range", "Keep one or more inclusive ranges.", "Keep selected ranges.", :normal, :range_list, true ],
+        [ "skip", [], "Skip First", "Ignore the first N matches.", "Skip first matches.", :normal, :positive_integer, true ],
+        [ "skip_last", [], "Skip Last", "Ignore the last N matches.", "Skip last matches.", :normal, :positive_integer, true ],
+        [ "every", [], "Every Nth", "Keep every Nth match.", "Keep periodic matches.", :normal, :positive_integer, true ],
+        [ "odd", [], "Odd", "Keep odd 1-based positions.", "Keep odd positions.", :normal, :none, true ],
+        [ "even", [], "Even", "Keep even 1-based positions.", "Keep even positions.", :normal, :none, true ],
+        [ "except", [], "Except", "Keep all except selected positions.", "Exclude selected positions.", :normal, :integer_list, true ],
+        [ "top_percent", [], "Top Percent", "Keep a percentage from the start.", "Keep top percentage.", :advanced, :percent, true ],
+        [ "bottom_percent", [], "Bottom Percent", "Keep a percentage from the end.", "Keep bottom percentage.", :advanced, :percent, true ],
+        [ "middle", [], "Middle", "Keep N matches from the middle.", "Keep middle matches.", :advanced, :positive_integer, true ],
+        [ "middle_percent", [], "Middle Percent", "Keep a percentage from the middle.", "Keep middle percentage.", :advanced, :percent, true ],
+        [ "alternate", [], "Alternate", "Keep alternating groups of matches.", "Keep alternating groups.", :advanced, :positive_integer, true ],
+        [ "random", [], "Random", "Keep N seeded random matches.", "Keep seeded random matches.", :advanced, :positive_integer, true ]
+      ].map do |token, aliases, label, tooltip, meaning, support, value_type, deterministic|
+        TakeRegistryEntry.new(token: token, aliases: aliases, label: label, tooltip: tooltip, meaning: meaning, support: { take: support }, value_type: value_type, deterministic: deterministic)
+      end
+    end
+  end
+end

data/lib/markdown_composer/registries/take_registry.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  TakeRegistryEntry = MarkdownComposer.value_object(:token, :aliases, :label, :tooltip, :meaning, :support, :value_type, :deterministic) do
+    def to_h
+      {
+        token: token,
+        aliases: aliases,
+        label: label,
+        tooltip: tooltip,
+        meaning: meaning,
+        support: support,
+        value_type: value_type,
+        deterministic: deterministic
+      }
+    end
+  end
+end

data/lib/markdown_composer/registries/target_entries.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  module TargetRegistryEntries
+    private
+
+    def target_entries
+      %w[output start end selector before after between in_place].map do |token|
+        RegistryEntry.new(
+          token: token,
+          aliases: target_aliases(token),
+          label: token.split("_").map(&:capitalize).join(" "),
+          tooltip: target_tooltip(token),
+          meaning: token,
+          row_sentence: nil,
+          support: { target: target_support(token) },
+          source_formats: [],
+          condition_fields: []
+        )
+      end
+    end
+
+    def target_aliases(token)
+      return [ "whole output", "whole_output" ] if token == "output"
+      return [ "in place" ] if token == "in_place"
+
+      []
+    end
+
+    def target_support(token)
+      %w[between in_place].include?(token) ? :advanced : :normal
+    end
+
+    def target_tooltip(token)
+      return "Replace the selected included buffer content inline. Only valid with action modify and source buffer." if token == "in_place"
+
+      "Target #{token}."
+    end
+  end
+end

data/lib/markdown_composer/registries/unit_token_entries.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  module UnitTokenRegistryEntries
+    include RegistrySupportValues
+
+    private
+
+    def unit_token_entries
+      base = canonical_unit_token_definitions
+
+      (1..6).each do |level|
+        base << unit_token("heading_#{level}_section", [ "h#{level}_section" ], "H#{level} Section", "Match H#{level} sections.", "Heading #{level} section.", all_normal)
+        base << unit_token("heading_#{level}", [ "h#{level}" ], "H#{level} Heading", "Match H#{level} heading nodes.", "Heading #{level} node.", all_normal)
+      end
+
+      base.map do |definition|
+        RegistryEntry.new(**definition.merge(row_sentence: nil, source_formats: %i[markdown html], condition_fields: condition_field_entries.map(&:token)))
+      end
+    end
+
+    def canonical_unit_token_definitions
+      [
+        unit_token("all", [], "Whole Source / All", "Use the whole available content.", "Whole source or selected unit.", { select: :normal, include: :normal, target: :disabled, scope: :disabled }),
+        unit_token("output", [], "Output", "Use the whole composed output.", "Composition buffer output.", { select: :disabled, include: :disabled, target: :normal, scope: :output_only }),
+        unit_token("content", [], "Content", "Keep content inside the selected unit.", "Nested content excluding selected heading.", { select: :disabled, include: :include_only, target: :disabled, scope: :advanced }),
+        unit_token("heading_title", [ "title" ], "Heading Title", "Keep only the heading title.", "Section heading node.", { select: :disabled, include: :include_only, target: :advanced, scope: :advanced }),
+        unit_token("section", [ "sections" ], "Section", "Match heading-defined sections at any level.", "Heading-defined section.", all_normal),
+        unit_token("heading", [ "headings" ], "Heading", "Match heading nodes at any level.", "Heading node.", all_normal),
+        unit_token("paragraph", [ "p" ], "Paragraph", "Match paragraph nodes.", "Paragraph node.", all_normal),
+        unit_token("link", [ "a" ], "Link", "Match links.", "Link node.", all_normal),
+        unit_token("image", [ "img" ], "Image", "Match images.", "Image node.", all_normal),
+        unit_token("list", [], "List", "Match list nodes.", "Ordered or unordered list.", all_normal),
+        unit_token("unordered_list", [ "ul" ], "Unordered List", "Match bullet lists.", "Unordered list node.", all_normal),
+        unit_token("ordered_list", [ "ol" ], "Ordered List", "Match numbered lists.", "Ordered list node.", all_normal),
+        unit_token("list_item", [ "li" ], "List Item", "Match list items.", "List item node.", all_normal),
+        unit_token("blockquote", [], "Blockquote", "Match blockquotes.", "Block quote node.", all_normal),
+        unit_token("table", [], "Table", "Match whole tables.", "Table node.", all_normal),
+        unit_token("table_head", [ "thead" ], "Table Head", "Match table header groups.", "Table header group.", all_advanced),
+        unit_token("table_body", [ "tbody" ], "Table Body", "Match table body groups.", "Table body group.", all_advanced),
+        unit_token("table_row", [ "tr" ], "Table Row", "Match table rows.", "Table row.", all_advanced),
+        unit_token("table_header", [ "th" ], "Header Cell", "Match table header cells.", "Table header cell.", all_advanced),
+        unit_token("table_cell", [ "td" ], "Table Cell", "Match table cells.", "Table cell.", all_advanced),
+        unit_token("code_block", [], "Code Block", "Match fenced or block code.", "Code block.", all_normal),
+        unit_token("inline_code", [], "Inline Code", "Match inline code spans.", "Inline code.", all_normal),
+        unit_token("data_block", [], "Data Block", "Match structured YAML/JSON blocks.", "Structured data block.", { select: :normal, include: :normal, target: :advanced, scope: :advanced }),
+        unit_token("data_path", [], "Data Path", "Keep a structured data path.", "Structured data path.", { select: :disabled, include: :include_only, target: :disabled, scope: :advanced }),
+        unit_token("data_record", [], "Data Record", "Match composed data records.", "Structured output record.", { select: :disabled, include: :disabled, target: :advanced, scope: :output_only }),
+        unit_token("data_value", [], "Data Value", "Match composed data values.", "Structured output value.", { select: :disabled, include: :disabled, target: :advanced, scope: :output_only }),
+        unit_token("mermaid", [], "Mermaid", "Match Mermaid diagrams.", "Mermaid diagram.", all_normal),
+        unit_token("math_block", [], "Math Block", "Match display math blocks.", "Display math.", all_normal),
+        unit_token("inline_math", [], "Inline Math", "Match inline math spans.", "Inline math.", all_normal),
+        unit_token("comment", [], "Comment", "Match comments.", "HTML comment.", all_normal),
+        unit_token("raw_html", [], "Raw HTML", "Match raw HTML nodes.", "Raw HTML node.", all_adapter_policy)
+      ]
+    end
+
+    def unit_token(token, aliases, label, tooltip, meaning, support)
+      { token: token, aliases: aliases, label: label, tooltip: tooltip, meaning: meaning, support: support }
+    end
+  end
+end

data/lib/markdown_composer/registries/where_registry.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  ConditionFieldRegistryEntry = MarkdownComposer.value_object(:token, :aliases, :label, :tooltip, :meaning, :predicates, :applies_to, :source_formats, :field_take) do
+    def to_h
+      {
+        token: token,
+        aliases: aliases,
+        label: label,
+        tooltip: tooltip,
+        meaning: meaning,
+        predicates: predicates,
+        applies_to: applies_to,
+        source_formats: source_formats,
+        field_take: field_take
+      }
+    end
+  end
+
+  PredicateRegistryEntry = MarkdownComposer.value_object(:token, :aliases, :label, :tooltip, :meaning, :value_type, :support) do
+    def to_h
+      {
+        token: token,
+        aliases: aliases,
+        label: label,
+        tooltip: tooltip,
+        meaning: meaning,
+        value_type: value_type,
+        support: support
+      }
+    end
+  end
+
+  WhereGroupRegistryEntry = MarkdownComposer.value_object(:token, :aliases, :label, :tooltip, :meaning, :arity) do
+    def to_h
+      {
+        token: token,
+        aliases: aliases,
+        label: label,
+        tooltip: tooltip,
+        meaning: meaning,
+        arity: arity
+      }
+    end
+  end
+
+  class WhereRegistry
+    attr_reader :fields, :predicates, :groups
+
+    def initialize(fields:, predicates:, groups:)
+      @fields = Registry.new(fields)
+      @predicates = Registry.new(predicates)
+      @groups = Registry.new(groups)
+    end
+
+    def field?(token)
+      fields.key?(token)
+    end
+
+    def predicate?(token)
+      predicates.key?(token)
+    end
+
+    def group?(token)
+      groups.key?(token)
+    end
+
+    def predicates_for(field)
+      fields[field]&.predicates || []
+    end
+
+    def condition_map
+      fields.entries.to_h { |entry| [ entry.token, entry.predicates ] }
+    end
+
+    def to_h
+      {
+        fields: fields.to_a,
+        predicates: predicates.to_a,
+        groups: groups.to_a
+      }
+    end
+  end
+end

data/lib/markdown_composer/registries.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "registries/registry"
+require_relative "registries/take_registry"
+require_relative "registries/where_registry"
+require_relative "registries/support_values"
+require_relative "registries/unit_token_entries"
+require_relative "registries/source_entries"
+require_relative "registries/action_entries"
+require_relative "registries/target_entries"
+require_relative "registries/take_entries"
+require_relative "registries/condition_entries"
+require_relative "transforms/default_entries"
+
+module MarkdownComposer
+  class Registries
+    include UnitTokenRegistryEntries
+    include SourceRegistryEntries
+    include ActionRegistryEntries
+    include TargetRegistryEntries
+    include TakeRegistryEntries
+    include WhereRegistryEntries
+    include DefaultTransformEntries
+
+    attr_reader :unit_tokens, :sources, :actions, :targets, :transforms, :take,
+      :where, :condition_fields, :predicates, :where_groups, :conditions
+
+    def self.default
+      @default ||= new
+    end
+
+    def initialize
+      @unit_tokens = Registry.new(unit_token_entries)
+      @sources = Registry.new(source_entries)
+      @actions = Registry.new(action_entries)
+      @targets = Registry.new(target_entries)
+      @transforms = Registry.new(transform_entries)
+      @take = Registry.new(take_entries)
+      @condition_fields = Registry.new(condition_field_entries)
+      @predicates = Registry.new(predicate_entries)
+      @where_groups = Registry.new(where_group_entries)
+      @where = WhereRegistry.new(fields: condition_field_entries, predicates: predicate_entries, groups: where_group_entries)
+      @conditions = @where.condition_map
+    end
+  end
+end

data/lib/markdown_composer/result.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  class Result
+    attr_reader :output, :buffer, :markdown, :html, :diagnostics, :errors, :stages
+
+    def initialize(output:, buffer:, markdown:, html:, diagnostics:, errors:, stages: {})
+      @output = output
+      @buffer = buffer
+      @markdown = markdown
+      @html = html
+      @diagnostics = diagnostics
+      @errors = errors
+      @stages = stages
+    end
+
+    def success?
+      errors.empty?
+    end
+
+    def to_h
+      {
+        success: success?,
+        output: output,
+        buffer: buffer&.to_h,
+        markdown: markdown,
+        html: html,
+        diagnostics: diagnostics.map(&:to_h),
+        errors: errors.map(&:to_h),
+        stages: stages
+      }
+    end
+  end
+end

data/lib/markdown_composer/selection_resolver.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  class SelectionResolver
+    attr_reader :index, :options, :diagnostics, :path
+
+    def initialize(index:, options: {}, diagnostics: Diagnostics.new, path: nil)
+      @index = index
+      @options = options
+      @diagnostics = diagnostics
+      @path = path
+    end
+
+    def resolve(selector, within: nil)
+      selector ||= { "type" => "all" }
+      matches = if selector["types"]
+        selector["types"].flat_map { |type| matches_for(type, within: within) }.uniq(&:id)
+      else
+        matches_for(selector["type"] || "all", within: within)
+      end
+      matches = apply_where(matches, selector["where"]) if selector["where"]
+      matches = Take.apply(matches, selector["take"], diagnostics: diagnostics, path: path, seed: options.fetch(:seed, 0)) if selector["take"]
+      diagnostics.warn("selection.empty", "Selection matched no content", path: path) if matches.empty?
+      matches
+    end
+
+    def resolve_with_includes(selector, include_config)
+      resolve(selector).flat_map do |unit|
+        include_units(unit, include_config || [ { "type" => "all" } ])
+      end.uniq(&:id).sort_by(&:source_position)
+    end
+
+    def include_units(unit, include_config)
+      included = []
+      excluded = []
+
+      Array(include_config).each do |item|
+        if item["exclude"]
+          excluded.concat(resolve_nested(unit, item["exclude"]))
+        else
+          included.concat(resolve_nested(unit, item))
+        end
+      end
+
+      (included - excluded).uniq(&:id).sort_by(&:source_position)
+    end
+
+    private
+
+    def resolve_nested(unit, item)
+      type = item["type"] || "all"
+      matches = case type
+      when "all"
+        emit_all(unit)
+      when "content"
+        nested_nodes(unit, include_heading: false)
+      when "heading_title"
+        unit.respond_to?(:heading_node) ? [ unit.heading_node ].compact : []
+      when "data_path"
+        DataPath.resolve(unit, item["path"], diagnostics: diagnostics, diagnostic_path: path)
+      else
+        matches_for(type, within: unit)
+      end
+      matches = apply_where(matches, item["where"]) if item["where"]
+      matches = Take.apply(matches, item["take"], diagnostics: diagnostics, path: path, seed: options.fetch(:seed, 0)) if item["take"]
+
+      if item["include"]
+        matches.flat_map { |match| include_units(match, item["include"]) }
+      else
+        matches.flat_map { |match| expand_unit(match) }
+      end
+    end
+
+    def matches_for(type, within:)
+      type = Registries.default.unit_tokens.normalise(type) || type.to_s
+      if type == "all"
+        return within ? emit_all(within) : [ *index.root.body_nodes, *index.root.child_sections ]
+      end
+
+      collection = within ? nested_candidates(within) : all_candidates
+      if type == "section"
+        section_candidates(within)
+      elsif type == "heading"
+        heading_candidates(within)
+      elsif section_token?(type)
+        level = type[/heading_(\d)_section/, 1].to_i
+        collection.select { |unit| unit.respond_to?(:heading_node) && unit.level == level }
+      elsif heading_token?(type)
+        level = type[/heading_(\d)/, 1].to_i
+        collection.select { |unit| unit.is_a?(ComposerNode) && unit.type == "heading_#{level}" }
+      elsif type == "list"
+        collection.select { |unit| unit.is_a?(ComposerNode) && %w[ordered_list unordered_list].include?(unit.type) }
+      else
+        collection.select { |unit| unit.is_a?(ComposerNode) && unit.type == type }
+      end
+    end
+
+    def all_candidates
+      [ *index.sections, *index.nodes, *index.nodes.flat_map(&:children) ].flatten
+    end
+
+    def section_candidates(within)
+      sections = if within.nil?
+        index.sections
+      elsif within.respond_to?(:child_sections)
+        descendant_sections(within)
+      else
+        []
+      end
+
+      sections.compact.uniq(&:id).sort_by(&:source_position)
+    end
+
+    def descendant_sections(section)
+      section.child_sections.flat_map { |child| [ child, *descendant_sections(child) ] }
+    end
+
+    def heading_candidates(within)
+      nodes = if within.nil?
+        index.nodes
+      elsif within.respond_to?(:heading_node)
+        [ *within.all_nodes, *within.all_nodes.flat_map(&:children) ].flatten
+      elsif within.is_a?(ComposerNode)
+        [ within, *within.children ]
+      else
+        []
+      end
+
+      nodes.compact.uniq(&:id).select { |unit| unit.is_a?(ComposerNode) && unit.heading? }.sort_by(&:source_position)
+    end
+
+    def nested_candidates(unit)
+      return all_candidates unless unit
+      return unit.children if unit.is_a?(ComposerNode) && unit.children.any?
+      return [] unless unit.respond_to?(:heading_node)
+
+      [ *unit.child_sections, *unit.body_nodes, *unit.all_nodes, *unit.all_nodes.flat_map(&:children) ].flatten.compact.uniq(&:id)
+    end
+
+    def nested_nodes(unit, include_heading:)
+      if unit.respond_to?(:heading_node)
+        nodes = []
+        nodes << unit.heading_node if include_heading && unit.heading_node
+        nodes.concat(unit.body_nodes.reject { |node| derived_node?(node) })
+        unit.child_sections.each { |child| nodes.concat(nested_nodes(child, include_heading: true)) }
+        nodes.compact.uniq(&:id).sort_by(&:source_position)
+      elsif unit.is_a?(ComposerNode)
+        [ unit ]
+      else
+        []
+      end
+    end
+
+    def emit_all(unit)
+      expand_unit(unit)
+    end
+
+    def expand_unit(unit)
+      nested_nodes(unit, include_heading: true)
+    end
+
+    def derived_node?(node)
+      node.respond_to?(:attributes) && node.attributes["derived"]
+    end
+
+    def apply_where(matches, where)
+      total = matches.length
+      matches.each_with_index.select do |(unit, index)|
+        Where.match?(unit, where, position: index + 1, total: total, options: options)
+      end.map(&:first)
+    end
+
+    def section_token?(type)
+      type.match?(/\Aheading_[1-6]_section\z/)
+    end
+
+    def heading_token?(type)
+      type.match?(/\Aheading_[1-6]\z/)
+    end
+  end
+end

data/lib/markdown_composer/source.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  class Source
+    attr_reader :key, :type, :title, :markdown, :html, :preferred_format, :metadata
+
+    def self.build(value)
+      value.is_a?(Source) ? value : new(**symbolize(value))
+    end
+
+    def self.symbolize(value)
+      value.to_h.transform_keys(&:to_sym)
+    end
+
+    def initialize(key:, type: "explicit", title: nil, markdown: nil, html: nil, preferred_format: :markdown, metadata: {})
+      @key = key.to_s
+      @type = type.to_s
+      @title = title
+      @markdown = markdown
+      @html = html
+      @preferred_format = preferred_format.to_sym
+      @metadata = metadata || {}
+    end
+
+    def format
+      return :html if preferred_format == :html && html_present?
+      return :markdown if markdown_present?
+      return :html if html_present?
+
+      preferred_format
+    end
+
+    def content
+      format == :html ? html.to_s : markdown.to_s
+    end
+
+    def markdown_present?
+      !markdown.to_s.empty?
+    end
+
+    def html_present?
+      !html.to_s.empty?
+    end
+
+    def to_h
+      {
+        key: key,
+        type: type,
+        title: title,
+        markdown: markdown,
+        html: html,
+        preferred_format: preferred_format,
+        metadata: metadata
+      }.compact
+    end
+  end
+end