Extended Converter Use Cases
In Create an Extended Converter, we only touched on what you can do with an extended converter. This page presents more realistic use cases that can be accomplished by extending and customizing the converter. Each section introduces a different use case and presents the code for an extended converter you can use as a starting point.
An extended converter can access predefined or custom theme keys via the theme accessor.
The segments in a key are always separated by an underscore character (e.g., theme.title_page_font_color ).
Consulting the value of theme keys allows the extra behavior provided by the extended converter to be styled using the theme.
|
The source code for each use case on this page can be found in the docs/modules/extend/examples directory in the Asciidoctor PDF repository. To use one of them, you can either download the script to your local disk or clone the Asciidoctor PDF repository. Once you have done so, refer to Use the Extended Converter to learn how to register and use it with Asciidoctor PDF. For example, to register and use the extended converter that allows you to theme admonitions by type, you’d use this command:
$ asciidoctor-pdf -r pdf-converter-admonition-theme-per-type.rb doc.adoc
Refer to the sections below for details about how to use each extended converter.
Custom thematic break
One of the simplest ways to extend the converter is to make a thematic break.
For this case, we’ll override the convert handler method for a thematic break, which is convert_thematic_break
.
The thematic break only consists of line graphics, no text.
That means we can make use of graphics fill and stroke methods provided by Asciidoctor PDF or Prawn.
class PDFConverterCustomThematicBreak < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def convert_thematic_break node
theme_margin :thematic_break, :top
stroke_horizontal_rule 'FF0000', line_width: 0.5, line_style: :solid
move_down 1
stroke_horizontal_rule 'FF0000', line_width: 1, line_style: :solid
move_down 1
stroke_horizontal_rule 'FF0000', line_width: 0.5, line_style: :solid
theme_margin :thematic_break, ((block_next = next_enclosed_block node) ? :bottom : :top), block_next || true
end
end
The return value of the convert handler method for a block node is ignored, which is why there’s no clear return value in this override. If this were a convert handler method for an inline node, a return value would be required, which becomes the text to render.
Custom title page
Every title page is as unique as the work itself.
That’s why Asciidoctor PDF gives you the ability to customize the title page by overriding the ink_title_page
method in an extended converter.
The ink_title_page
method is called after the title page has been created and the background applied, so it can focus on writing content.
In this method, you can choose to honor the title-page
settings from the theme, or go your own way.
The one rule is that the ink_title_page
method must not start a new page.
If it tries to start a new page, that request will be ignored and a warning will be generated.
Let’s create a custom title page that shows the document title and subtitle between two lines in the top half and a logo in the bottom half.
class PDFConverterCustomTitlePage < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def ink_title_page doc
move_cursor_to page_height * 0.75
theme_font :title_page do
stroke_horizontal_rule '2967B2', line_width: 1.5, line_style: :double
move_down 10
doctitle = doc.doctitle partition: true
theme_font :title_page_title do
ink_prose doctitle.main, align: :center, color: theme.base_font_color, line_height: 1, margin: 0
end
if (subtitle = doctitle.subtitle)
theme_font :title_page_subtitle do
move_down 10
ink_prose subtitle, align: :center, margin: 0
move_down 10
end
end
stroke_horizontal_rule '2967B2', line_width: 1.5, line_style: :double
move_cursor_to page_height * 0.5
convert ::Asciidoctor::Block.new doc, :image,
content_model: :empty,
attributes: { 'target' => 'sample-logo.jpg', 'pdfwidth' => '1.5in', 'align' => 'center' },
pinned: true
end
end
end
The methods move_cursor_to
and move_cursor
advance the cursor on the page where the next content will be written.
The method theme_font
applies the font from the specified category in the theme (with hyphens in the category name replaced by underscores).
The method stroke_horizontal_rule
draws a horizontal line using the specified color and line width.
The method ink_prose
is provided by Asciidoctor PDF to make writing text to the page easier.
Finally, the method convert
will convert and render the Asciidoctor node that is passed to it, in this case a block image.
Custom article title with details
Documents rendered as articles (i.e., doctype=article
) by Asciidoctor PDF don’t have a title page by default.
Instead the document title of the article, the article title, is shown on the first content page above the main content.
The document details, which includes the author, date, and revision information (revnumber and revremark), are not shown in this mode.
To insert them below the document title (similar to what the built-in HTML converter does), we can use an extended converter.
To do so, we hook into the method ink_general_heading
, which renders the document title of an article.
Since this method is also responsible for rendering other headings (e.g. section titles), we allow it fall back to the default implementation unless it is processing the document title of an article.
class PDFConverterArticleTitleWithAuthorAndDate < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def ink_general_heading doc, title, opts
return super unless opts[:role] == :doctitle (1)
ink_document_title title, opts (2)
ink_document_details doc, opts (3)
margin_bottom @theme[:heading_h1_margin_bottom] || @theme.heading_margin_bottom (4)
end
def ink_document_title title, opts
if (top_margin = @theme.heading_h1_margin_page_top || @theme.heading_margin_page_top) > 0
move_down top_margin
end
pad_box @theme.heading_h1_padding do
if (transform = resolve_text_transform opts)
title = transform_text title, transform
end
if (inherited = apply_text_decoration font_styles, :heading, 1).empty?
inline_format_opts = true
else
inline_format_opts = [{ inherited: inherited }]
end
typeset_text_opts = { color: @font_color, inline_format: inline_format_opts }.merge opts
typeset_text title, (calc_line_metrics (opts.delete :line_height) || @base_line_height), typeset_text_opts
end
end
def ink_document_details doc, opts
revnumber = doc.attr 'revnumber' (5)
if doc.author || doc.revdate || revnumber (6)
move_down @theme.heading_h1_details_margin_top || 0 (7)
theme_font_cascade [:base, :heading_h1_details] do (8)
author_date_separator = doc.author && doc.revdate ? %( #{EmDash} ) : '' (9)
revision = (doc.attr? 'revremark') ? %(#{revnumber} | #{doc.attr 'revremark'}) : revnumber if revnumber (10)
revision_separator = revision && (doc.author || doc.revdate) ? %( #{EmDash} ) : '' (11)
ink_prose %(#{doc.author}#{author_date_separator}#{doc.revdate}#{revision_separator}#{revision}), align: opts[:align] (12)
end
end
end
end
1 | Fall back to default implementation unless handling the document title. |
2 | Render the document title.
See the definition of ink_document_title for details. |
3 | Render the author, date, and revision information, if available.
See the definition of ink_document_details for details. |
4 | Render a vertical gap between the header and body of the document. |
5 | The revnumber isn’t available as a field of doc , so we have to retrieve it using the method doc.attr instead.
Because we’ll use the revnumber multiple times, we store it in a local variable. |
6 | Only include the additional line if there’s actually content for it so we don’t end up with unused vertical space. |
7 | Insert a vertical gap between the document title and the line with author, date, and revision information if the theme sets a size of that gap. Otherwise, don’t insert a gap. |
8 | When we get here, a heading-specific style will already be set by the code that calls ink_general_heading .
Since we don’t want the document details to use the heading font, we first have to revert to the base font using the :base category.
Then, we can apply the heading_h1_details category from the theme. |
9 | Build the revision information if the revnumber is set. If a revmark is specified, add it after the revnumber, separating the two by a vertical bar. |
10 | An em dash is put before the between author and date, but only if either are set. |
11 | An em dash is put before the revision, but only if it isn’t empty and there’s content in front of it. |
12 | Put the author, date, and revision information and their separators together using Ruby string interpolation and render the resulting string. |
Custom part title
A common need is to add extra styling to the title page for a part in a multi-part book.
Since this is a specialized section element, there’s a dedicated method named ink_part_title
that you can override.
The converter already allocates a dedicated page for the part title (so there’s no need to worry about doing that).
The extended converter can override the method that inks the part title to add extra decoration or content to that page.
Let’s customize the part title page by making the background orange, making the font white, aligning the title to the right, adding a line below it, and switching off the running content.
class PDFConverterCustomPartTitle < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def ink_part_title node, title, opts = {}
fill_absolute_bounds 'E64C3D'
move_down cursor * 0.25
indent bounds.width * 0.5 do
ink_prose title, line_height: 1.3, color: 'FFFFFF', inline_format: true, align: :right, size: 42, margin: 0
end
indent bounds.width * 0.33 do
move_down 12
stroke_horizontal_rule 'FFFFFF', line_width: 3
end
page.imported
end
end
The method ink_prose
is provided by Asciidoctor PDF to make writing text to the page easier.
If you wanted, you could just use the low-level text
method provided by Prawn.
It’s also possible to override the start_new_part method if all you want to do is called page.imported to turn off the running content.
|
Now let’s look at how to center the part title both vertically and horizontally.
For this, we first need to compute the height of the title using the height_of_typeset_text
helper, taking into account the vertical padding as well.
Then, we use that height to position the cursor so that the title falls in the vertical center of the page.
Next, we set the text alignment to center (which alternately could be done using the theme).
Finally, we delegate to the super method to handle rendering the title in the new position.
class PDFConverterCenteredPartTitle < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def ink_part_title node, title, opts = {}
vertical_padding = (padding = expand_padding_value @theme.heading_h1_padding)[0] + padding[2]
title_height = height_of_typeset_text title, inline_format: true, text_transform: @text_transform
space_above = (effective_page_height - (title_height + vertical_padding)) * 0.5
move_down space_above
opts = opts.merge align: :center
page.imported
super
end
end
To find all the methods available to an extended converter, consult the API docs.
Custom chapter title
A similar need is to add extra styling to the title of a chapter, or to place it on a page by itself. The extended converter can override the method that inks the chapter title to add extra decoration or content to that page, then insert a page break afterwards.
class PDFConverterCustomChapterTitle < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def ink_chapter_title node, title, opts = {}
move_down cursor * 0.25
ink_heading title, (opts.merge align: :center, text_transform: :uppercase)
stroke_horizontal_rule 'DDDDDD', line_width: 2
move_down theme.block_margin_bottom
theme_font :base do
layout_prose 'Custom text here, maybe a chapter preamble.'
end
start_new_page
end
end
It’s also possible to override the start_new_chapter method if all you want to do is called page.imported to turn off the running content.
|
Chapter image
As another way to customize the chapter title, you may want to add an image above the chapter title if specified. Once again, the extended converter can override the method that inks the chapter title and use it as an opportunity to insert an image.
class PDFConverterChapterImage < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def ink_chapter_title sect, title, opts
if (image_path = sect.attr 'image')
image_attrs = { 'target' => image_path, 'pdfwidth' => '1in' }
image_block = ::Asciidoctor::Block.new sect.document, :image, content_model: :empty, attributes: image_attrs
convert_image image_block, relative_to_imagesdir: true, pinned: true
end
super
end
end
The path to the image is controlled using the image
block attribute on the chapter.
[image=gears.png]
== Chapter Title
Per chapter TOC
In addition to (or instead of) a TOC for the whole book, you may want to insert a TOC per chapter immediately following the chapter title.
Inserting a TOC into the PDF is a two-step process.
First, you need to allocate the space for the chapter TOC using the allocate_toc
method.
Then, you need to come back and ink the TOC after the chapter has been rendered using the ink_toc
method.
class PDFConverterChapterTOC < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def convert_section sect, opts = {}
result = super
if (toc_extent = sect.attr 'pdf-toc-extent')
levels = (sect.document.attr 'chapter-toclevels', 1).to_i + 1
page_numbering_offset = @index.start_page_number - 1
float do
ink_toc sect, levels, toc_extent.from.page, toc_extent.from.cursor, page_numbering_offset
end
end
result
end
def ink_chapter_title sect, title, opts
super
if ((doc = sect.document).attr? 'chapter-toc') && (levels = (doc.attr 'chapter-toclevels', 1).to_i + 1) > 1
theme_font :base do
sect.set_attr 'pdf-toc-extent', (allocate_toc sect, levels, cursor, false)
end
end
end
end
The chapter TOC can is activated by setting the chapter-toc
attribute and the depth of the TOC is controlled using the chapter-toclevels
attribute.
For example:
= Book Title
:chapter-toc:
:chapter-toclevels: 2
Colophon before TOC
Some publishers prefer the colophon to precede the table of contents. Asciidoctor PDF provides support for this out of the box. The trick is to use the TOC macro to position the TOC at the end of the colophon. The converter will start the TOC on the next available recto page. If the publisher requires it, you can configure the colophon to be non-facing so it starts on the verso page that follows the title page.
Use the following AsciiDoc source as a starting point:
= Book Title
:doctype: book
:media: prepress
:toc: macro
[colophon%notitle%nonfacing]
= Colophon
This is the text of the colophon.
It will start on the verso page following the title page since it has the `nonfacing` option set.
The title will be hidden on that page since it has the `notitle` option set.
toc::[]
== First Chapter
This the the text of the first chapter.
This chapter will start on the first recto page after the table of contents.
If you want the running content and/or page numbering to start at the first chapter, you’ll need to set the start-at key to after-toc in the running-content and/or page-numbering keys in your theme.
|
Instead of using the built-in support through configuration, you can achieve these customizations using an extended converter instead.
To do so, you need to override the built-in ink_toc
method and render the colophon before the TOC is rendered (i.e., inked).
class AsciidoctorPDFExtensions < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def ink_toc doc, num_levels, toc_page_number, start_cursor, num_front_matter_pages = 0
colophon = (doc.instance_variable_get :@colophon) || (doc.sections.find {|sect| sect.sectname == 'colophon' })
return super unless colophon
go_to_page toc_page_number unless (page_number == toc_page_number) || scratch?
if scratch?
(doc.instance_variable_set :@colophon, colophon).parent.blocks.delete colophon
else
# if doctype=book and media=prepress, use blank page before table of contents
go_to_page page_number.pred if @ppbook
colophon.set_option 'nonfacing' # ensure colophon is configured to be non-facing
convert_section colophon
go_to_page page_number.next
end
offset = @ppbook ? 0 : 1
toc_page_numbers = super doc, num_levels, (toc_page_number + offset), start_cursor, num_front_matter_pages
scratch? ? ((toc_page_numbers.begin - offset)..toc_page_numbers.end) : toc_page_numbers
end
end
It’s important to note that this converter, as written, assumes the colophon fits on a single page. More effort would be needed to accomodate a multi-page colophon using an extended converter only. Thus, you are better off using the configuration-based approach described above.
License page
Let’s say you want to insert a license page into your documents, but you don’t want to have to put a block macro for it in the document source. You can use an extended converter to add new pages to the body of the document.
Let’s consider the case of reading the license text from a file and inserting it into the first page of the body.
class PDFConverterLicensePage < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def traverse node
return super unless node.context == :document
start_new_page unless at_page_top?
theme_font :heading, level: 2 do
ink_heading 'License', level: 2
end
license_text = File.read 'LICENSE'
theme_font :code do
ink_prose license_text, normalize: false, align: :left, color: theme.base_font_color
end
start_new_page
super
end
end
The method start_new_page
will create a new page in the document.
The ink_prose
method provides a normalize
option.
When this option is false, it will preserve the newlines in the content, which is what we want in the case of license text.
You may want to take this a bit further and allow the location of the license file to be configurable.
Paragraph numbering
To help with content auditing or correlation, you may want to add a number in front of each paragraph.
You can do this first by assigning a number to each paragraph in the document in the init_pdf
method.
Then, you can add this number in the left margin at the start of each paragraph by overriding the convert_paragraph
method.
class PDFConverterNumberedParagraphs < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def init_pdf doc
doc
.find_by(context: :paragraph) {|candidate| [:document, :section].include? candidate.parent.context }
.each_with_index {|paragraph, idx| paragraph.set_attr 'number', idx + 1 }
super
end
def convert_paragraph node
if (paragraph_number = node.attr 'number')
float do
label = %(#{paragraph_number}.#{::Prawn::Text::NBSP})
label_width = rendered_width_of_string label
bounding_box [-label_width, cursor], width: label_width do
ink_prose label, color: 'CCCCCC', align: :right, margin: 0, single_line: true
end
end
end
super
end
end
No running content on empty page
If a page is labeled as imported, Asciidoctor PDF will not add running content to that page. Thus, you can use an extended converter to turn off the running content on otherwise empty pages by marking them as imported. You can access this property from the pages attached to the PDF state or you can switch to each page in turn, as shown in the commented code.
Instead of marking pages as imported, you can add them to the set of pages, by page number, on which the running content will not be added.
These sets are stored in the :header
and :footer
keys of the @disable_running_content
instance variable.
This benefit of this approach is that you can control the header and footer independently.
class NoRunningContentOnEmptyPageConverter < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def ink_running_content(*)
state.pages.each do |page_|
page_.imported if page_.empty?
end
# or you can switch to each page first in case you need to use additional logic
# pgnum = page_number
#(1..page_count).each do |pgnum_|
# go_to_page pgnum_
# page.imported if page.empty?
#end
# go_to_page pgnum
# or you can add the page numbers to the sets of page numbers on which the running content is disabled
#state.pages.each_with_index do |page_, idx|
# next unless page_.empty?
# pgnum = idx + 1
# @disable_running_content[:header] << pgnum
# @disable_running_content[:footer] << pgnum
#end
super
end
end
This converter does not attempt to detect pages that are empty to make the next page facing (i.e., empty verso pages). Therefore, you may want to add a filter to only turn off the running content on those pages.
Change bars
If you have a preprocessor that adds change metadata to the content, you can use an extended converter to draw change bars to add a visual indicator in the rendered output.
class PDFConverterChangeBars < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def convert_paragraph node
start_cursor = cursor
super
if node.role? 'changed'
float do
bounding_box [bounds.left - 4, start_cursor], width: 2, height: (start_cursor - cursor) do
fill_bounds 'FF0000'
end
end
end
end
end
This converter will look for paragraphs like this one:
[.changed]
This line has been changed.
Avoid break after heading
This functionality is already provided by the converter if you set the breakable
option on section title or discrete heading or you set the heading-min-height-after
theme key to auto
.
The code is presented here both to explain how it works and show how to do it programmatically (perhaps to tune it for specific headings).
If an in-flow heading is followed by content that doesn’t fit on the current page, and the breakable
option is not set on the heading, the converter will orphan the heading on the current page.
You can fix this behavior by overriding the arrange_heading
method in an extended converter.
This extended converter takes this opportunity to use dry_run
to make an attempt to write content in the remaining space on the page after the heading.
If no content is written, it advances to the next page before inking the heading (and its corresponding anchor).
class PDFConverterAvoidBreakAfterSectionTitle < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def arrange_heading node, title, opts
return if y >= page_height / 3 (1)
orphaned = nil
dry_run single_page: true do (2)
start_page = page
theme_font :heading, level: opts[:level] do
if opts[:part]
ink_part_title node, title, opts (3)
elsif opts[:chapterlike]
ink_chapter_title node, title, opts (3)
else
ink_general_heading node, title, opts (3)
end
end
if page == start_page
page.tare_content_stream
orphaned = stop_if_first_page_empty do (4)
if node.context == :section
traverse node
else # discrete heading
convert (siblings = node.parent.blocks)[(siblings.index node).next]
end
end
end
end
advance_page if orphaned (5)
nil
end
end
1 | An optional optimization to skip this logic if the cursor is above the bottom third of the page. |
2 | Initiate a dry run up to the end of the current page. |
3 | Render the heading as normal. |
4 | Proceed with converting content until the end of the page is reached. Returns true if content is written, false otherwise. |
5 | Start new page before rendering heading if orphaned. |
Additional TOC entries
By default, the table of contents (TOC) only includes section references.
If you want to include additional entries in the TOC, or to filter the sections that are included, you can extend the converter and override the get_entries_for_toc
method.
This method is invoked for each parent entry in the TOC, starting from the document.
class PDFConverterAdditionalTOCEntries < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def get_entries_for_toc node
return super if node.context == :document
node.blocks.select do |candidate|
candidate.context == :section ||
(candidate.id && (candidate.title? || candidate.reftext?))
end
end
end
The depth of the TOC is automatically controlled by the toclevels
attribute.
Once this limit is reached, the converter will not call get_entries_for_toc
for that parent (as none of its children will be included in the TOC).
Breakable tables
As explained on Breakable and Unbreakable Blocks, tables are not configured with orphan prevention of the anchor and title by default.
In order to activate this behavior, the breakable
option must be specified on the table.
To avoid having to add this option on every table, you can use an Asciidoctor extension to add it at runtime. This use case employs a tree processor rather than an extended PDF converter, though its behavior does impact conversion.
Asciidoctor::Extensions.register do
tree_processor do
process do |doc|
doc.find_by context: :table do |table|
unless (table.option? 'breakable') || (table.option? 'unbreakable')
table.set_option 'breakable'
end
end
doc
end
end
end
This same technique can be used to add the breakable
or unbreakable
option at runtime to any blocks of your choosing.
Narrow TOC
Let’s say you want to make the content on the TOC page(s) really narrow.
You can do so by overriding the ink_toc
method and squeezing the margins by applying extra indentation.
class PDFConverterNarrowTOC < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def ink_toc *_args
indent 100, 100 do
super
end
end
end
Indent block image
If you want all (or some) block images to be indented by an amount specified in the theme, you can override the convert handler method for block images, convert_image
, and call super within an indented context.
class PDFConverterImageIndent < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def convert_image node
if (image_indent = theme.image_indent)
indent(*Array(image_indent)) { super }
else
super
end
end
end
The indent
DSL method adds padding to either side of the content area, delegates to the specified code block, then shaves it back off.
This converter works when a custom theme defines the image-indent
key, as follows:
extends: default
image:
indent: [0.5in, 0]
Look for images in multiple dirs
By default, an AsciiDoc converter only supports resolving images from a single location, the value of the imagesdir
attribute.
You can use an extended converter to have Asciidoctor PDF look in multiple locations until it finds the image.
class PDFConverterMultipleImagesdirs < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def resolve_image_path node, image_path, image_format, relative_to = true
if relative_to == true
unless File.file? image_path
docdir = (doc = node.document).attr 'docdir'
%w(imagesdir imagesdir2).each do |attr_name|
imagesdir = (doc.attr attr_name) || ''
abs_imagesdir = File.absolute_path imagesdir, docdir
next unless File.file? (File.absolute_path image_path, abs_imagesdir)
relative_to = abs_imagesdir
break
end
end
end
super
end
end
If you need the converter to support more than two locations, update the list of attribute names in the extended converter.
Language label on code block
The built-in HTML converter inserts a source language label in the upper right corner of the code block, which appears on hover. You can use an extended converter to imprint a fixed label in the PDF output.
To add this label, you’ll need to override the arrange_block
method of the converter.
This method arranges content blocks that have a border and/or background or support unbreakable, such as code blocks.
The override needs to filter the arguments for a node that has the source
style and language
attribute.
If the method detects that combination, it must decorate the callback passed via the &block
argument to inject the extra logic.
Otherwise, the method should delegate directly to super
.
When a code block is detected, the decorator should first call the block argument using instance_exec
.
Then, it should look to see if the extent is set and that this is not a dry run.
The extent provides information about where the background and border of the code block started.
The extended converter should move to that page and cursor, reapply the code block padding, and ink the label using the code font settings.
class PDFConverterSourceLanguageLabel < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def arrange_block node, &block
return super unless node.style == 'source' && (lang = node.attr 'language')
super node do |extent|
return_val = instance_exec extent, &block
if extent && !scratch?
float do
go_to_page extent.from.page
bounds.current_column = extent.from.column if ColumnBox === bounds
move_cursor_to extent.from.cursor
pad_box theme.code_padding, node do
theme_font :code do
ink_prose lang,
align: :right,
text_transform: :uppercase,
margin: 0,
color: theme.quote_cite_font_color
end
end
end
end
return_val
end
end
end
The way this extended converter is written, the label is inked on top of the inked code block. You’re free to customize where the label is placed. The float method allows you to move the cursor around in absolute space without impacting the flow of the content. The extent gives you the information about the location of the code block.
Wrap code blocks around an image float
Asciidoctor PDF provides basic support for image floats. It will wrap paragraph text on the opposing side of the float. However, if it encounters a non-paragraph, the converter will clear the float and continue positioning content below the image.
As a companion to this basic support, the converter provides a framework for broadening support for float wrapping.
We can take advantage of this framework in an extended converter.
By extending the converter and overriding the supports_float_wrapping?
method as well as the convert handler for the block you want to enlist (e.g., convert_code
), you can arrange additional content into the empty space adjacent to the floated image.
In the following example, code (listing and literal) blocks are included in the float wrapping.
class PDFConverterCodeFloatWrapping < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def supports_float_wrapping? node
%i(paragraph listing literal).include? node.context
end
def convert_code node
return super unless (float_box = @float_box ||= nil)
indent(float_box[:left] - bounds.left, bounds.width - float_box[:right]) { super }
@float_box = nil unless page_number == float_box[:page] && cursor > float_box[:bottom]
end
end
You can configure the gap next to and below the image using the image-float-gap
key in the theme.
extends: default
image:
float-gap: [12, 6]
Theme table using roles
The converter only supports custom roles on paragraphs and phrases. You can use an extended converter to add this capability to tables.
class PDFConverterTableRole < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def convert_table node
if node.role?
key_prefix = %(role_<table>_#{node.roles[0]}_)
unless (role_entries = theme.each_pair.select {|name, val| name.to_s.start_with? key_prefix }).empty?
save_theme do
role_entries.each do |name, val|
theme[%(table_#{name.to_s.delete_prefix key_prefix})] = val
end
super
end
return
end
end
super
end
end
This extended converter allows you to specify any theme key on the custom role that’s supported for tables.
The role must be defined under a special role name <table>
(to avoid clashing with other role names).
Here’s an example of a custom table role named heavy
that increases the width of the table border and grid lines and increases the font size.
extends: default
role:
<table>:
heavy:
border-width: 1.5
grid-width: 1.5
font-size: 12.5
You apply this role to a table by prepending .heavy
to the first positional attribute in the block attribute line above the table.
[.heavy,cols=2*]
|===
|big
|data
|===
As written, the extended converter only supports the first role on the table. It could be enhanced to support an arbitrary number of roles, with each successive role cascading (like CSS).
You can use the technique shown in this extended converter to add role-based theming to any other block type recognized by the theme (e.g., code, sidebar, etc). |
Theme admonition per type
Similarly to the custom table role, we can use an extended converter to add support for theme keys per admonition type.
class PDFConverterAdmonitionThemePerType < (Asciidoctor::Converter.for 'pdf')
register_for 'pdf'
def convert_admonition node
type = node.attr 'name'
key_prefix = %(admonition_#{type}_)
entries = theme.each_pair.select {|name, val| name.to_s.start_with? key_prefix }
return super if entries.empty?
save_theme do
entries.each do |name, val|
theme[%(admonition_#{name.to_s.delete_prefix key_prefix})] = val
end
super
end
end
end
This converter temporarily promotes keys under the admonition-<type>
theme category to the admonition
theme category, overriding any existing keys.
The placeholder <type>
represents the admonition type; caution, important, note, tip, or warning.
Here’s an example that shows how you’d use the theme to apply a border to the important admonition type when using this extended converter:
admonition:
important:
border-color: #BF0000
border-width: 1
column-rule-width: 0
padding: 12
Multiple columns
Starting with Asciidoctor PDF 2.1, this converter provides built-in support for multiple columns. This feature is available when the doctype is article or manpage, but not book. The columns get applied to the body of the document, which excludes the document title and TOC, if present.
The Asciidoctor PDF converter also provides the framework for making multi-column layouts in an extended converter.
This framework is accessible via the helper method column_box
.
To make a multi-column layout, you put statements that ink content inside a code block and pass it to the column_box
method as follows:
column_box [bounds.left, cursor], columns: 2, width: bounds.width, reflow_margins: true do
ink_prose 'left column'
bounds.move_past_bottom
ink_prose 'right column'
end
If you want a multi-column layout for a specific chapter or section, you can override the traverse
method, look for the section you want to arrange, and wrap the call to super
in a column_box
enclosure.
Access page number from inline macro
Although not an extended converter, this use case uses information from the converter in much the same way. In this case, we’re interested in retrieving the page number and inserting it into the content.
Let’s create an inline macro named pagenum
that inserts the current page number into the document when the macro is converted.
Asciidoctor::Extensions.register do
inline_macro :pagenum do
format :short
process do |parent|
create_inline parent, :quoted, parent.document.converter.page_number.to_s
end
end
end
Here’s how this macro would be used.
= Document Title
:doctype: book
You're looking at page number pagenum:[].
We can build on this extension to show the start page of the current section by adding support for a scope parameter. We can also have it show the page number label instead of the physical page number by subtracting the start page number (which is stored on the index catalog).
Asciidoctor::Extensions.register do
inline_macro :pagenum do
format :short
parse_content_as :text
process do |parent, scope|
doc = parent.document
if scope == 'section'
if doc.nested?
inner_doc = doc
parent = (doc = doc.parent_document).find_by(context: :table_cell) do |it|
it.style == :asciidoc && it.inner_document == inner_doc
end.first
end
section = (closest parent, :section) || doc
physical_pagenum = section.attr 'pdf-page-start'
else
physical_pagenum = doc.converter.page_number
end
create_inline parent, :quoted, %(#{physical_pagenum + 1 - (start_page_number doc)})
end
def closest node, context
node.context == context ? node : ((parent = node.parent) && (closest parent, context))
end
def start_page_number doc
doc.converter.index.start_page_number
end
end
end
The macro can now be used to show the page number label for the current section:
= Document Title
:doctype: book
== Chapter A
You're reading a section that begins on page pagenum:[section].
Taking inspiration from this extension, we develop another inline macro named pageref
that resolves the page number of the closest parent section of a reference.
Asciidoctor::Extensions.register do
inline_macro :pageref do
process do |parent, refid|
doc = (doc = parent.document).nested? ? doc.parent_document : doc
if (ref = doc.catalog[:refs][refid])
section = (closest ref, :section) || doc
unless (physical_pagenum = section.attr 'pdf-page-start')
doc.instance_variable_set :@pass, 1 unless (doc.instance_variable_get :@pass) == 2
next create_inline parent, :quoted, '00' # reserve space for real page number
end
attributes = { 'refid' => refid, 'fragment' => refid, 'path' => nil }
create_anchor parent, %(#{physical_pagenum + 1 - (start_page_number doc)}), { type: :xref, attributes: attributes }
else
create_inline parent, :quoted, '???'
end
end
def closest node, context
node.context == context ? node : ((parent = node.parent) && (closest parent, context))
end
def start_page_number doc
doc.converter.index.start_page_number
end
end
postprocessor do
process do |doc|
if (doc.instance_variable_get :@pass) == 1
doc.instance_variable_set :@pass, 2
doc.convert # WARNING: this may have side effects
end
doc.converter
end
end
end
The only caveat of this extension is that it has to use a two-phase conversion. In other words, it has to convert the document a second time to resolve any forward references. That’s because the page number of a section is not known until it is rendered. And not all sections are rendered until the first conversion is complete.
Here’s how the pageref
macro would be used:
= Document Title
:doctype: book
== Chapter A
Content.
== Chapter B
Refer to <<_chapter_a>> on page pageref:_chapter_a[].
Resources
To find even more examples of how to override the behavior of the converter, refer to the extended converter in the InfoQ Mini-Book template.