asciidoctor-epub3 1.5.0.alpha.16 → 1.5.1

data/lib/asciidoctor-epub3/converter.rb

@@ -39,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,7 +105,7 @@ module Asciidoctor
         if respond_to? method_name
           send method_name, node
         else
-          logger.warn %(#{::File.basename node.attr('docfile')}: conversion missing in backend #{@backend} for #{name})
+          logger.warn %(conversion missing in backend #{@backend} for #{name})
           nil
         end
       end
@@ -143,6 +143,10 @@ module Asciidoctor
         title
       end
 
+      def icon_names
+        @icon_names ||= []
+      end
+
       def convert_document node
         @format = node.attr('ebook-format').to_sym
 
@@ -152,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 = []
-        @media_files = []
+        @media_files = {}
         @footnotes = []
 
         @book = GEPUB::Book.new 'EPUB/package.opf'
@@ -220,8 +223,27 @@ module Asciidoctor
           series_meta.refine 'collection-type', 'series'
         end
 
-        add_cover_image node
-        add_front_matter_page node
+        # For list of supported landmark types see
+        # https://idpf.github.io/epub-vocabs/structure/
+        landmarks = []
+
+        front_cover = add_cover_page node, 'front-cover'
+        landmarks << { type: 'cover', href: front_cover.href, title: 'Front Cover' } unless front_cover.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
@@ -231,24 +253,34 @@ module Asciidoctor
           add_chapter node
         end
 
-        nav_xhtml = @book.add_item 'nav.xhtml', content: postprocess_xhtml(nav_doc(node, toc_items)), id: 'nav'
-        nav_xhtml.nav
+        _back_cover = add_cover_page node, 'back-cover'
+        # TODO: add landmark for back cover? But what epub:type?
+
+        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}/))
 
-        @media_files.each do |file|
-          if file[:name].start_with? %(#{docimagesdir}jacket/cover.)
-            logger.warn %(path is reserved for cover artwork: #{file[:name]}; skipping file found in content)
-          elsif ::File.readable? file[:path]
-            mime_types = MIME::Types.type_for file[:name]
+        @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 file[:name], content: file[:path], media_type: preferred_mime_type
+            @book.add_item name, content: file[:path], media_type: preferred_mime_type
           else
             logger.error %(#{File.basename node.attr('docfile')}: media file not found or not readable: #{file[:path]})
           end
@@ -301,25 +333,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 = 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
@@ -337,10 +366,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>
@@ -351,19 +380,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>) : ''
 
-        # TODO : support writing code highlighter CSS to a separate file
-        linkcss = false
+        # 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[
@@ -376,13 +406,14 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 });
 ]]></script>)]
 
-        if self.class.supports_highlighter_docinfo? && (syntax_hl = node.document.syntax_highlighter) && (syntax_hl.docinfo? :head)
-          lines << (syntax_hl.docinfo :head, node, linkcss: linkcss, self_closing_tag_slash: '/')
-        end
+        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})
 
@@ -405,7 +436,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 
         lines << '</section>'
 
-        lines << (syntax_hl.docinfo :footer, node.document, linkcss: linkcss, self_closing_tag_slash: '/') if syntax_hl && (syntax_hl.docinfo? :footer)
+        lines << (syntax_hl.docinfo :footer, node.document, linkcss: linkcss, self_closing_tag_slash: '/') if syntax_hl&.docinfo? :footer
 
         lines << '</body>
 </html>'
@@ -423,11 +454,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 = get_numbered_title node
-          title_sanitized = xml_sanitize title
-          %(<section class="#{div_classes * ' '}" title="#{title_sanitized}"#{epub_type_attr}>
+          %(<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>)
@@ -510,14 +540,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">
@@ -544,10 +572,12 @@ 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'
-          if self.class.supports_highlighter_docinfo? && (syntax_hl = node.document.syntax_highlighter)
+          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)],
@@ -565,17 +595,41 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         figure_classes = ['listing']
         figure_classes << 'coalesce' if node.option? 'unbreakable'
         title_div = node.title? ? %(<figcaption>#{node.captioned_title}</figcaption>) : ''
-        %(<figure class="#{figure_classes * ' '}">#{title_div}
+        %(<figure#{id_attribute} class="#{figure_classes * ' '}">#{title_div}
         #{syntax_hl ? (syntax_hl.format node, lang, opts) : pre_open + (node.content || '') + pre_close}
 </figure>)
       end
 
-      # TODO: implement proper stem support. See https://github.com/asciidoctor/asciidoctor-epub3/issues/10
-      alias convert_stem convert_listing
+      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
+
+      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
@@ -657,41 +711,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}>)
@@ -711,19 +758,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}") : ''
@@ -932,26 +976,40 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 
         return if target.start_with? 'data:'
 
-        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
+        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.
-        @media_files << { name: target, path: fs_path, media_type: media_type }
+        @media_files[target] ||= { path: fs_path, media_type: media_type }
       end
 
       def resolve_image_attrs node
         img_attrs = []
         img_attrs << %(alt="#{node.attr 'alt'}") if node.attr? 'alt'
 
-        width = node.attr 'scaledwidth'
-        width = node.attr 'width' if width.nil?
-
         # Unlike browsers, Calibre/Kindle *do* scale image if only height is specified
         # So, in order to match browser behavior, we just always omit height
-        img_attrs << %(width="#{width}") unless width.nil?
+
+        if (scaledwidth = node.attr 'scaledwidth')
+          img_attrs << %(style="width: #{scaledwidth}")
+        elsif (width = node.attr 'width')
+          # HTML5 spec (and EPUBCheck) only allows pixels in width, but browsers also accept percents
+          # and there are multiple AsciiDoc files in the wild that have width=percents%
+          # So, for compatibility reasons, output percentage width as a CSS style
+          if width[/^\d+%$/]
+            img_attrs << %(style="width: #{width}")
+          else
+            img_attrs << %(width="#{width}")
+          end
+        end
 
         img_attrs
       end
@@ -1126,7 +1184,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'
@@ -1173,25 +1231,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
 
@@ -1255,6 +1318,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?
@@ -1274,38 +1350,41 @@ 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, name
+        image_attr_name = %(#{name}-image)
+
+        return nil if (image_path = doc.attr image_attr_name).nil?
 
         imagesdir = (doc.attr 'imagesdir', '.').chomp '/'
         imagesdir = (imagesdir == '.' ? '' : %(#{imagesdir}/))
 
         image_attrs = {}
         if (image_path.include? ':') && image_path =~ ImageMacroRx
-          logger.warn %(deprecated block macro syntax detected in front-cover-image attribute) if image_path.start_with? 'image::'
+          logger.warn %(deprecated block macro syntax detected in :#{image_attr_name}: attribute) if image_path.start_with? 'image::'
           image_path = %(#{imagesdir}#{$1})
           (::Asciidoctor::AttributeList.new $2).parse_into image_attrs, %w(alt width height) unless $2.empty?
         end
 
-        image_href = %(#{imagesdir}jacket/cover#{::File.extname image_path})
+        image_href = %(#{imagesdir}jacket/#{name}#{::File.extname image_path})
 
         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 cover image. Make sure that :#{image_attr_name}: 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"/>
@@ -1335,10 +1414,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 %(#{name}.xhtml), content: content, id: name
       end
 
       def get_frontmatter_files doc, workdir
@@ -1368,19 +1444,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
@@ -1412,8 +1491,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>
@@ -1423,13 +1501,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
 
@@ -1463,7 +1557,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'}">
@@ -1475,7 +1569,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>)
@@ -1553,10 +1647,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?
@@ -1575,11 +1669,11 @@ body > svg {
         end
       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|
@@ -1604,10 +1698,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?
@@ -1625,8 +1719,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
@@ -1671,14 +1765,6 @@ body > svg {
       def role_valid_class? role
         role.is_a? String
       end
-
-      class << self
-        def supports_highlighter_docinfo?
-          # Asciidoctor only got pluggable syntax highlighters since 2.0:
-          # https://github.com/asciidoctor/asciidoctor/commit/23ddbaed6818025cbe74365fec7e8101f34eadca
-          Asciidoctor::Document.method_defined? :syntax_highlighter
-        end
-      end
     end
 
     class DocumentIdGenerator
@@ -1691,6 +1777,7 @@ body > svg {
         InvalidIdCharsRx = /[^[:word:]]+/
         LeadingDigitRx = /^[[:digit:]]/
       end
+
       class << self
         def generate_id doc, pre = nil, sep = nil
           synthetic = false
@@ -1746,7 +1833,10 @@ body > svg {
         # 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'
-        unless Converter.supports_highlighter_docinfo?
+
+        # 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'