asciidoctor-epub3 1.5.0.alpha.14 → 1.5.0.alpha.19

data/lib/asciidoctor-epub3/converter.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'mime/types'
 require 'open3'
 require_relative 'font_icon_map'
 
@@ -29,7 +30,7 @@ module Asciidoctor
                 unless (entry_dir = ::File.dirname entry.name) == '.' || (::File.directory? entry_dir)
                   ::FileUtils.mkdir_p entry_dir
                 end
-                entry.extract
+                entry.extract entry.name
               end
             end
           end
@@ -38,9 +39,9 @@ module Asciidoctor
 
         if @format == :kf8
           # QUESTION shouldn't we validate this epub file too?
-          distill_epub_to_mobi epub_file, target, @compress, @kindlegen_path
+          distill_epub_to_mobi epub_file, target, @compress
         elsif @validate
-          validate_epub epub_file, @epubcheck_path
+          validate_epub epub_file
         end
       end
 
@@ -105,16 +106,45 @@ module Asciidoctor
           send method_name, node
         else
           logger.warn %(conversion missing in backend #{@backend} for #{name})
+          nil
         end
       end
 
       # See https://asciidoctor.org/docs/user-manual/#book-parts-and-chapters
       def get_chapter_name node
         if node.document.doctype != 'book'
-          return Asciidoctor::Document === node ? node.attr('docname') : nil
+          return Asciidoctor::Document === node ? node.attr('docname') || node.id : nil
         end
         return (node.id || 'preamble') if node.context == :preamble && node.level == 0
-        Asciidoctor::Section === node && node.level <= 1 ? node.id : nil
+        chapter_level = [node.document.attr('epub-chapter-level', 1).to_i, 1].max
+        Asciidoctor::Section === node && node.level <= chapter_level ? node.id : nil
+      end
+
+      def get_numbered_title node
+        doc_attrs = node.document.attributes
+        level = node.level
+        if node.caption
+          title = node.captioned_title
+        elsif node.respond_to?(:numbered) && node.numbered && level <= (doc_attrs['sectnumlevels'] || 3).to_i
+          if level < 2 && node.document.doctype == 'book'
+            if node.sectname == 'chapter'
+              title = %(#{(signifier = doc_attrs['chapter-signifier']) ? "#{signifier} " : ''}#{node.sectnum} #{node.title})
+            elsif node.sectname == 'part'
+              title = %(#{(signifier = doc_attrs['part-signifier']) ? "#{signifier} " : ''}#{node.sectnum nil, ':'} #{node.title})
+            else
+              title = %(#{node.sectnum} #{node.title})
+            end
+          else
+            title = %(#{node.sectnum} #{node.title})
+          end
+        else
+          title = node.title
+        end
+        title
+      end
+
+      def icon_names
+        @icon_names ||= []
       end
 
       def convert_document node
@@ -126,8 +156,7 @@ module Asciidoctor
         @kindlegen_path = node.attr 'ebook-kindlegen-path'
         @epubcheck_path = node.attr 'ebook-epubcheck-path'
         @xrefs_seen = ::Set.new
-        @icon_names = []
-        @images = []
+        @media_files = {}
         @footnotes = []
 
         @book = GEPUB::Book.new 'EPUB/package.opf'
@@ -182,41 +211,75 @@ module Asciidoctor
           @book.metadata.add_metadata 'subject', s
         end
 
-        add_cover_image node
-        add_front_matter_page node
+        if node.attr? 'series-name'
+          series_name = node.attr 'series-name'
+          series_volume = node.attr 'series-volume', 1
+          series_id = node.attr 'series-id'
+
+          series_meta = @book.metadata.add_metadata 'meta', series_name, id: 'pub-collection', group_position: series_volume
+          series_meta['property'] = 'belongs-to-collection'
+          series_meta.refine 'dcterms:identifier', series_id unless series_id.nil?
+          # Calibre only understands 'series'
+          series_meta.refine 'collection-type', 'series'
+        end
+
+        # For list of supported landmark types see
+        # https://idpf.github.io/epub-vocabs/structure/
+        landmarks = []
+
+        cover_page = add_cover_page node
+        landmarks << { type: 'cover', href: cover_page.href, title: 'Cover' } unless cover_page.nil?
+
+        front_matter_page = add_front_matter_page node
+        landmarks << { type: 'frontmatter', href: front_matter_page.href, title: 'Front Matter' } unless front_matter_page.nil?
+
+        nav_item = @book.add_item('nav.xhtml', id: 'nav').nav
+
+        toclevels = [(node.attr 'toclevels', 1).to_i, 0].max
+        outlinelevels = [(node.attr 'outlinelevels', toclevels).to_i, 0].max
+
+        if node.attr? 'toc'
+          toc_item = @book.add_ordered_item 'toc.xhtml', id: 'toc'
+          landmarks << { type: 'toc', href: toc_item.href, title: node.attr('toc-title') }
+        else
+          toc_item = nil
+        end
 
         if node.doctype == 'book'
-          toc_items = []
-          node.sections.each do |section|
-            toc_items << section
-            section.sections.each do |subsection|
-              next if get_chapter_name(node).nil?
-              toc_items << subsection
-            end
-          end
+          toc_items = node.sections
           node.content
         else
           toc_items = [node]
           add_chapter node
         end
 
-        nav_xhtml = @book.add_item 'nav.xhtml', content: postprocess_xhtml(nav_doc(node, toc_items)), id: 'nav'
-        nav_xhtml.nav
+        landmarks << { type: 'bodymatter', href: %(#{get_chapter_name toc_items[0]}.xhtml), title: 'Start of Content' } unless toc_items.empty?
+
+        toc_items.each do |item|
+          landmarks << { type: item.style, href: %(#{get_chapter_name item}.xhtml), title: item.title } if %w(appendix bibliography glossary index preface).include? item.style
+        end
+
+        nav_item.add_content postprocess_xhtml(nav_doc(node, toc_items, landmarks, outlinelevels))
+        # User is not supposed to see landmarks, so pass empty array here
+        toc_item&.add_content postprocess_xhtml(nav_doc(node, toc_items, [], toclevels))
 
         # NOTE gepub doesn't support building a ncx TOC with depth > 1, so do it ourselves
-        toc_ncx = ncx_doc node, toc_items
+        toc_ncx = ncx_doc node, toc_items, outlinelevels
         @book.add_item 'toc.ncx', content: toc_ncx.to_ios, id: 'ncx'
 
         docimagesdir = (node.attr 'imagesdir', '.').chomp '/'
         docimagesdir = (docimagesdir == '.' ? nil : %(#{docimagesdir}/))
 
-        @images.each do |image|
-          if image[:name].start_with? %(#{docimagesdir}jacket/cover.)
-            logger.warn %(image path is reserved for cover artwork: #{image[:name]}; skipping image found in content)
-          elsif ::File.readable? image[:path]
-            @book.add_item image[:name], content: image[:path]
+        @media_files.each do |name, file|
+          if name.start_with? %(#{docimagesdir}jacket/cover.)
+            logger.warn %(path is reserved for cover artwork: #{name}; skipping file found in content)
+          elsif file[:path].nil? || File.readable?(file[:path])
+            mime_types = MIME::Types.type_for name
+            mime_types.delete_if {|x| x.media_type != file[:media_type] }
+            preferred_mime_type = mime_types.empty? ? nil : mime_types[0].content_type
+            @book.add_item name, content: file[:path], media_type: preferred_mime_type
           else
-            logger.error %(#{File.basename node.attr('docfile')}: image not found or not readable: #{image[:path]})
+            logger.error %(#{File.basename node.attr('docfile')}: media file not found or not readable: #{file[:path]})
           end
         end
 
@@ -267,25 +330,22 @@ module Asciidoctor
 
         chapter_item = @book.add_ordered_item %(#{docid}.xhtml)
 
-        if node.context == :document && (doctitle = node.doctitle partition: true, use_fallback: true).subtitle?
+        doctitle = node.document.doctitle partition: true, use_fallback: true
+        chapter_title = doctitle.combined
+
+        if node.context == :document && doctitle.subtitle?
           title = %(#{doctitle.main} )
           subtitle = doctitle.subtitle
         elsif node.title
           # HACK: until we get proper handling of title-only in CSS
           title = ''
-          subtitle = node.title
+          subtitle = get_numbered_title node
+          chapter_title = subtitle
         else
           title = nil
           subtitle = nil
         end
 
-        doctitle_sanitized = (node.document.doctitle sanitize: true, use_fallback: true).to_s
-
-        # By default, Kindle does not allow the line height to be adjusted.
-        # But if you float the elements, then the line height disappears and can be restored manually using margins.
-        # See https://github.com/asciidoctor/asciidoctor-epub3/issues/123
-        subtitle_formatted = subtitle ? subtitle.split.map {|w| %(<b>#{w}</b>) } * ' ' : nil
-
         if node.document.doctype == 'book'
           byline = ''
         else
@@ -303,10 +363,10 @@ module Asciidoctor
 
         # NOTE must run after content is resolved
         # TODO perhaps create dynamic CSS file?
-        if @icon_names.empty?
+        if icon_names.empty?
           icon_css_head = ''
         else
-          icon_defs = @icon_names.map {|name|
+          icon_defs = icon_names.map {|name|
             %(.i-#{name}::before { content: "#{FontIconMap.unicode name}"; })
           } * LF
           icon_css_head = %(<style>
@@ -317,16 +377,20 @@ module Asciidoctor
 
         header = (title || subtitle) ? %(<header>
 <div class="chapter-header">
-#{byline}<h1 class="chapter-title">#{title}#{subtitle ? %(<small class="subtitle">#{subtitle_formatted}</small>) : ''}</h1>
+#{byline}<h1 class="chapter-title">#{title}#{subtitle ? %(<small class="subtitle">#{subtitle}</small>) : ''}</h1>
 </div>
 </header>) : ''
 
+        # We want highlighter CSS to be stored in a separate file
+        # in order to avoid style duplication across chapter files
+        linkcss = true
+
         # NOTE kindlegen seems to mangle the <header> element, so we wrap its content in a div
         lines = [%(<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="#{lang = node.document.attr 'lang', 'en'}" lang="#{lang}">
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:mml="http://www.w3.org/1998/Math/MathML" xml:lang="#{lang = node.document.attr 'lang', 'en'}" lang="#{lang}">
 <head>
 <meta charset="UTF-8"/>
-<title>#{doctitle_sanitized}</title>
+<title>#{chapter_title}</title>
 <link rel="stylesheet" type="text/css" href="styles/epub3.css"/>
 <link rel="stylesheet" type="text/css" href="styles/epub3-css3-only.css" media="(min-device-width: 0px)"/>
 #{icon_css_head}<script type="text/javascript"><![CDATA[
@@ -337,12 +401,18 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
   }
   document.body.setAttribute('class', reader.name.toLowerCase().replace(/ /g, '-'));
 });
-]]></script>
-</head>
+]]></script>)]
+
+        syntax_hl = node.document.syntax_highlighter
+        epub_type_attr = node.respond_to?(:section) && node.sectname != 'section' ? %( epub:type="#{node.sectname}") : ''
+
+        lines << (syntax_hl.docinfo :head, node, linkcss: linkcss, self_closing_tag_slash: '/') if syntax_hl&.docinfo? :head
+
+        lines << %(</head>
 <body>
-<section class="chapter" title="#{doctitle_sanitized.gsub '"', '&quot;'}" epub:type="chapter" id="#{docid}">
+<section class="chapter" title=#{chapter_title.encode xml: :attr}#{epub_type_attr} id="#{docid}">
 #{header}
-#{content})]
+        #{content})
 
         unless (fns = node.document.footnotes - @footnotes).empty?
           @footnotes += fns
@@ -361,8 +431,11 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 </footer>'
         end
 
-        lines << '</section>
-</body>
+        lines << '</section>'
+
+        lines << (syntax_hl.docinfo :footer, node.document, linkcss: linkcss, self_closing_tag_slash: '/') if syntax_hl&.docinfo? :footer
+
+        lines << '</body>
 </html>'
 
         chapter_item.add_content postprocess_xhtml lines * LF
@@ -378,11 +451,10 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       def convert_section node
         if add_chapter(node).nil?
           hlevel = node.level
-          epub_type_attr = node.special ? %( epub:type="#{node.sectname}") : ''
+          epub_type_attr = node.sectname != 'section' ? %( epub:type="#{node.sectname}") : ''
           div_classes = [%(sect#{node.level}), node.role].compact
-          title = node.title
-          title_sanitized = xml_sanitize title
-          %(<section class="#{div_classes * ' '}" title="#{title_sanitized}"#{epub_type_attr}>
+          title = get_numbered_title node
+          %(<section class="#{div_classes * ' '}" title=#{title.encode xml: :attr}#{epub_type_attr}>
 <h#{hlevel} id="#{node.id}">#{title}</h#{hlevel}>#{(content = node.content).empty? ? '' : %(
           #{content})}
 </section>)
@@ -427,15 +499,16 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       end
 
       def convert_paragraph node
+        id_attr = node.id ? %( id="#{node.id}") : ''
         role = node.role
         # stack-head is the alternative to the default, inline-head (where inline means "run-in")
         head_stop = node.attr 'head-stop', (role && (node.has_role? 'stack-head') ? nil : '.')
         head = node.title? ? %(<strong class="head">#{title = node.title}#{head_stop && title !~ TrailingPunctRx ? head_stop : ''}</strong> ) : ''
         if role
           node.set_option 'hardbreaks' if node.has_role? 'signature'
-          %(<p class="#{role}">#{head}#{node.content}</p>)
+          %(<p#{id_attr} class="#{role}">#{head}#{node.content}</p>)
         else
-          %(<p>#{head}#{node.content}</p>)
+          %(<p#{id_attr}>#{head}#{node.content}</p>)
         end
       end
 
@@ -464,14 +537,12 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         type = node.attr 'name'
         epub_type = case type
                     when 'tip'
-                      'help'
-                    when 'note'
-                      'note'
-                    when 'important', 'warning', 'caution'
-                      'warning'
+                      'tip'
+                    when 'important', 'warning', 'caution', 'note'
+                      'notice'
                     else
                       logger.warn %(unknown admonition type: #{type})
-                      'note'
+                      'notice'
                     end
         %(<aside#{id_attr} class="admonition #{type}"#{title_attr} epub:type="#{epub_type}">
 #{title_el}<div class="content">
@@ -498,22 +569,64 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       end
 
       def convert_listing node
+        id_attribute = node.id ? %( id="#{node.id}") : ''
+        nowrap = (node.option? 'nowrap') || !(node.document.attr? 'prewrap')
+        if node.style == 'source'
+          lang = node.attr 'language'
+          syntax_hl = node.document.syntax_highlighter
+          if syntax_hl
+            opts = syntax_hl.highlight? ? {
+              css_mode: ((doc_attrs = node.document.attributes)[%(#{syntax_hl.name}-css)] || :class).to_sym,
+              style: doc_attrs[%(#{syntax_hl.name}-style)],
+            } : {}
+            opts[:nowrap] = nowrap
+          else
+            pre_open = %(<pre class="highlight#{nowrap ? ' nowrap' : ''}"><code#{lang ? %( class="language-#{lang}" data-lang="#{lang}") : ''}>)
+            pre_close = '</code></pre>'
+          end
+        else
+          pre_open = %(<pre#{nowrap ? ' class="nowrap"' : ''}>)
+          pre_close = '</pre>'
+          syntax_hl = nil
+        end
         figure_classes = ['listing']
         figure_classes << 'coalesce' if node.option? 'unbreakable'
-        pre_classes = node.style == 'source' ? ['source', %(language-#{node.attr 'language'})] : ['screen']
-        title_div = node.title? ? %(<figcaption>#{node.captioned_title}</figcaption>
-) : ''
-        %(<figure class="#{figure_classes * ' '}">
-#{title_div}<pre class="#{pre_classes * ' '}"><code>#{node.content}</code></pre>
+        title_div = node.title? ? %(<figcaption>#{node.captioned_title}</figcaption>) : ''
+        %(<figure#{id_attribute} class="#{figure_classes * ' '}">#{title_div}
+        #{syntax_hl ? (syntax_hl.format node, lang, opts) : pre_open + (node.content || '') + pre_close}
+</figure>)
+      end
+
+      def convert_stem node
+        return convert_listing node if node.style != 'asciimath' || !asciimath_available?
+
+        id_attr = node.id ? %( id="#{node.id}") : ''
+        title_element = node.title? ? %(<figcaption>#{node.captioned_title}</figcaption>) : ''
+        equation_data = AsciiMath.parse(node.content).to_mathml 'mml:'
+
+        %(<figure#{id_attr} class="#{prepend_space node.role}">
+#{title_element}
+<div class="content">
+#{equation_data}
+</div>
 </figure>)
       end
 
-      # TODO: implement proper stem support. See https://github.com/asciidoctor/asciidoctor-epub3/issues/10
-      alias convert_stem convert_listing
+      def asciimath_available?
+        (@asciimath_status ||= load_asciimath) == :loaded
+      end
+
+      def load_asciimath
+        Helpers.require_library('asciimath', true, :warn).nil? ? :unavailable : :loaded
+      end
 
-      # QUESTION should we wrap the <pre> in either <div> or <figure>?
       def convert_literal node
-        %(<pre class="screen">#{node.content}</pre>)
+        id_attribute = node.id ? %( id="#{node.id}") : ''
+        title_element = node.title? ? %(<figcaption>#{node.captioned_title}</figcaption>) : ''
+        %(<figure#{id_attribute} class="literalblock#{prepend_space node.role}">
+#{title_element}
+<div class="content"><pre class="screen">#{node.content}</pre></div>
+</figure>)
       end
 
       def convert_page_break _node
@@ -595,41 +708,34 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         lines = [%(<div class="table">)]
         lines << %(<div class="content">)
         table_id_attr = node.id ? %( id="#{node.id}") : ''
-        frame_class = {
-          'all' => 'table-framed',
-          'topbot' => 'table-framed-topbot',
-          'sides' => 'table-framed-sides',
-          'none' => '',
-        }
-        grid_class = {
-          'all' => 'table-grid',
-          'rows' => 'table-grid-rows',
-          'cols' => 'table-grid-cols',
-          'none' => '',
-        }
-        table_classes = %W[table #{frame_class[node.attr 'frame'] || frame_class['topbot']} #{grid_class[node.attr 'grid'] || grid_class['rows']}]
+        table_classes = [
+          'table',
+          %(table-framed-#{node.attr 'frame', 'rows', 'table-frame'}),
+          %(table-grid-#{node.attr 'grid', 'rows', 'table-grid'}),
+        ]
         if (role = node.role)
           table_classes << role
         end
-        table_class_attr = %( class="#{table_classes * ' '}")
         table_styles = []
-        table_styles << %(width: #{node.attr 'tablepcwidth'}%) unless (node.option? 'autowidth') && !(node.attr? 'width', nil, false)
+        if (autowidth = node.option? 'autowidth') && !(node.attr? 'width')
+          table_classes << 'fit-content'
+        else
+          table_styles << %(width: #{node.attr 'tablepcwidth'}%;)
+        end
+        table_class_attr = %( class="#{table_classes * ' '}")
         table_style_attr = !table_styles.empty? ? %( style="#{table_styles * '; '}") : ''
 
         lines << %(<table#{table_id_attr}#{table_class_attr}#{table_style_attr}>)
         lines << %(<caption>#{node.captioned_title}</caption>) if node.title?
         if (node.attr 'rowcount') > 0
           lines << '<colgroup>'
-          #if node.option? 'autowidth'
-          tag = %(<col/>)
-          node.columns.size.times do
-            lines << tag
+          if autowidth
+            lines += (Array.new node.columns.size, %(<col/>))
+          else
+            node.columns.each do |col|
+              lines << ((col.option? 'autowidth') ? %(<col/>) : %(<col style="width: #{col.attr 'colpcwidth'}%;" />))
+            end
           end
-          #else
-          #  node.columns.each do |col|
-          #    lines << %(<col style="width: #{col.attr 'colpcwidth'}%"/>)
-          #  end
-          #end
           lines << '</colgroup>'
           [:head, :body, :foot].reject {|tsec| node.rows[tsec].empty? }.each do |tsec|
             lines << %(<t#{tsec}>)
@@ -649,19 +755,16 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
                   else
                     cell_content = ''
                     cell.content.each do |text|
-                      cell_content = %(#{cell_content}<p>#{text}</p>)
+                      cell_content = %(#{cell_content}<p class="tableblock">#{text}</p>)
                     end
                   end
                 end
 
                 cell_tag_name = tsec == :head || cell.style == :header ? 'th' : 'td'
-                cell_classes = []
-                if (halign = cell.attr 'halign') && halign != 'left'
-                  cell_classes << 'halign-left'
-                end
-                if (halign = cell.attr 'valign') && halign != 'top'
-                  cell_classes << 'valign-top'
-                end
+                cell_classes = [
+                  "halign-#{cell.attr 'halign'}",
+                  "valign-#{cell.attr 'valign'}",
+                ]
                 cell_class_attr = !cell_classes.empty? ? %( class="#{cell_classes * ' '}") : ''
                 cell_colspan_attr = cell.colspan ? %( colspan="#{cell.colspan}") : ''
                 cell_rowspan_attr = cell.rowspan ? %( rowspan="#{cell.rowspan}") : ''
@@ -694,16 +797,30 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       # TODO: add complex class if list has nested blocks
       def convert_dlist node
         lines = []
+        id_attribute = node.id ? %( id="#{node.id}") : ''
+
+        classes = case node.style
+                  when 'horizontal'
+                    ['hdlist', node.role]
+                  when 'itemized', 'ordered'
+                    # QUESTION should we just use itemized-list and ordered-list as the class here? or just list?
+                    ['dlist', %(#{node.style}-list), node.role]
+                  else
+                    ['description-list']
+                  end.compact
+
+        class_attribute = %( class="#{classes.join ' '}")
+
+        lines << %(<div#{id_attribute}#{class_attribute}>)
+        lines << %(<div class="title">#{node.title}</div>) if node.title?
+
         case (style = node.style)
         when 'itemized', 'ordered'
           list_tag_name = style == 'itemized' ? 'ul' : 'ol'
           role = node.role
           subject_stop = node.attr 'subject-stop', (role && (node.has_role? 'stack') ? nil : ':')
-          # QUESTION should we just use itemized-list and ordered-list as the class here? or just list?
-          div_classes = [%(#{style}-list), role].compact
           list_class_attr = (node.option? 'brief') ? ' class="brief"' : ''
-          lines << %(<div class="#{div_classes * ' '}">
-<#{list_tag_name}#{list_class_attr}#{list_tag_name == 'ol' && (node.option? 'reversed') ? ' reversed="reversed"' : ''}>)
+          lines << %(<#{list_tag_name}#{list_class_attr}#{list_tag_name == 'ol' && (node.option? 'reversed') ? ' reversed="reversed"' : ''}>)
           node.items.each do |subjects, dd|
             # consists of one term (a subject) and supporting content
             subject = [*subjects].first.text
@@ -719,11 +836,40 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
             end
             lines << '</li>'
           end
-          lines << %(</#{list_tag_name}>
-</div>)
+          lines << %(</#{list_tag_name}>)
+        when 'horizontal'
+          lines << '<table>'
+          if (node.attr? 'labelwidth') || (node.attr? 'itemwidth')
+            lines << '<colgroup>'
+            col_style_attribute = (node.attr? 'labelwidth') ? %( style="width: #{(node.attr 'labelwidth').chomp '%'}%;") : ''
+            lines << %(<col#{col_style_attribute} />)
+            col_style_attribute = (node.attr? 'itemwidth') ? %( style="width: #{(node.attr 'itemwidth').chomp '%'}%;") : ''
+            lines << %(<col#{col_style_attribute} />)
+            lines << '</colgroup>'
+          end
+          node.items.each do |terms, dd|
+            lines << '<tr>'
+            lines << %(<td class="hdlist1#{(node.option? 'strong') ? ' strong' : ''}">)
+            first_term = true
+            terms.each do |dt|
+              lines << %(<br />) unless first_term
+              lines << '<p>'
+              lines << dt.text
+              lines << '</p>'
+              first_term = nil
+            end
+            lines << '</td>'
+            lines << '<td class="hdlist2">'
+            if dd
+              lines << %(<p>#{dd.text}</p>) if dd.text?
+              lines << dd.content if dd.blocks?
+            end
+            lines << '</td>'
+            lines << '</tr>'
+          end
+          lines << '</table>'
         else
-          lines << '<div class="description-list">
-<dl>'
+          lines << '<dl>'
           node.items.each do |terms, dd|
             [*terms].each do |dt|
               lines << %(<dt>
@@ -740,9 +886,10 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
             end
             lines << '</dd>'
           end
-          lines << '</dl>
-</div>'
+          lines << '</dl>'
         end
+
+        lines << '</div>'
         lines * LF
       end
 
@@ -816,22 +963,29 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         document
       end
 
-      def register_image node, target
-        if target.end_with? '.svg'
+      def register_media_file node, target, media_type
+        if target.end_with?('.svg') || target.start_with?('data:image/svg+xml')
           chapter = get_enclosing_chapter node
           chapter.set_attr 'epub-properties', [] unless chapter.attr? 'epub-properties'
           epub_properties = chapter.attr 'epub-properties'
           epub_properties << 'svg' unless epub_properties.include? 'svg'
         end
 
-        out_dir = node.attr('outdir', nil, true) || doc_option(node.document, :to_dir)
-        fs_path = (::File.join out_dir, target)
-        unless ::File.exist? fs_path
-          base_dir = root_document(node.document).base_dir
-          fs_path = ::File.join base_dir, target
+        return if target.start_with? 'data:'
+
+        if Asciidoctor::Helpers.uriish? target
+          # We need to add both local and remote media files to manifest
+          fs_path = nil
+        else
+          out_dir = node.attr('outdir', nil, true) || doc_option(node.document, :to_dir)
+          fs_path = (::File.join out_dir, target)
+          unless ::File.exist? fs_path
+            base_dir = root_document(node.document).base_dir
+            fs_path = ::File.join base_dir, target
+          end
         end
         # We need *both* virtual and physical image paths. Unfortunately, references[:images] only has one of them.
-        @images << { name: target, path: fs_path }
+        @media_files[target] ||= { path: fs_path, media_type: media_type }
       end
 
       def resolve_image_attrs node
@@ -848,16 +1002,81 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         img_attrs
       end
 
+      def convert_audio node
+        id_attr = node.id ? %( id="#{node.id}") : ''
+        target = node.media_uri node.attr 'target'
+        register_media_file node, target, 'audio'
+        title_element = node.title? ? %(\n<figcaption>#{node.captioned_title}</figcaption>) : ''
+
+        autoplay_attr = (node.option? 'autoplay') ? ' autoplay="autoplay"' : ''
+        controls_attr = (node.option? 'nocontrols') ? '' : ' controls="controls"'
+        loop_attr = (node.option? 'loop') ? ' loop="loop"' : ''
+
+        start_t = node.attr 'start'
+        end_t = node.attr 'end'
+        if start_t || end_t
+          time_anchor = %(#t=#{start_t || ''}#{end_t ? ",#{end_t}" : ''})
+        else
+          time_anchor = ''
+        end
+
+        %(<figure#{id_attr} class="audioblock#{prepend_space node.role}">#{title_element}
+<div class="content">
+<audio src="#{target}#{time_anchor}"#{autoplay_attr}#{controls_attr}#{loop_attr}>
+<div>Your Reading System does not support (this) audio.</div>
+</audio>
+</div>
+</figure>)
+      end
+
+      # TODO: Support multiple video files in different formats for a single video
+      def convert_video node
+        id_attr = node.id ? %( id="#{node.id}") : ''
+        target = node.media_uri node.attr 'target'
+        register_media_file node, target, 'video'
+        title_element = node.title? ? %(\n<figcaption>#{node.captioned_title}</figcaption>) : ''
+
+        width_attr = (node.attr? 'width') ? %( width="#{node.attr 'width'}") : ''
+        height_attr = (node.attr? 'height') ? %( height="#{node.attr 'height'}") : ''
+        autoplay_attr = (node.option? 'autoplay') ? ' autoplay="autoplay"' : ''
+        controls_attr = (node.option? 'nocontrols') ? '' : ' controls="controls"'
+        loop_attr = (node.option? 'loop') ? ' loop="loop"' : ''
+
+        start_t = node.attr 'start'
+        end_t = node.attr 'end'
+        if start_t || end_t
+          time_anchor = %(#t=#{start_t || ''}#{end_t ? ",#{end_t}" : ''})
+        else
+          time_anchor = ''
+        end
+
+        if (poster = node.attr 'poster').nil_or_empty?
+          poster_attr = ''
+        else
+          poster = node.media_uri poster
+          register_media_file node, poster, 'image'
+          poster_attr = %( poster="#{poster}")
+        end
+
+        %(<figure#{id_attr} class="video#{prepend_space node.role}">#{title_element}
+<div class="content">
+<video src="#{target}#{time_anchor}"#{width_attr}#{height_attr}#{autoplay_attr}#{poster_attr}#{controls_attr}#{loop_attr}>
+<div>Your Reading System does not support (this) video.</div>
+</video>
+</div>
+</figure>)
+      end
+
       def convert_image node
         target = node.image_uri node.attr 'target'
-        register_image node, target
+        register_media_file node, target, 'image'
         id_attr = node.id ? %( id="#{node.id}") : ''
+        title_element = node.title? ? %(\n<figcaption>#{node.captioned_title}</figcaption>) : ''
         img_attrs = resolve_image_attrs node
         %(<figure#{id_attr} class="image#{prepend_space node.role}">
 <div class="content">
 <img src="#{target}"#{prepend_space img_attrs * ' '} />
-</div>#{node.title? ? %(
-<figcaption>#{node.captioned_title}</figcaption>) : ''}
+</div>#{title_element}
 </figure>)
       end
 
@@ -901,7 +1120,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
               end
 
               id_attr = '' unless @xrefs_seen.add? refid
-              text = (ref.xreftext node.attr('xrefstyle', nil, true))
+              text ||= (ref.xreftext node.attr('xrefstyle', nil, true))
             else
               logger.warn %(#{::File.basename doc.attr('docfile')}: invalid reference to unknown anchor: #{refid})
             end
@@ -953,7 +1172,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 
       def convert_inline_image node
         if node.type == 'icon'
-          @icon_names << (icon_name = node.target)
+          icon_names << (icon_name = node.target)
           i_classes = ['icon', %(i-#{icon_name})]
           i_classes << %(icon-#{node.attr 'size'}) if node.attr? 'size'
           i_classes << %(icon-flip-#{(node.attr 'flip')[0]}) if node.attr? 'flip'
@@ -962,7 +1181,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
           %(<i class="#{i_classes * ' '}"></i>)
         else
           target = node.image_uri node.target
-          register_image node, target
+          register_media_file node, target, 'image'
 
           img_attrs = resolve_image_attrs node
           img_attrs << %(class="inline#{prepend_space node.role}")
@@ -1000,25 +1219,30 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       def convert_inline_quoted node
         open, close, tag = QUOTE_TAGS[node.type]
 
-        # TODO: implement proper stem support. See https://github.com/asciidoctor/asciidoctor-epub3/issues/10
+        if node.type == :asciimath && asciimath_available?
+          content = AsciiMath.parse(node.text).to_mathml 'mml:'
+        else
+          content = node.text
+        end
+
         node.add_role 'literal' if [:monospaced, :asciimath, :latexmath].include? node.type
 
         if node.id
           class_attr = class_string node
           if tag
-            %(#{open.chop} id="#{node.id}"#{class_attr}>#{node.text}#{close})
+            %(#{open.chop} id="#{node.id}"#{class_attr}>#{content}#{close})
           else
-            %(<span id="#{node.id}"#{class_attr}>#{open}#{node.text}#{close}</span>)
+            %(<span id="#{node.id}"#{class_attr}>#{open}#{content}#{close}</span>)
           end
         elsif role_valid_class? node.role
           class_attr = class_string node
           if tag
-            %(#{open.chop}#{class_attr}>#{node.text}#{close})
+            %(#{open.chop}#{class_attr}>#{content}#{close})
           else
-            %(<span#{class_attr}>#{open}#{node.text}#{close}</span>)
+            %(<span#{class_attr}>#{open}#{content}#{close}</span>)
           end
         else
-          %(#{open}#{node.text}#{close})
+          %(#{open}#{content}#{close})
         end
       end
 
@@ -1082,6 +1306,19 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
           @book.add_item 'styles/epub3-css3-only.css', content: (postprocess_css_file ::File.join(workdir, 'epub3-css3-only.css'), format)
         end
 
+        syntax_hl = doc.syntax_highlighter
+        if syntax_hl&.write_stylesheet? doc
+          Dir.mktmpdir do |dir|
+            syntax_hl.write_stylesheet doc, dir
+            Pathname.glob(dir + '/**/*').map do |filename|
+              # Workaround for https://github.com/skoji/gepub/pull/117
+              filename.open do |f|
+                @book.add_item filename.basename.to_s, content: f
+              end if filename.file?
+            end
+          end
+        end
+
         font_files, font_css = select_fonts ::File.join(DATA_DIR, 'styles/epub3-fonts.css'), (doc.attr 'scripts', 'latin')
         @book.add_item 'styles/epub3-fonts.css', content: font_css
         unless font_files.empty?
@@ -1101,8 +1338,8 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         nil
       end
 
-      def add_cover_image doc
-        return if (image_path = doc.attr 'front-cover-image').nil?
+      def add_cover_page doc
+        return nil if (image_path = doc.attr 'front-cover-image').nil?
 
         imagesdir = (doc.attr 'imagesdir', '.').chomp '/'
         imagesdir = (imagesdir == '.' ? '' : %(#{imagesdir}/))
@@ -1119,20 +1356,21 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         workdir = doc.attr 'docdir'
         workdir = '.' if workdir.nil_or_empty?
 
-        unless ::File.readable? ::File.join(workdir, image_path)
-          logger.error %(#{::File.basename doc.attr('docfile')}: front cover image not found or readable: #{::File.expand_path image_path, workdir})
-          return
+        begin
+          @book.add_item(image_href, content: File.join(workdir, image_path)).cover_image
+        rescue => e
+          logger.error %(#{::File.basename doc.attr('docfile')}: error adding front cover image. Make sure that :front-cover-image: attribute points to a valid image file. #{e})
+          return nil
         end
 
+        return nil if @format == :kf8
+
         unless !image_attrs.empty? && (width = image_attrs['width']) && (height = image_attrs['height'])
           width, height = 1050, 1600
         end
 
-        @book.add_item(image_href, content: File.join(workdir, image_path)).cover_image
-
-        unless @format == :kf8
-          # NOTE SVG wrapper maintains aspect ratio and confines image to view box
-          content = %(<!DOCTYPE html>
+        # NOTE SVG wrapper maintains aspect ratio and confines image to view box
+        content = %(<!DOCTYPE html>
 <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="en" lang="en">
 <head>
 <meta charset="UTF-8"/>
@@ -1162,10 +1400,7 @@ body > svg {
 </svg></body>
 </html>).to_ios
 
-          # Gitden expects a cover.xhtml, so add it to the spine
-          @book.add_ordered_item 'cover.xhtml', content: content, id: 'cover'
-        end
-        nil
+        @book.add_ordered_item 'cover.xhtml', content: content, id: 'cover'
       end
 
       def get_frontmatter_files doc, workdir
@@ -1195,19 +1430,22 @@ body > svg {
         workdir = doc.attr 'docdir'
         workdir = '.' if workdir.nil_or_empty?
 
+        result = nil
         get_frontmatter_files(doc, workdir).each do |front_matter|
           front_matter_content = ::File.read front_matter
 
           front_matter_file = File.basename front_matter, '.html'
           item = @book.add_ordered_item "#{front_matter_file}.xhtml", content: (postprocess_xhtml front_matter_content)
           item.add_property 'svg' if SvgImgSniffRx =~ front_matter_content
+          # Store link to first frontmatter page
+          result = item if result.nil?
 
           front_matter_content.scan ImgSrcScanRx do
             @book.add_item $1, content: File.join(File.dirname(front_matter), $1)
           end
         end
 
-        nil
+        result
       end
 
       def add_profile_images doc, usernames
@@ -1239,8 +1477,7 @@ body > svg {
         nil
       end
 
-      # TODO: aggregate authors of chapters into authors attribute(s) on main document
-      def nav_doc doc, items
+      def nav_doc doc, items, landmarks, depth
         lines = [%(<!DOCTYPE html>
 <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="#{lang = doc.attr 'lang', 'en'}" lang="#{lang}">
 <head>
@@ -1250,13 +1487,29 @@ body > svg {
 <link rel="stylesheet" type="text/css" href="styles/epub3-css3-only.css" media="(min-device-width: 0px)"/>
 </head>
 <body>
-<h1>#{sanitize_doctitle_xml doc, :pcdata}</h1>
-<nav epub:type="toc" id="toc">
-<h2>#{doc.attr 'toc-title'}</h2>)]
-        lines << (nav_level items, [(doc.attr 'toclevels', 1).to_i, 0].max)
-        lines << %(</nav>
+<section class="chapter">
+<header>
+<div class="chapter-header"><h1 class="chapter-title"><small class="subtitle">#{doc.attr 'toc-title'}</small></h1></div>
+</header>
+<nav epub:type="toc" id="toc">)]
+        lines << (nav_level items, [depth, 0].max)
+        lines << '</nav>'
+
+        unless landmarks.empty?
+          lines << '
+<nav epub:type="landmarks" id="landmarks" hidden="hidden">
+<ol>'
+          landmarks.each do |landmark|
+            lines << %(<li><a epub:type="#{landmark[:type]}" href="#{landmark[:href]}">#{landmark[:title]}</a></li>)
+          end
+          lines << '
+</ol>
+</nav>'
+        end
+        lines << '
+</section>
 </body>
-</html>)
+</html>'
         lines * LF
       end
 
@@ -1266,14 +1519,14 @@ body > svg {
         items.each do |item|
           #index = (state[:index] = (state.fetch :index, 0) + 1)
           if (chapter_name = get_chapter_name item).nil?
-            item_label = sanitize_xml item.title, :pcdata
+            item_label = sanitize_xml get_numbered_title(item), :pcdata
             item_href = %(#{state[:content_doc_href]}##{item.id})
           else
             # NOTE we sanitize the chapter titles because we use formatting to control layout
             if item.context == :document
               item_label = sanitize_doctitle_xml item, :cdata
             else
-              item_label = sanitize_xml item.title, :cdata
+              item_label = sanitize_xml get_numbered_title(item), :cdata
             end
             item_href = (state[:content_doc_href] = %(#{chapter_name}.xhtml))
           end
@@ -1290,7 +1543,7 @@ body > svg {
         lines * LF
       end
 
-      def ncx_doc doc, items
+      def ncx_doc doc, items, depth
         # TODO: populate docAuthor element based on unique authors in work
         lines = [%(<?xml version="1.0" encoding="utf-8"?>
 <ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1" xml:lang="#{doc.attr 'lang', 'en'}">
@@ -1302,7 +1555,7 @@ body > svg {
 </head>
 <docTitle><text>#{sanitize_doctitle_xml doc, :cdata}</text></docTitle>
 <navMap>)]
-        lines << (ncx_level items, [(doc.attr 'toclevels', 1).to_i, 0].max, state = {})
+        lines << (ncx_level items, depth, state = {})
         lines[0] = lines[0].sub '%{depth}', %(<meta name="dtb:depth" content="#{state[:max_depth]}"/>)
         lines << %(</navMap>
 </ncx>)
@@ -1316,13 +1569,13 @@ body > svg {
           index = (state[:index] = (state.fetch :index, 0) + 1)
           item_id = %(nav_#{index})
           if (chapter_name = get_chapter_name item).nil?
-            item_label = sanitize_xml item.title, :cdata
+            item_label = sanitize_xml get_numbered_title(item), :cdata
             item_href = %(#{state[:content_doc_href]}##{item.id})
           else
             if item.context == :document
               item_label = sanitize_doctitle_xml item, :cdata
             else
-              item_label = sanitize_xml item.title, :cdata
+              item_label = sanitize_xml get_numbered_title(item), :cdata
             end
             item_href = (state[:content_doc_href] = %(#{chapter_name}.xhtml))
           end
@@ -1380,10 +1633,10 @@ body > svg {
           .to_ios
       end
 
-      def get_kindlegen_command kindlegen_path
-        unless kindlegen_path.nil?
-          logger.debug %(Using ebook-kindlegen-path attribute: #{kindlegen_path})
-          return [kindlegen_path]
+      def get_kindlegen_command
+        unless @kindlegen_path.nil?
+          logger.debug %(Using ebook-kindlegen-path attribute: #{@kindlegen_path})
+          return [@kindlegen_path]
         end
 
         unless (result = ENV['KINDLEGEN']).nil?
@@ -1391,22 +1644,15 @@ body > svg {
           return [result]
         end
 
-        begin
-          require 'kindlegen' unless defined? ::Kindlegen
-          result = ::Kindlegen.command.to_s
-          logger.debug %(Using KindleGen from gem: #{result})
-          [result]
-        rescue LoadError => e
-          logger.debug %(#{e}; Using KindleGen from PATH)
-          [%(kindlegen#{::Gem.win_platform? ? '.exe' : ''})]
-        end
+        logger.debug 'Using KindleGen from PATH'
+        [%(kindlegen#{::Gem.win_platform? ? '.exe' : ''})]
       end
 
-      def distill_epub_to_mobi epub_file, target, compress, kindlegen_path
+      def distill_epub_to_mobi epub_file, target, compress
         mobi_file = ::File.basename target.sub(EpubExtensionRx, '.mobi')
         compress_flag = KindlegenCompression[compress ? (compress.empty? ? '1' : compress.to_s) : '0']
 
-        argv = get_kindlegen_command(kindlegen_path) + ['-dont_append_source', compress_flag, '-o', mobi_file, epub_file].compact
+        argv = get_kindlegen_command + ['-dont_append_source', compress_flag, '-o', mobi_file, epub_file].compact
         begin
           # This duplicates Kindlegen.run, but we want to override executable
           out, err, res = Open3.capture3(*argv) do |r|
@@ -1431,10 +1677,10 @@ body > svg {
         end
       end
 
-      def get_epubcheck_command epubcheck_path
-        unless epubcheck_path.nil?
-          logger.debug %(Using ebook-epubcheck-path attribute: #{epubcheck_path})
-          return [epubcheck_path]
+      def get_epubcheck_command
+        unless @epubcheck_path.nil?
+          logger.debug %(Using ebook-epubcheck-path attribute: #{@epubcheck_path})
+          return [@epubcheck_path]
         end
 
         unless (result = ENV['EPUBCHECK']).nil?
@@ -1452,8 +1698,8 @@ body > svg {
         end
       end
 
-      def validate_epub epub_file, epubcheck_path
-        argv = get_epubcheck_command(epubcheck_path) + ['-w', epub_file]
+      def validate_epub epub_file
+        argv = get_epubcheck_command + ['-w', epub_file]
         begin
           out, err, res = Open3.capture3(*argv)
         rescue Errno::ENOENT => e
@@ -1510,6 +1756,7 @@ body > svg {
         InvalidIdCharsRx = /[^[:word:]]+/
         LeadingDigitRx = /^[[:digit:]]/
       end
+
       class << self
         def generate_id doc, pre = nil, sep = nil
           synthetic = false
@@ -1561,13 +1808,19 @@ body > svg {
     Extensions.register do
       if (document = @document).backend == 'epub3'
         document.set_attribute 'listing-caption', 'Listing'
-        # pygments.rb hangs on JRuby for Windows, see https://github.com/asciidoctor/asciidoctor-epub3/issues/253
-        if !(::RUBY_ENGINE == 'jruby' && Gem.win_platform?) && (Gem.try_activate 'pygments.rb')
-          if document.set_attribute 'source-highlighter', 'pygments'
-            document.set_attribute 'pygments-css', 'style'
-            document.set_attribute 'pygments-style', 'bw'
-          end
+
+        # TODO: bw theme for CodeRay
+        document.set_attribute 'pygments-style', 'bw' unless document.attr? 'pygments-style'
+        document.set_attribute 'rouge-style', 'bw' unless document.attr? 'rouge-style'
+
+        # Old asciidoctor versions do not have public API for writing highlighter CSS file
+        # So just use inline CSS there.
+        unless Document.supports_syntax_highlighter?
+          document.set_attribute 'coderay-css', 'style'
+          document.set_attribute 'pygments-css', 'style'
+          document.set_attribute 'rouge-css', 'style'
         end
+
         case (ebook_format = document.attributes['ebook-format'])
         when 'epub3', 'kf8'
           # all good