# asciidoctor/asciidoctor-extensions-lab

A lab and incubator for Asciidoctor extensions.
Ruby CSS Other
Switch branches/tags
Nothing to show
Latest commit 98f8d65 Jul 24, 2018

# Asciidoctor Extensions Lab

A repository of sample and incubating Ruby-based extensions for Asciidoctor.

If you simply want to use the extensions in this repository, skip ahead to Using an extension. To create your own extension, we recommend that you first read the extensions section in the Asciidoctor user manual.

## Extension types

We have the following types of extensions in the lab:

• Preprocessor - processes the AsciiDoc source before it is parsed

• IncludeProcessor - intercepts the AsciiDoc include directive

• TreeProcessor - processes the AsciiDoc document (AST) after block-level parsing is complete

• Postprocessor - processes the converted output before it is written to the output stream (or disk)

• DocinfoProcessor - contributes additional content to the header or footer of the output document

• BlockProcessor - adds a custom delimited block

• BlockMacroProcessor - adds a custom block macro

• InlineMacroProcessor - adds a custom inline macro

The type of extension (e.g, -block-macro) is always used in the name of the extension registration file and directory to make it easy to distinguish. You can also look for examples using git grep. For example, to look for a BlockMacroProcessor, run the following command:

$git grep BlockMacroProcessor lib/ You’ll get a result like this: lib/chart-block-macro/extension.rb:class ChartBlockMacro < Extensions::BlockMacroProcessor lib/gist-block-macro/extension.rb:class GistBlockMacro < Extensions::BlockMacroProcessor lib/pass-block-macro/extension.rb:class PassBlockMacro < Extensions::BlockMacroProcessor lib/tree-block-macro/extension.rb:class TreeBlockMacro < Asciidoctor::Extensions::BlockMacroProcessor ## Extension files Each extension consists of several files: • A file that registers the extension (sometimes also contains the extension) • A file with the extension itself (when not defined in the registration file) • A file with sample AsciiDoc source to use to test the extension • Auxiliary assets needed by the extension For example, the emoji-inline-macro extension has four files:  Note The registration file (e.g., emoji-inline-macro.rb) goes in the lib directory whereas the remaining files go inside a directory whose base name matches the name of the registration file (e.g., emoji-inline-macro). ## Extension catalog The following extensions are available in the lab. AutoXrefTreeprocessor, lib/autoxref-treeprocessor.rb Refers images, tables, listings, sections by their numbers. ChartBlockMacro, lib/chart-block-macro.rb Adds a chart block and block macro to AsciiDoc powered by c3js, chartist or chartjs. ChromeInlineMacro, lib/chrome-inline-macro.rb Adds an inline macro for linking to a chrome:// URI. CopyrightFooterPostprocessor, lib/copyright-footer-postprocessor.rb Adds a copyright to the document footer based on the value of the copyright attribute. CustomAdmonitionBlock, lib/custom-admonition-block.rb Introduces a new admonition block type, complete with a custom icon. DumpAttributesBlockMacro, lib/dump-attributes-block-macro.rb Dumps the document attributes as attribute entries in a source block. EmojiInlineMacro, lib/emoji-inline-macro.rb Adds an emoji inline macro for inserting emoji by name. FoldLinesTreeProcessor, lib/fold-lines-tree-processor.rb Replaces newlines (i.e., line feeds) in paragraphs with a single space. FrontMatterPreprocessor, lib/front-matter-preprocessor.rb Emulates the built-in behavior of Asciidoctor to sweep away YAML front matter into the front-matter attribute. GitMetadataPreprocessor, lib/git-metadata-preprocessor.rb Provide information on the local git repository, e.g. the branch or tag name or the commit id. GistBlockMacro, lib/gist-block-macro.rb Adds a block macro to embed a gist into an AsciiDoc document. GlobIncludeProcessor, lib/glob-include-processor.rb Enhances the include directive to support a glob expression to include all matching files. GoogleAnalyticsDocinfoProcessor, lib/google-analytics-docinfoprocessor.rb Adds the Google Analytics code for the account identified by the google-analytics-account attribute to the bottom of the HTML document. HardbreaksPreprocessor, lib/hardbreaks-preprocessor.rb Adds hardbreaks to the end of all non-empty lines that aren’t section titles. HighlightTreeprocessor, lib/highlight-treeprocessor.rb Highlights source blocks using the highlight command. ImplicitApidocInlineMacro, lib/implicit-apidoc-inline-macro.rb Adds an inline macro for linking to the Javadoc of a class in the Java EE API. LicenseUrlDocinfoProcessor, lib/license-url-docinfoprocessor.rb Adds a link to the license specified by the license attribute to the document header. LoremBlockMacro, lib/lorem-block-macro.rb Generates lorem ipsum text using the Middleman lorem extension. (Requires middleman >= 4.0.0). ManInlineMacro, lib/man-inline-macro.rb Adds an inline macro for linking to another man page (used in the Git documentation). MathematicalTreeprocessor, lib/mathematical-treeprocessor.rb Converts all latexmath blocks to SVG using the Mathematical library. Replaced by Asciidoctor Mathematical. MathoidTreeprocessor, lib/mathoid-treeprocessor.rb Converts all stem blocks to SVG using MathJax via the Mathoid library. MentionsInlineMacro, lib/mentions-inline-macro.rb Detects Twitter-style username mentions and converts them to links. MultipageHtml5Converter, lib/multipage-html5-converter.rb A simple converter that chunks the HTML5 output into multiple pages. Still far from complete. MultirowTableHeaderTreeProcessor, lib/multirow-table-header-tree-processor.rb Promotes additional rows from the table body to the table head(er). Number of header rows is controlled by the hrows attribute on the table block. PassBlockMacro, lib/pass-block-macro.rb Adds a pass block macro to AsciiDoc. PickInlineMacro, lib/pick-inline-macro.rb Adds an inline macro for selecting between two values based on the value of another attribute. PullquoteInlineMacro, lib/pullquote-inline-macro.rb Adds an inline macro to pull a quote out of the flow and display it in a sidebar. SectnumoffsetTreeprocessor, lib/sectnumoffset-treeprocessor.rb Increments all level-1 section numbers (and subsequently all subsections) by the value of the sectnumoffset attribute. ShellSessionTreeprocessor, lib/shell-session-treeprocessor.rb Detects a shell command and trailing output and styles it for display in HTML. ShoutBlock, lib/shout-block.rb Converts all text inside a delimited block named shout to uppercase and adds trailing exclamation marks. ShowCommentsPreprocessor, lib/showcomments-preprocessor.rb Converts line comments to visual elements (normally dropped). SlimBlock, lib/slim-block.rb Passes the content in blocks named slim to the Slim template engine for processing. StepsPostprocessor, lib/steps-postprocessor.rb Styles an ordered list as a procedure list. TelInlineMacro, lib/tel-inline-macro.rb Adds an inline macro for linking to a tel: URI. TexPreprocessor, lib/tex-preprocessor.rb Interprets tex markup embedded inside of AsciiDoc. TextqlBlock, lib/textql-block.rb Adds a block for using textql to process data in an AsciiDoc document. TreeBlockMacro, lib/tree-block-macro.rb Adds a block macro to show the output of the tree command. UndoReplacementsPostprocessor, lib/undo-replacements-postprocessor.rb Reverses the text replacements that are performed by Asciidoctor. UriIncludeProcessor, lib/uri-include-processor.rb Emulates the built-in behavior of Asciidoctor to include content from a URI. ViewResultDocinfoProcessor, lib/view-result-docinfoprocessor.rb Adds an interactive toggle to block content marked as a view result. WhitespaceIncludeProcessor, lib/whitespace-include-processor.rb An include processor that substitutes tabs with spaces (naively) in included source code. XmlEntityPostprocessor, lib/xml-entity-postprocessor.rb Converts named entities to character entities so they can be resolved without the use of external entity declarations. ## Using an extension Before creating your own extensions, it would be wise to run one yourself. First, make sure Asciidoctor is installed:$ gem install asciidoctor

Next, run the extension from the root directory of the project:

$asciidoctor -r lib/emoji-inline-macro.rb lib/emoji-inline-macro/sample.adoc # asciidoctor: FAILED: 'lib/emoji-inline-macro.rb' could not be loaded # Use --trace for backtrace Oops! We forgot to include the leading ./ when using the -r flag Let’s try again:$ asciidoctor -r ./lib/emoji-inline-macro.rb lib/emoji-inline-macro/sample.adoc

All right, it ran! The output file, sample.html, was created in the same directory as the source file, sample.adoc.

The relevant bits of the input and output are shown below.

Faster than a emoji:turtle[1x]!

This is an example of how you can emoji:heart[lg] Asciidoctor and Twitter Emoji.
lib/emoji-inline-macro/sample.html
<div class="paragraph">
<p>Faster than a <i class="twa twa-1x twa-turtle"></i>!</p>
</div>
<div class="paragraph">
<p>This is an example of how you can <i class="twa twa-lg twa-heart"></i> Asciidoctor and Twitter Emoji.</p>
</div>
 Warning Certain extensions require additional libraries. Please consult the extension’s registration file for details about what is required to use it.

You can find examples of various ways to define an extension in the lib/shout-block.rb extension.

### Shorthand (DSL)

If you’re creating a trivial extension, you can define the extension using the extension DSL directly in the registration file. Create a new file in the lib directory. Include the extension type in the name of the file so others are clear what type of extension it is.

lib/sample-block.rb
require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'

include Asciidoctor

Extensions.register do
block do
named :sample
on_context :open

end
end
end
 Tip The include Asciidoctor line allows you to use classes from Asciidoctor without the Asciidoctor:: prefix.

### Formal

If you’re creating a more complex extension or want to enable reuse, you’re encouraged to move the extension code to the extension.rb inside a directory with the same base name as the registration file. In the case of a block, block macro or inline macro, this enables you to register the extension multiple times.

lib/sample-block.rb
RUBY_ENGINE == 'opal' ? (require 'sample-block/extension') : (require_relative 'sample-block/extension')

Extensions.register do
block SampleBlock
end
lib/sample-block/extension.rb
class SampleBlock < Extensions::BlockProcessor
use_dsl
named :sample
on_context :open