Module: Coradoc::Html

Defined in:
lib/coradoc/html.rb,
lib/coradoc/html.rb,
lib/coradoc/html/spa.rb,
lib/coradoc/html/drop.rb,
lib/coradoc/html/input.rb,
lib/coradoc/html/theme.rb,
lib/coradoc/html/config.rb,
lib/coradoc/html/escape.rb,
lib/coradoc/html/static.rb,
lib/coradoc/html/version.rb,
lib/coradoc/html/renderer.rb,
lib/coradoc/html/drop/base.rb,
lib/coradoc/html/title_text.rb,
lib/coradoc/html/tag_mapping.rb,
lib/coradoc/html/toc_builder.rb,
lib/coradoc/html/drop/toc_drop.rb,
lib/coradoc/html/asset_resolver.rb,
lib/coradoc/html/converter_base.rb,
lib/coradoc/html/drop/term_drop.rb,
lib/coradoc/html/render_options.rb,
lib/coradoc/html/toc_serializer.rb,
lib/coradoc/html/drop/block_drop.rb,
lib/coradoc/html/drop/image_drop.rb,
lib/coradoc/html/drop/table_drop.rb,
lib/coradoc/html/layout_renderer.rb,
lib/coradoc/html/template_config.rb,
lib/coradoc/html/frontmatter_meta.rb,
lib/coradoc/html/template_caching.rb,
lib/coradoc/html/template_helpers.rb,
lib/coradoc/html/template_locator.rb,
lib/coradoc/html/drop/drop_factory.rb,
lib/coradoc/html/drop/document_drop.rb,
lib/coradoc/html/drop/footnote_drop.rb,
lib/coradoc/html/section_numberable.rb,
lib/coradoc/html/drop/list_item_drop.rb,
lib/coradoc/html/drop/table_row_drop.rb,
lib/coradoc/html/drop/toc_entry_drop.rb,
lib/coradoc/html/drop/annotation_drop.rb,
lib/coradoc/html/drop/list_block_drop.rb,
lib/coradoc/html/drop/table_cell_drop.rb,
lib/coradoc/html/drop/bibliography_drop.rb,
lib/coradoc/html/drop/text_content_drop.rb,
lib/coradoc/html/transform/to_core_model.rb,
lib/coradoc/html/drop/inline_element_drop.rb,
lib/coradoc/html/drop/definition_item_drop.rb,
lib/coradoc/html/drop/definition_list_drop.rb,
lib/coradoc/html/transform/from_core_model.rb,
lib/coradoc/html/drop/bibliography_entry_drop.rb

Defined Under Namespace

Modules: AssetResolver, Config, Drop, Escape, FormatDetection, FrontmatterMeta, SectionNumberable, TagMapping, TemplateCaching, TemplateFilters, Theme, TitleText, Transform Classes: ConverterBase, LayoutRenderer, RenderOptions, Renderer, Spa, Static, TemplateConfig, TemplateLocator, TocBuilder, TocSerializer

Constant Summary collapse

HTML_EXTENSIONS = 
%w[.html .htm].freeze
Input = 
Coradoc::Input::Html
VERSION = 
'1.1.17'

Class Method Summary collapse

Class Method Details

.available_templates ⇒ Object 



83
84
85
 
# File 'lib/coradoc/html/template_config.rb', line 83

def available_templates
  TemplateConfig.available_templates
end

.configuration ⇒ Object 



71
72
73
 
# File 'lib/coradoc/html/template_config.rb', line 71

def configuration
  @configuration ||= TemplateConfig.new
end

.configure {|configuration| ... } ⇒ Object

Yields:



75
76
77
 
# File 'lib/coradoc/html/template_config.rb', line 75

def configure
  yield(configuration) if block_given?
end

.from_core_model(core_document) ⇒ Object

Transform CoreModel to HTML-ready structure

Parameters:

  • core_document (Coradoc::CoreModel::Base) —

    CoreModel document

Returns:

  • (Object) —

    HTML-ready structure



205
206
207
 
# File 'lib/coradoc/html.rb', line 205

def self.from_core_model(core_document)
  Transform::FromCoreModel.transform(core_document)
end

.from_file(filename) ⇒ Object

Parse HTML file



116
117
118
119
 
# File 'lib/coradoc/html.rb', line 116

def self.from_file(filename, **)
  content = File.read(filename)
  parse(content, **)
end

.handles_model?(model) ⇒ Boolean

Check if this format can transform the given model to CoreModel

HTML uses Nokogiri as its model layer. Accepts Nokogiri nodes and CoreModel objects (pass-through).

Parameters:

  • model (Object) —

    The model to check

Returns:

  • (Boolean) —

    true if the model is a Nokogiri node or CoreModel



191
192
193
194
195
 
# File 'lib/coradoc/html.rb', line 191

def self.handles_model?(model)
  model.is_a?(Nokogiri::XML::Node) ||
    model.is_a?(Nokogiri::XML::Document) ||
    model.is_a?(Coradoc::CoreModel::Base)
end

.parse(html, options = {}) ⇒ Object

Parse HTML content and return CoreModel elements (may be an Array)



79
80
81
 
# File 'lib/coradoc/html.rb', line 79

def self.parse(html, options = {})
  ::Coradoc::Input::Html.to_coradoc(html, options)
end

.parse_to_core(html, options = {}) ⇒ Coradoc::CoreModel::DocumentElement

Parse HTML content directly into a CoreModel document

Unlike #parse which returns an Array of CoreModel elements, this wraps the result into a top-level DocumentElement document suitable for use with Coradoc.serialize and other CoreModel pipelines.

Parameters:

  • html (String) —

    HTML content

  • options (Hash) (defaults to: {}) —

    Parse options

Returns:

  • (Coradoc::CoreModel::DocumentElement) —

    CoreModel document



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/coradoc/html.rb', line 92

def self.parse_to_core(html, options = {})
  elements = parse(html, options)

  return elements if elements.is_a?(Coradoc::CoreModel::Base)

  # Extract document title from the first heading element
  title = nil
  children = elements
  if elements.is_a?(Array) && !elements.empty?
    first = elements.first
    if first.is_a?(Coradoc::CoreModel::StructuralElement) &&
       first.section? && first.level == 1
      title = first.title
      children = first.children + elements[1..]
    end
  end

  Coradoc::CoreModel::DocumentElement.new(
    title: title,
    children: Array(children)
  )
end

.reset_configuration! ⇒ Object 



79
80
81
 
# File 'lib/coradoc/html/template_config.rb', line 79

def reset_configuration!
  @configuration = nil
end

.serialize(document, options = {}) ⇒ String

Serialize CoreModel document to HTML

Uses the unified Liquid template renderer.

Parameters:

  • document (Coradoc::CoreModel::Base) —

    CoreModel document to serialize

  • options (Hash) (defaults to: {}) —

    Output options

Returns:

  • (String) —

    HTML output



128
129
130
131
132
133
134
 
# File 'lib/coradoc/html.rb', line 128

def self.serialize(document, options = {})
  validate_core_model!(document)

  layout = options.delete(:layout) || :static
  renderer = Renderer.new(template_dirs: options.delete(:template_dirs))
  renderer.render_html5(document, layout: layout, **options)
end

.serialize_as(document, format, options = {}) ⇒ String

Serialize CoreModel document to HTML with specified format

Parameters:

  • document (Coradoc::CoreModel::Base) —

    CoreModel document to serialize

  • format (Symbol) —

    Output format (:static, :spa, :classic)

  • options (Hash) (defaults to: {}) —

    Converter options

Returns:

  • (String) —

    HTML output



164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/coradoc/html.rb', line 164

def self.serialize_as(document, format, options = {})
  case format.to_sym
  when :static, :html_static, :classic
    serialize_static(document, options)
  when :spa, :html_spa, :modern
    serialize_spa(document, options)
  else
    raise ArgumentError, "Unknown output format: #{format}. " \
                         'Valid formats: :static, :spa'
  end
end

.serialize_spa(document, config = {}) ⇒ String

Serialize CoreModel document to SPA HTML

Uses the modern theme renderer for Vue.js + Tailwind output.

Parameters:

  • document (Coradoc::CoreModel::Base) —

    CoreModel document to serialize

  • config (Hash, Spa::Configuration) (defaults to: {}) —

    SPA converter configuration

Returns:

  • (String) —

    HTML output



154
155
156
 
# File 'lib/coradoc/html.rb', line 154

def self.serialize_spa(document, config = {})
  Spa.convert(document, config)
end

.serialize_static(document, config = {}) ⇒ String

Serialize CoreModel document to static HTML

Uses the classic theme renderer for traditional HTML output.

Parameters:

  • document (Coradoc::CoreModel::Base) —

    CoreModel document to serialize

  • config (Hash, Static::Configuration) (defaults to: {}) —

    Static converter configuration

Returns:

  • (String) —

    HTML output



143
144
145
 
# File 'lib/coradoc/html.rb', line 143

def self.serialize_static(document, config = {})
  Static.convert(document, config)
end

.template_path_for(name) ⇒ Object 



87
88
89
 
# File 'lib/coradoc/html/template_config.rb', line 87

def template_path_for(name)
  TemplateConfig.template_path_for(name)
end

.to_core(document) ⇒ Object 



197
198
199
 
# File 'lib/coradoc/html.rb', line 197

def self.to_core(document)
  to_core_model(document)
end

.to_core_model(document) ⇒ Coradoc::CoreModel::Base

Transform HTML model to CoreModel

Parameters:

  • document (Object) —

    HTML input model

Returns:

  • (Coradoc::CoreModel::Base) —

    CoreModel document



180
181
182
 
# File 'lib/coradoc/html.rb', line 180

def self.to_core_model(document)
  Transform::ToCoreModel.transform(document)
end

.validate_core_model!(document) ⇒ Object

Validate that input is a CoreModel type

Parameters:

  • document (Object) —

    Document to validate

Returns:

  • (Object) —

    The validated document

Raises:

  • (ArgumentError) —

    If document is not a CoreModel type



65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/coradoc/html.rb', line 65

def self.validate_core_model!(document)
  return document if document.nil?

  unless document.is_a?(Coradoc::CoreModel::Base)
    raise ArgumentError,
          'coradoc-html only accepts CoreModel types. ' \
          "Got: #{document.class}. " \
          'Transform your document to CoreModel before passing to HTML conversion.'
  end

  document
end