logo

asciidoctor filter

← Back to Filter List

asciidoctor


↓ examples

Runs `asciidoctor`.

Aliases for this filter

  • asciidoctor

Converts from file formats:

  • .*

To file formats:

  • .html
  • .xml
  • .tex

Available settings:

SettingDescriptionDefault
add-new-filesBoolean or list of extensions/patterns to match.False
added-in-versionDexy version when this filter was first available.
additional-doc-filtersFilters to apply to additional documents created as side effects.{}
additional-doc-settingsSettings to apply to additional documents created as side effects.{}
argsArguments to be passed to the executable.
backendAsciidoctor backend to use (optional, only to override default).None
check-return-codeWhether to look for nonzero return code.True
clargsArguments to be passed to the executable (same as 'args').
command-stringThe full command string.%(prog)s %(format)s %(args)s %(ss)s -o %(output_file)s %(script_file)s
data-typeAlias of custom data class to use to store filter output.generic
envDictionary of key-value pairs to be added to environment for runs.{}
examplesTemplates which should be used as examples for this filter.['asciidoctor']
exclude-add-new-filesList of patterns to skip even if they match add-new-files.[]
exclude-new-files-from-dirList of directories to skip when adding new files.[]
executableThe executable to be runasciidoctor
extFile extension to output.None
ext-to-formatA dict of mappings from file extensions to format parameters that need to be passed on the command line, e.g. for ghostscript .png => png16m{'.html': 'html5', '.tex': 'latex', '.xml': 'docbook5'}
extension-mapDictionary mapping input extensions to default output extensions.None
format-specifierThe string used to specify the format switch, include trailing space if needed.-b
helpHelpstring for plugin.Runs `asciidoctor`.
initial-timeout10
input-extensionsList of extensions which this filter can accept as input.['.*']
keep-originalsWhether, if additional-doc-filters are specified, the original unmodified docs should also be added.False
make-dummy-outputWhether to make a dummy output file when one is not generated and add-new-files is True.False
mkdirA directory which should be created in working dir.None
mkdirsA list of directories which should be created in working dir.[]
nodocWhether filter should be excluded from documentation.False
outputWhether to output results of this filter by default by reporters such as 'output' or 'website'.True
output-extensionsList of extensions which this filter can produce as output.['.html', '.xml', '.tex']
override-workspace-exclude-filtersIf True, document will be populated to other workspaces ignoring workspace-exclude-filters.False
path-extensionsstrings to extend path with[]
preserve-prior-data-classWhether output data class should be set to match the input data class.False
record-varsWhether to add code that will automatically record values of variables.False
require-outputShould dexy raise an exception if no output is produced by this filter?True
scriptargsArguments to be passed to the executable.
stylesheetCustom asciidoctor stylesheet to use.None
tagsTags which describe the filter.['asciidoc', 'html']
timeout10
use-wdWhether to use a custom working directory when running filter.True
variablesA dictionary of variable names and values to make available to this filter.{}
varsA dictionary of variable names and values to make available to this filter.{}
version-commandCommand to call to return version of installed software.asciidoctor --version
windows-version-commandCommand to call on windows to return version of installed software.None
workspace-exclude-filtersFilters whose output should be excluded from workspace.['pyg']
workspace-includesIf set to a list of filenames or extensions, only these will be populated to working dir.None
write-stderr-to-stdoutShould stderr be piped to stdout?True

Asciidoc Filter

The asciidoc filter takes asciidoc content, like this:

= Hello, AsciiDoc!
Doc Writer <doc@example.com>

An introduction to http://asciidoc.org[AsciiDoc].

== First Section

* item 1
* item 2

[source,ruby]
puts "Hello, World!"

And converts it using the asciidoc command:

- example1.adoc|asciidoctor

Custom asciidoctor stylesheets can be specified:

- example2.adoc|asciidoctor:
    - asciidoctor: { 'stylesheet' : 'readthedocs.css' }
Filter Source Code
class Asciidoctor(SubprocessExtToFormatFilter):
    """
    Runs `asciidoctor`.
    """
    aliases = ['asciidoctor']
    _settings = {
            'tags' : ['asciidoc', 'html'],
            'examples' : ['asciidoctor'],
            'output' : True,
            'version-command' : "asciidoctor --version",
            'executable' : 'asciidoctor',
            'input-extensions' : ['.*'],
            'output-extensions': ['.html', '.xml', '.tex'],
            'stylesheet' : ("Custom asciidoctor stylesheet to use.", None),
            'format-specifier': '-b ',
            'backend' : ("Asciidoctor backend to use (optional, only to override default).", None),
            'ext-to-format' : {
                '.html' : 'html5',
                '.xml': 'docbook5',
                '.tex' : 'latex'
                },
            'command-string': '%(prog)s %(format)s %(args)s %(ss)s -o %(output_file)s %(script_file)s'
            }

    def command_string_args(self):
        args = super(Asciidoctor, self).command_string_args()

        stylesheet = self.setting('stylesheet')
        if stylesheet is not None:
            stylesdir = os.path.abspath(os.path.join(os.path.dirname(__file__), 'asciidoctor'))

            if not os.path.exists(stylesdir):
                msg = "Asciidoctor stylesheet directory not found at '%s'"
                raise InternalDexyProblem(msg % stylesdir)

            args['ss'] = "-a stylesheet=%s -a stylesdir=%s" % (stylesheet, stylesdir)

            if not os.path.exists(os.path.join(stylesdir, stylesheet)):
                msg = "No stylesheet file named '%s' was found in directory '%s'. Files found: %s"
                stylesheets = os.listdir(stylesdir)
                raise UserFeedback(msg % (stylesheet, stylesdir, ", ".join(stylesheets)))

        else:
            args['ss'] = ''

        backend = self.setting('backend')
        if backend is not None:
            format_specifier = self.setting('format-specifier')
            args['format'] = "%s%s" % (format_specifier, backend)

        return args

Content © 2020 Dr. Ana Nelson | Site Design © Copyright 2011 Andre Gagnon | All Rights Reserved.