https://github.com/asciidoctor/asciidoctor-extensions-lab

A lab for testing and demonstrating Asciidoctor extensions. Please do not use this code in production. If you want to use one of these extensions in your application, create a new project, import the code, and distribute it as a RubyGem. You can then request to make it a top-level project under the Asciidoctor organization.
https://github.com/asciidoctor/asciidoctor-extensions-lab

Last synced: 4 days ago
JSON representation

A lab for testing and demonstrating Asciidoctor extensions. Please do not use this code in production. If you want to use one of these extensions in your application, create a new project, import the code, and distribute it as a RubyGem. You can then request to make it a top-level project under the Asciidoctor organization.

• Host: GitHub
• URL: https://github.com/asciidoctor/asciidoctor-extensions-lab
• Owner: asciidoctor
• License: other
• Created: 2014-02-07T07:59:01.000Z (almost 11 years ago)
• Default Branch: main
• Last Pushed: 2024-02-29T21:51:19.000Z (8 months ago)
• Last Synced: 2024-10-29T16:58:17.539Z (11 days ago)
• Language: Ruby
• Homepage:
• Size: 328 KB
• Stars: 105
• Watchers: 18
• Forks: 101
• Open Issues: 26
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE.adoc

Awesome Lists containing this project

README

        
= Asciidoctor Extensions Lab

:idprefix:

:idseparator: -

:toc: preamble

ifndef::env-github[:icons: font]

ifdef::env-github[]

:toclevels: 1

:!toc-title:

:note-caption: :paperclip:

:tip-caption: :bulb:

:warning-caption: :warning:

endif::[]

This repository is a lab for experimenting with Ruby-based Asciidoctor extensions using the Extensions API.

*Please do not use this code in production.*

The code is untested.

It is also not packaged and distributed.

The purpose of these examples is to demonstrate how extensions are set up, how to write them, and what they can do.

The examples also offer patterns that can be reused when implementing your own extension.

In order to use the extensions in this repository, you need to clone the repository.

Then, you need to pass the location of the extension you want to use to Asciidoctor using the `-r` CLI option or require it in your Ruby script if you are using the Asciidoctor API.

If you only want to test the extensions in this repository, skip ahead to <>.

If you want to use one of the extensions from this lab in production, and perhaps develop it further, please import it into a new project and distribute it as a RubyGem.

If you're prepared to maintain it for the community, you can submit a request in the https://asciidoctor.zulipchat.com[project chat] to graduate it a top-level project in the Asciidoctor organization.

When writing your own extension, we recommend that you study the https://docs.asciidoctor.org/asciidoctor/latest/extensions/[extensions section] in the Asciidoctor documentation.

== 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/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:

* https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro.rb[lib/emoji-inline-macro.rb] (registration file)

* https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro/extension.rb[lib/emoji-inline-macro/extension.rb] (extension file)

* https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro/sample.adoc[lib/emoji-inline-macro/sample.adoc] (sample AsciiDoc file)

* https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro/twemoji-awesome.css[lib/emoji-inline-macro/twemoji-awesome.css] (auxiliary asset file)

NOTE: The registration file (e.g., emoji-inline-macro.rb) goes in the [path]_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.

When the registration of the extension is in a separate file from the extension code, you require the registration file.

AutoXrefTreeprocessor (link:lib/autoxref-treeprocessor.rb[registration & extension code])::

Refers images, tables, listings, sections by their numbers.

BackToTopDocinfoProcessor (link:lib/back-to-top-docinfo-processor.rb[registration & extension code])::

Adds a floating back to top button to the bottom right corner of the page.

pass:m[ChartBlockMacro]::

Adds a chart block and block macro to AsciiDoc powered by c3js, chartist or chartjs.

_Replaced by https://github.com/asciidoctor/asciidoctor-chart/[Asciidoctor Chart]._

ChromeInlineMacro (link:lib/chrome-inline-macro.rb[registration], link:lib/chrome-inline-macro/extension.rb[extension code])::

Adds an inline macro for linking to a `chrome://` URI.

CopyToClipboardDocinfoProcessor (link:lib/copy-to-clipboard-docinfo-processor.rb[registration], link:lib/copy-to-clipboard-docinfo-processor/extension.rb[extension code])::

Adds a source toolbox with a copy to clipboard button to all source blocks.

CopyrightFooterPostprocessor (link:lib/copyright-footer-postprocessor.rb[registration], link:lib/copyright-footer-postprocessor/extension.rb[extension code])::

Adds a copyright to the document footer based on the value of the `copyright` attribute.

CustomAdmonitionBlock (link:lib/custom-admonition-block.rb[registration], link:lib/custom-admonition-block/extension.rb[extension code])::

Introduces a new admonition block type, complete with a custom icon.

DocstatInlineMacro (link:lib/docstat-inline-macro.rb[registration], link:lib/docstat-inline-macro/extension.rb[extension code])::

A macro that displays the word count and estimated reading time of the current document.

DumpAttributesBlockMacro (link:lib/dump-attributes-block-macro.rb[registration & extension code])::

Dumps the document attributes as attribute entries in a source block.

EmojiInlineMacro (link:lib/emoji-inline-macro.rb[registration], link:lib/emoji-inline-macro/extension.rb[extension code])::

Adds an emoji inline macro for inserting emoji by name.

EnableSourcemapPreprocessor (link:lib/enable-sourcemap-preprocessor.rb[registration & extension code])::

Specifies sourcemap attribute for document.

ExternalHeaderAttributesPreprocessor (link:lib/external-header-attributes-preprocessor.rb[registration], link:lib/external-header-attributes-preprocessor/extension.rb[extension code])::

Reads additional AsciiDoc attributes from a YAML-based configuration file and adds them to the document header.

FoldLinesTreeProcessor (link:lib/fold-lines-tree-processor.rb[registration & extension code])::

Replaces newlines (i.e., line feeds) in paragraphs with a single space.

FootnotesBlockMacro (link:lib/footnotes-block-macro.rb[registration], link:lib/footnotes-block-macro/extension.rb[extension code])::

Consumes the footnotes from the document catalog and puts them into a dedicated section.

FrontMatterPreprocessor (link:lib/front-matter-preprocessor.rb[registration], link:lib/front-matter-preprocessor/extension.rb[extension code])::

Emulates the built-in behavior of Asciidoctor to sweep away YAML front matter into the `front-matter` attribute.

GitMetadataInlineMacro (link:lib/git-metadata-inline-macro.rb[registration], link:lib/git-metadata-inline-macro/extension.rb[extension code])::

Provide information on references using a macro (e.g. commits, branches and tags).

GitMetadataPreprocessor (link:lib/git-metadata-preprocessor.rb[registration], link:lib/git-metadata-preprocessor/extension.rb[extension code])::

Provide information on the local git repository, e.g. the branch or tag name or the commit id.

GistBlockMacro (link:lib/gist-block-macro.rb[registration], link:lib/gist-block-macro/extension.rb[extension code])::

Adds a block macro to embed a gist into an AsciiDoc document.

GlobIncludeProcessor (link:lib/glob-include-processor.rb[registration], link:lib/glob-include-processor/extension.rb[extension code])::

Enhances the include directive to support a glob expression to include all matching files.

GoogleAnalyticsDocinfoProcessor (link:lib/google-analytics-docinfoprocessor.rb[registration & extension code])::

Adds the Google Analytics code for the account identified by the `google-analytics-account` attribute to the bottom of the HTML document.

HardbreaksPreprocessor (link:lib/hardbreaks-preprocessor.rb[registration & extension code])::

Adds hardbreaks to the end of all non-empty lines that aren't section titles.

HighlightTreeprocessor (link:lib/highlight-treeprocessor.rb[registration & extension code])::

Highlights source blocks using the highlight command.

ImplicitApidocInlineMacro (link:lib/implicit-apidoc-inline-macro.rb[registration & extension code])::

Adds an inline macro for linking to the Javadoc of a class in the Java EE API.

ImplicitHeaderIncludeProcessor (link:lib/implicit-header-include-processor.rb[registration], link:lib/implicit-header-include-processor/extension.rb[extension code])::

Skips the implicit author line below the document title in included documents.

LicenseUrlDocinfoProcessor (link:lib/license-url-docinfoprocessor.rb[registration & extension code])::

Adds a link to the license specified by the `license` attribute to the document header.

LoremBlockMacro (link:lib/lorem-block-macro.rb[registration & extension code])::

Generates lorem ipsum text using the Middleman lorem extension. (Requires middleman >= 4.0.0).

ManInlineMacro (link:lib/man-inline-macro.rb[registration], link:lib/man-inline-macro/extension.rb[extension code])::

Adds an inline macro for linking to another man page (used in the Git documentation).

pass:m[MathematicalTreeprocessor]::

Converts all latexmath blocks to SVG using the Mathematical library.

_Replaced by https://github.com/asciidoctor/asciidoctor-mathematical/[Asciidoctor Mathematical]._

MarkdownLinkInlineMacro (link:lib/markdown-link-inline-macro.rb[registration & extension code])::

Parses a Markdown-style link.

MentionsInlineMacro (link:lib/mentions-inline-macro.rb[registration & extension code])::

Detects Twitter-style username mentions and converts them to links.

MultipageHtml5Converter (link:lib/multipage-html5-converter.rb[registration & extension code])::

A converter that chunks the HTML5 output into multiple pages.

This extension is merely a proof of concept.

You can find a complete implementation of a multipage HTML converter at https://github.com/owenh000/asciidoctor-multipage.

MultirowTableHeaderTreeProcessor (link:lib/multirow-table-header-tree-processor.rb[registration & extension code])::

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.

NestedOpenBlock (link:lib/nested-open-block.rb[registration & extension code])::

Allows open blocks to be nested by repurposing the example container as an open block.

NumberParagraphsTreeProcessor (link:lib/number-paragraphs-tree-processor.rb[registration], link:lib/number-paragraphs-tree-processor/extension.rb[extension code])::

Naively numbers paragraphs based on position.

PassBlockMacro (link:lib/pass-block-macro.rb[registration], link:lib/pass-block-macro/extension.rb[extension code])::

Adds a pass block macro to AsciiDoc.

PickInlineMacro (link:lib/pick-inline-macro.rb[registration & extension code])::

Adds an inline macro for selecting between two values based on the value of another attribute.

PullquoteInlineMacro (link:lib/pullquote-inline-macro.rb[registration], link:lib/pullquote-inline-macro/extension.rb[extension code])::

Adds an inline macro to pull a quote out of the flow and display it in a sidebar.

RubyAttributesPreprocessor (link:lib/ruby-attributes-preprocessor.rb[registration], link:lib/ruby-attributes-preprocessor/extension.rb[extension code])::

Makes information about the Ruby runtime available to the document by defining document attributes for all constants that begin with RUBY_ (e.g, ruby-version).

SectnumoffsetTreeprocessor (link:lib/sectnumoffset-treeprocessor.rb[registration & extension code])::

Increments all level-1 section numbers (and subsequently all subsections) by the value of the `sectnumoffset` attribute.

ShellSessionTreeProcessor (link:lib/shell-session-treeprocessor.rb[registration], link:lib/shell-session-treeprocessor/extension.rb[extension code])::

Detects a shell command and trailing output and styles it for display in HTML.

ShoutBlock (link:lib/shout-block.rb[registration], link:lib/shout-block/extension.rb[extension code])::

Converts all text inside a delimited block named `shout` to uppercase and adds trailing exclamation marks.

ShowCommentsPreprocessor (link:lib/showcomments-preprocessor.rb[registration & extension code])::

Converts line comments to visual elements (normally dropped).

SlimBlock (link:lib/slim-block.rb[registration], link:lib/slim-block/extension.rb[extension code])::

Passes the content in blocks named `slim` to the Slim template engine for processing.

StepsPostprocessor (link:lib/steps-postprocessor.rb[registration], link:lib/steps-postprocessor/extension.rb[extension code])::

Styles an ordered list as a procedure list.

TelInlineMacro (link:lib/tel-inline-macro.rb[registration & extension code])::

Adds an inline macro for linking to a `tel:` URI.

TermInlineMacro (link:lib/term-inline-macro.rb[registration & extension code])::

Demonstrates how to convert an inline macro into a span of text with a role.

TexPreprocessor (link:lib/tex-preprocessor.rb[registration], link:lib/tex-preprocessor/extension.rb[extension code])::

Interprets tex markup embedded inside of AsciiDoc.

TextqlBlock (link:lib/textql-block.rb[registration & extension code])::

Adds a block for using textql to process data in an AsciiDoc document.

TreeBlockMacro (link:lib/tree-block-macro.rb[registration], link:lib/tree-block-macro/extension.rb[extension code])::

Adds a block macro to show the output of the `tree` command.

UndoReplacementsPostprocessor (link:lib/undo-replacements-postprocessor.rb[registration & extension code])::

Reverses the text replacements that are performed by Asciidoctor.

UriIncludeProcessor (link:lib/uri-include-processor.rb[registration], link:lib/uri-include-processor/extension.rb[extension code])::

Emulates the built-in behavior of Asciidoctor to include content from a URI.

ViewResultDocinfoProcessor (link:lib/view-result-docinfoprocessor.rb[registration], link:lib/view-result-docinfoprocessor/extension.rb[extension code])::

Adds an interactive toggle to block content marked as a view result.

WhitespaceIncludeProcessor (link:lib/whitespace-include-processor.rb[registration & extension code])::

An include processor that substitutes tabs with spaces (naively) in included source code.

XmlEntityPostprocessor (link:lib/xml-entity-postprocessor.rb[registration], link:lib/xml-entity-postprocessor/extension.rb[extension code])::

Converts named entities to character entities so they can be resolved without the use of external entity declarations.

////

//^

See also:

JIRAInlineMacro, https://github.com/jbosstools/jbosstools-website/blob/master/_ext/asciidoctor_extensions.rb::

Generates a link to the JIRA issue by issue number.

////

== 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, [path]_sample.html_, was created in the same directory as the source file, [path]_sample.adoc_.

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

._lib/emoji-inline-macro/sample.adoc_

[,asciidoc]

----

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_

[,html]

----



Faster than a !





This is an example of how you can  Asciidoctor and Twitter Emoji.



----


WARNING: Certain extensions require additional libraries.

Please consult the extension's registration file for details about what is required to use it.

== Adding an extension

You can find examples of various ways to define an extension in the link: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 [path]_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_

[,ruby]

----

Asciidoctor::Extensions.register do

  block do

    named :sample

    on_context :open

    process do |parent, reader, attrs|

      create_paragraph parent, reader.lines, attrs

    end

  end

end

----

=== Formal

If you're creating a more complex extension or want to enable reuse, you're encouraged to move the extension code to the [path]_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]

----

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

Asciidoctor::Extensions.register do

  block SampleBlock

end

----

._lib/sample-block/extension.rb_

[,ruby]

----

class SampleBlock < Asciidoctor::Extensions::BlockProcessor

  use_dsl

  named :sample

  on_context :open

  def process parent, reader, attrs

    create_paragraph parent, reader.lines, attrs

  end

end

----

It's customary to provide a sample AsciiDoc file named [path]_sample.adoc_ inside the extension subdirectory that others can use to try the extension.

You should also add your extension to the <> section along with a short description of what it does.

== Other extensions

See http://asciidoctor.org/docs/extensions/[this list] of official and community extensions for Asciidoctor.

Here are some other experimental extensions.

* https://launchpad.net/imagemap-block-processor[imagemap block processor] - Adds an image with an imagemap using targets specified in the contents of the block.

Note that this extension does not follow the standard use of block attrlists and is therefore considered to be experimental.

However, it could be a useful starting point for someone interesting in creating one that is more conventional.

You may also be interested in these extensions which were submitted, but never merged:

* https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/66[gallery block]

* https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/90[create section numbers tree processor]

* https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/67[icons for toc]

* https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/80[image sizing tree processor]

* https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/85[line number tree processor]

* https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/100[indir include processor]

* https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/113[figure numbering by chapter tree processor]

== Copyright

Copyright (C) 2014-present The Asciidoctor Project.

Free use of this software is granted under the terms of the MIT License.

See the link:LICENSE.adoc[LICENSE] file for details.