Semantic changes proposed to several blocks and one inline element

data/templates/admonition.html.slim

@@ -1,12 +1,16 @@
+- title_id = generate_title_id('admonition') if title?
 - capture
-  h6.block-title class=('label-only' unless title?)
-    span.title-label ="#{local_attr :textlabel}: "
-    =title
-  = html_tag_if !blocks?, :p
-    =content
+  .gutter
+    span.icon aria-hidden='true'
+    span.label =(local_attr :textlabel)
+  .content
+    - if title?
+      p.block-title id=title_id role='heading' =title
+    = html_tag_if !blocks?, :p
+      =content
 - if admonition_aside?
-  aside.admonition-block id=id class=[(attr :name), role] role=admonition_aria
+  aside.admonition-block id=id class=[(attr :name), role] role=admonition_aria aria-labelledby=title_id
     - yield_capture
 - else
-  section.admonition-block id=id class=[(attr :name), role] role=admonition_aria
+  section.admonition-block id=id class=[(attr :name), role] role=admonition_aria aria-labelledby=title_id
     - yield_capture

data/templates/helpers.rb

@@ -168,8 +168,8 @@ def html_tag_if(condition, name, attributes = {}, content = nil, &block)
   #   = block_with_title :class=>['quote-block', 'center']
   #     blockquote =content
   #
-  #   <section id="myid" class="quote-block center myrole1 myrole2">
-  #     <h6>Block Title</h6>
+  #   <section id="myid" class="quote-block center myrole1 myrole2" aria-labelledby="quote-title-1">
+  #     <p class="block-title" id="quote-title-1" role="heading">Block Title</p>
   #     <blockquote>Lorem ipsum</blockquote>
   #   </section>
   #
@@ -189,13 +189,22 @@ def html_tag_if(condition, name, attributes = {}, content = nil, &block)
   #     <blockquote>Lorem ipsum</blockquote>
   #   </div>
   #
+  # The title, when present, is rendered as a non-heading +p.block-title+
+  # referenced via +aria-labelledby+ on the enclosing tag, instead of a
+  # fixed-level heading -- a heading tag pinned to a fixed level would clash
+  # with the document's real section hierarchy.
+  #
   # @param attrs [Hash, String] the tag's attributes as Hash),
-  #        or the tag's class if it's not a Hash.
+  #        or the tag's class if it's not a Hash. May include +:tag+ to
+  #        override the enclosing element (default: +:section+, falling back
+  #        to +:div+ when untitled; a non-+:section+ +:tag+ is kept as-is even
+  #        when untitled, e.g. sidebar's +:aside+).
   # @param title [String, nil] the title.
   # @yield The block of Slim/HTML code within the tag (optional).
   # @return [String] a rendered HTML fragment.
   #
   def block_with_title(attrs = {}, title = @title, &block)
+    tag = attrs.delete(:tag) || :section
     if (klass = attrs[:class]).is_a? String
       klass = klass.split(' ')
     end
@@ -206,14 +215,28 @@ def block_with_title(attrs = {}, title = @title, &block)
       # XXX quick hack
       nested = is_a?(::Asciidoctor::List) &&
           (parent.is_a?(::Asciidoctor::ListItem) || parent.is_a?(::Asciidoctor::List))
-      html_tag_if !nested, :div, attrs, yield
+      html_tag_if !nested, (tag == :section ? :div : tag), attrs, yield
     else
-      html_tag :section, attrs do
-        [html_tag(:h6, {class: 'block-title'}, title), yield].join("\n")
+      title_id = generate_title_id
+      attrs[:'aria-labelledby'] = title_id
+      html_tag tag, attrs do
+        [html_tag(:p, {class: 'block-title', id: title_id, role: 'heading'}, title), yield].join("\n")
       end
     end
   end
 
+  ##
+  # Generates a unique, namespaced id for a non-heading block title (see
+  # {#block_with_title}), so it can be referenced via +aria-labelledby+
+  # instead of relying on a fixed-level heading tag.
+  #
+  # @param prefix [#to_s] a namespace for the id (default: the node's context).
+  # @return [String] a unique id, e.g. "sidebar-title-1".
+  #
+  def generate_title_id(prefix = context)
+    "#{prefix}-title-#{document.counter("html5s-#{prefix}-title")}"
+  end
+
   def block_with_caption(position = :bottom, attrs = {}, &block)
     if (klass = attrs[:class]).is_a? String
       klass = klass.split(' ')

data/templates/inline_footnote.html.slim

@@ -1,9 +1,11 @@
 - if (index = local_attr :index)
-  a.footnote-ref [
-      id=(footnoteref_id unless type == :xref)
-      href="##{footnote_id}"
-      title="View footnote #{index}"
-      role='doc-noteref' ]
-    | [#{index}]
+  sup.footnote-ref
+    a [
+        id=(footnoteref_id unless type == :xref)
+        href="##{footnote_id}"
+        title="View footnote #{index}"
+        role='doc-noteref' ]
+      | [#{index}]
 - else
-  a.footnote-ref.broken title="Unresolved footnote reference." [#{text}]
+  sup.footnote-ref.broken
+    a title="Unresolved footnote reference." [#{text}]

data/templates/open.html.slim

@@ -1,7 +1,13 @@
 - if style == 'abstract'
   - if abstract_allowed?
-    = block_with_title :class=>'quote-block abstract'
-      blockquote =content
+    - if title?
+      - title_id = generate_title_id('abstract')
+      section.abstract id=id class=role aria-labelledby=title_id role='doc-abstract'
+        p.block-title id=title_id role='heading' =title
+        =content
+    - else
+      section.abstract id=id class=role aria-label='Abstract' role='doc-abstract'
+        =content
 - elsif style != 'partintro' || partintro_allowed?
   = block_with_title :class=>['open-block', (style if style != 'open')]
     .content =content

data/templates/paragraph.html.slim

@@ -1,6 +1,7 @@
 - if title?
-  section.paragraph id=id
-    h6.block-title =title
+  - title_id = generate_title_id
+  section.paragraph id=id aria-labelledby=title_id
+    p.block-title id=title_id role='heading' =title
     p class=role =content
 - else
   p id=id class=role =content

data/templates/sidebar.html.slim

@@ -1,4 +1,2 @@
-aside.sidebar id=id class=role
-  - if title?
-    h6.block-title =title
+= block_with_title :class=>'sidebar', :tag=>:aside
   =content