Module: Coradoc::Html

Defined in:
lib/coradoc/html.rb,
lib/coradoc/html.rb,
lib/coradoc/html.rb,
lib/coradoc/html/spa.rb,
lib/coradoc/html/drop.rb,
lib/coradoc/html/theme.rb,
lib/coradoc/html/config.rb,
lib/coradoc/html/errors.rb,
lib/coradoc/html/escape.rb,
lib/coradoc/html/plugin.rb,
lib/coradoc/html/static.rb,
lib/coradoc/html/cleaner.rb,
lib/coradoc/html/version.rb,
lib/coradoc/html/renderer.rb,
lib/coradoc/html/drop/base.rb,
lib/coradoc/html/converters.rb,
lib/coradoc/html/title_text.rb,
lib/coradoc/html/tag_mapping.rb,
lib/coradoc/html/toc_builder.rb,
lib/coradoc/html/converters/a.rb,
lib/coradoc/html/converters/h.rb,
lib/coradoc/html/converters/p.rb,
lib/coradoc/html/converters/q.rb,
lib/coradoc/html/input_config.rb,
lib/coradoc/html/converters/br.rb,
lib/coradoc/html/converters/dl.rb,
lib/coradoc/html/converters/em.rb,
lib/coradoc/html/converters/hr.rb,
lib/coradoc/html/converters/li.rb,
lib/coradoc/html/converters/ol.rb,
lib/coradoc/html/converters/td.rb,
lib/coradoc/html/converters/tr.rb,
lib/coradoc/html/drop/toc_drop.rb,
lib/coradoc/html/postprocessor.rb,
lib/coradoc/html/asset_resolver.rb,
lib/coradoc/html/converter_base.rb,
lib/coradoc/html/converters/div.rb,
lib/coradoc/html/converters/img.rb,
lib/coradoc/html/converters/pre.rb,
lib/coradoc/html/converters/sub.rb,
lib/coradoc/html/converters/sup.rb,
lib/coradoc/html/drop/term_drop.rb,
lib/coradoc/html/html_converter.rb,
lib/coradoc/html/render_options.rb,
lib/coradoc/html/toc_serializer.rb,
lib/coradoc/html/converters/base.rb,
lib/coradoc/html/converters/code.rb,
lib/coradoc/html/converters/drop.rb,
lib/coradoc/html/converters/head.rb,
lib/coradoc/html/converters/mark.rb,
lib/coradoc/html/converters/math.rb,
lib/coradoc/html/converters/text.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/plugins/plateau.rb,
lib/coradoc/html/template_config.rb,
lib/coradoc/html/converters/aside.rb,
lib/coradoc/html/converters/audio.rb,
lib/coradoc/html/converters/table.rb,
lib/coradoc/html/converters/video.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/converters/bypass.rb,
lib/coradoc/html/converters/figure.rb,
lib/coradoc/html/converters/markup.rb,
lib/coradoc/html/converters/strong.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/converters/blockquote.rb,
lib/coradoc/html/converters/media_base.rb,
lib/coradoc/html/drop/bibliography_drop.rb,
lib/coradoc/html/drop/text_content_drop.rb,
lib/coradoc/html/converters/pass_through.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,
lib/coradoc/html/drop/raw_inline_element_drop.rb,
lib/coradoc/html/converters/positional_formatting.rb

Defined Under Namespace

Modules: AssetResolver, Config, Converters, Drop, Errors, Escape, FormatDetection, FrontmatterMeta, SectionNumberable, TagMapping, TemplateCaching, TemplateFilters, Theme, TitleText, Transform Classes: Cleaner, ConverterBase, HtmlConverter, InputConfig, LayoutRenderer, Plugin, Postprocessor, RenderOptions, Renderer, Spa, Static, TemplateConfig, TemplateLocator, TocBuilder, TocSerializer

Constant Summary collapse

HTML_EXTENSIONS = 
%w[.html .htm].freeze
VERSION = 
'1.1.19'

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

.cleaner ⇒ Object 



35
36
37
 
# File 'lib/coradoc/html.rb', line 35

def self.cleaner
  @cleaner ||= Cleaner.new
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



230
231
232
 
# File 'lib/coradoc/html.rb', line 230

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

.from_file(filename) ⇒ Object

Parse HTML file



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

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



216
217
218
219
220
 
# File 'lib/coradoc/html.rb', line 216

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

.input_config {|@input_config| ... } ⇒ Object

Yields:



25
26
27
28
29
 
# File 'lib/coradoc/html.rb', line 25

def self.input_config
  @input_config ||= InputConfig.new
  yield @input_config if block_given?
  @input_config
end

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

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



104
105
106
 
# File 'lib/coradoc/html.rb', line 104

def self.parse(html, options = {})
  HtmlConverter.to_core_model(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



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/coradoc/html.rb', line 117

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

.reset_input_config! ⇒ Object 



31
32
33
 
# File 'lib/coradoc/html.rb', line 31

def self.reset_input_config!
  @input_config = 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



153
154
155
156
157
158
159
 
# File 'lib/coradoc/html.rb', line 153

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



189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/coradoc/html.rb', line 189

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



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

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



168
169
170
 
# File 'lib/coradoc/html.rb', line 168

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_coradoc(html, options = {}) ⇒ Object 



39
40
41
 
# File 'lib/coradoc/html.rb', line 39

def self.to_coradoc(html, options = {})
  HtmlConverter.to_core_model(html, options)
end

.to_core(document) ⇒ Object 



222
223
224
 
# File 'lib/coradoc/html.rb', line 222

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



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

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



90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/coradoc/html.rb', line 90

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