NAME

Text::AsciidocDown - Lightweight AsciiDoc to Markdown conversion

SYNOPSIS

use Text::AsciidocDown;

my $converter = Text::AsciidocDown->new(
  attributes => {
    'markdown-list-indent' => 4,
  },
);

my $asciidoc = <<'ASCIIDOC';
= Hello, AsciidocDown

This is a *paragraph* with `inline` formatting.

== Section

Here is a list:

* one
* two
* three
ASCIIDOC

my $markdown = $converter->convert($asciidoc);
print $markdown;

DESCRIPTION

Text::AsciidocDown is a pure Perl, dependency-minimal converter intended to transform practical AsciiDoc documents into Markdown.

The module supports include pre-merge expansion (optional), parser conversion, and reference rewrite passes through a single OO interface.

METHODS

new

my $converter = Text::AsciidocDown->new(%opts);

Creates a converter object with default options.

Any option accepted by convert may also be provided here as a default. Per-call options override constructor defaults.

If no constructor options are provided, defaults are effectively empty.

Special merge behavior:

• attributes

  Constructor and per-call attributes hashes are merged key-by-key, with per-call keys taking precedence.

convert

my $md = $converter->convert($asciidoc, \%opts);

Converts AsciiDoc text to Markdown and returns the converted string.

If \%opts is not provided, constructor defaults are used as-is. If neither constructor defaults nor per-call options are provided, conversion runs with empty options (no runtime attributes and include pre-merge disabled).

Accepted options (constructor defaults and/or per call):

• attributes

  Hash reference containing runtime AsciiDoc attributes used by include pre-merge and parser stages.

  Default when unspecified: empty attribute set.

  Example:

  attributes => {
    'markdown-list-indent' => 4,
    'hide-uri-scheme' => '',
  }

• source_path

  Absolute or relative path to the input document being converted.

  Used for include pre-merge resolution and diagnostics when processing include::...[] directives.

  Default when unspecified: undefined (include resolution falls back to include.base_dir when needed).

• include

  Hash reference controlling include pre-merge behavior.

  Default when unspecified: include pre-merge is disabled.

  Supported keys:

  • enabled

    Boolean. When true, local include directives are expanded before parser conversion.

    Default: false.

  • base_dir

    Base directory used when resolving relative include targets and source_path is not available.

    Default: current working directory.

  • max_depth

    Maximum include recursion depth (default: 64).

  • on_missing

    Policy for missing include files: error, keep, or drop.

    Default: error.

  • on_cycle

    Controls what happens when include expansion detects an include loop, meaning a file includes itself through a chain

    Policy for include cycles: error, keep, or drop.

    Default: error.

  • restrict_to_base_dir

    Boolean. When true, include targets must resolve under base_dir.

    Default: false.

  • on_missing_tag

    Policy for missing include tag selectors (tag/tags): error, keep, or drop.

    Default: error.

  • on_bad_selector

    Policy for invalid selector syntax (for example lines=bad): error, keep, or drop.

    Default: error.

  • Policy values: error, keep, drop

    Shared behavior across on_missing, on_cycle, on_missing_tag, and on_bad_selector:

    C<error> - stop conversion and throw an error
    C<keep>  - keep the original C<include::...[]> line unchanged
    C<drop>  - remove the C<include::...[]> line from output

NOTES

- Include pre-merge currently supports local filesystem includes. - Include selector support includes tag, tags, and lines. - Some advanced Asciidoctor include and xref semantics remain intentionally conservative.

AUTHOR

Sandor Patocs

LICENSE

Same terms as Perl itself.