V3 / Asciidoc / Asciidoctor / Customized generator template for titles

thoraxe · March 29, 2016, 3:28pm

Currently using Middleman 3.3.12 / Asciidoctor 1.5.4 and trying to figure out how to customize the HTML generated when rendering titles/headings.

This is related to http://discuss.asciidoctor.org/Custom-style-on-title-heading-element-td4543.html#a4547

Basically I want to customize the generated HTML when going from Middleman->Asciidoctor->HTML, but I cannot figure out even remotely where to start with where to even put the template file, let alone how to ensure that it is used (and the default back-end is not used).

Any thoughts?

thoraxe · March 29, 2016, 4:12pm

So it appears that the behavior of asciidoctor, at least in this case, may lie in the “section” node definition from the html5 renderer:

github.com

asciidoctor/asciidoctor/blob/master/lib/asciidoctor/converter/html5.rb#L317-L350



    if node.sections? && (node.attr? 'toc') && (toc_p = node.attr 'toc-placement') != 'macro' && toc_p != 'preamble'
      result << %(<div id="toc" class="toc">
<div id="toctitle">#{node.attr 'toc-title'}</div>
#{node.converter.convert node, 'outline'}
</div>)
    end

    result << node.content

    if node.footnotes? && !(node.attr? 'nofootnotes')
      result << %(<div id="footnotes">
<hr#{@void_element_slash}>)
      node.footnotes.each do |footnote|
        result << %(<div class="footnote" id="_footnotedef_#{footnote.index}">
<a href="#_footnoteref_#{footnote.index}">#{footnote.index}</a>. #{footnote.text}
</div>)
      end
      result << '</div>'
    end

This file has been truncated. show original

I initially tried to just include this method to override it in config.rb:

# override asciidoctor behavior
require 'asciidoctor'
module Asciidoctor
  class Converter::Html5Converter < Converter::BuiltIn
    def section node
....

But upon starting middleman I get an error that it doesn’t know what’s going on yet:

bundle exec middleman server --verbose == The Middleman is loading == Activating: sprockets == File Change: data/displaynames.yml == File Change: data/tree.yml == Reading: Local config == Activating: sitemap == Activating: deploy /home/thoraxe/Red_Hat/openshift/discoverycenter/config.rb:176:in '<module:Asciidoctor>': uninitialized constant # <Class:0x000000041addb8>::Asciidoctor::Converter (NameError)

I’m not sure if this is the right approach (overriding the Asciidoctor renderer) or if I should continue to chase the template situation…

thoraxe · March 29, 2016, 4:36pm

Replying to my own replies here…

I think I can pass the template_dir option to Asciidoctor in the attributes line:

set :asciidoc_attributes, %w(source-highlighter=coderay coderay-css=style template_dir=templates)

I see this reflected when examining the config:

:asciidoc = {:safe=>:safe,
 :backend=>:html5,
 :attributes=>
  ["env=middleman",
   "env-middleman",
   "middleman-version=3.4.1",
   "source-highlighter=coderay",
   "coderay-css=style",
   "imagesdir=/img",
   "source-highlighter=coderay",
   "coderay-css=style",
   "template_dir=templates",
   "imagesdir=/img"],
 :base_dir=>"/home/thoraxe/Red_Hat/openshift/discoverycenter/source"}
AsciiDoc engine options (Hash)

If I edit the template, I see that Middleman notices:
== File Change: source/templates/section.html.haml == Rebuilding resource list

Here’s the content of source/templates/section.html.haml:

- slevel = @level == 0 && @special ? 1 : @level
- anchor = nil
- link = nil
- if @id
  - if @document.attr? :sectanchors
    - anchor = %(<a class="anchor" href="##{@id}"></a>)
    - link = nil
  - elsif @document.attr? :sectlinks
    - anchor = nil 
    - link = %(<a class="link" href="##{@id}">)
- if slevel == 0
  %h1{:id=>@id, :class=>"sect0"}=%(#{anchor}#{link}#{title}#{link && '</a>'})
  =content
- else
  %div{:class=>["sect#{slevel}", role]}
    %p foo bar baz beta
    - snum = @numbered && @caption.nil? && slevel <= (@document.attr 'sectnumlevels', 3).to_i ? %(#{sectnum} ) : nil
    - haml_tag "h#{slevel + 1}##{@id}", %(#{anchor}#{link}#{snum}#{captioned_title}#{link && '</a>'})
    - if slevel == 1
      .sectionbody
        =content
    - else
      =content

This is nipped directly from https://github.com/asciidoctor/asciidoctor-backends/blob/master/haml/html5/section.html.haml

Here’s the Asciidoc:

[[fundamentals]]
[.category-info.helper.pt0]
=== OpenShift Fundamentals

Here’s the resulting output HTML I’m seeing in the rendered page:

<div class="sect2 category-info helper pt0">
<h3 id="fundamentals">OpenShift Fundamentals</h3>
</div>

So, clearly the “foo bar baz” stuff is not being output.

I think I’m so close!

thoraxe · March 30, 2016, 3:23pm

Bringing it full circle, the path was wrong.

See http://discuss.asciidoctor.org/Custom-style-on-title-heading-element-td4543.html#a4547 for the resolution.