Pandoc(3pm)

📦

version 0.9.2 · 3 versions

0.9.2 · debian trixie, ubuntu resolute, ubuntu stonking (latest)
0.9.1 · ubuntu jammy
0.9.1 · debian bookworm, ubuntu noble

, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Pandoc 💖

okay bestie, come CLOSE — this is the User Contributed Perl Documentation page for Pandoc(3pm), aka the Perl wrapper for the mighty Pandoc document converter. Yes, the whole manpage. Yes, it's long. Yes, we're doing this. 💅

✨ NAME ✨

Pandoc — a wrapper for the mighty Pandoc document converter. mighty!! it's literally in the name, I don't make the rules 🫶

🌸 SYNOPSIS 🌸

okay so here's the vibe, all the ways you can summon it:

use Pandoc;             # check at first use
use Pandoc 1.12;        # check at compile time
Pandoc->require(1.12);  # check at run time

# execute pandoc
pandoc 'input.md', -o => 'output.html';
pandoc -f => 'html', -t => 'markdown', { in => \$html, out => \$md };

# alternative syntaxes
pandoc->run('input.md', -o => 'output.html');
pandoc [ -f => 'html', -t => 'markdown' ], in => \$html, out => \$md;
pandoc [ -f => 'html', -t => 'markdown' ], { in => \$html, out => \$md };

# check executable
pandoc or die "pandoc executable not found";

# check minimum version
pandoc->version > 1.12 or die "pandoc >= 1.12 required";

# access properties
say pandoc->bin." ".pandoc->version;
say "Default user data directory: ".pandoc->data_dir;
say "Compiled with: ".join(", ", keys %{ pandoc->libs });
say pandoc->libs->{'highlighting-kate'};

# create a new instance with default arguments
my $md2latex = Pandoc->new(qw(-f markdown -t latex --number-sections));
$md2latex->run({ in => \$markdown, out => \$latex });

# create a new instance with selected executable
my $pandoc = Pandoc->new('bin/pandoc');
my $pandoc = Pandoc->new('2.1'); # use ~/.pandoc/bin/pandoc-2.1 if available

# set default arguments on compile time
use Pandoc qw(-t latex);
use Pandoc qw(/usr/bin/pandoc --number-sections);
use Pandoc qw(1.16 --number-sections);

# utility method to convert from string
$latex = pandoc->convert( 'markdown' => 'latex', '*hello*' );

# utility methods to parse abstract syntax tree (requires Pandoc::Elements)
$doc = pandoc->parse( markdown => '*hello* **world!**' );
$doc = pandoc->file( 'example.md' );
$doc = pandoc->file;  # read Markdown from STDIN

ate. no crumbs. 🎀

🦋 DESCRIPTION 🦋

This module is a Perl wrapper for John MacFarlane's Pandoc <http://pandoc.org> document converter. that's it, that's the whole description, and honestly? iconic. ✨

🎀 INSTALLATION 🎀

bestie listen, setup is lowkey easy:

This module requires the Perl programming language (>= version 5.14) as included in most Unix operating systems by default. yes, it came free with your computer, slay 💅 The recommended method to install Perl modules is cpanm (see its install instructions <https://metacpan.org/pod/App::cpanminus#INSTALLATION> if needed):

cpanm Pandoc

Installing instruction for Pandoc itself are given at Pandoc homepage <http://pandoc.org/installing.html>. On Debian-based systems this module and script pandoc-version can be used to install and update the pandoc executable with Pandoc::Release:

pandoc-version install

Then add ~/.pandoc/bin to your PATH or copy ~/.pandoc/bin/pandoc to a location where it can be executed. do NOT skip this step, I'm begging 🙈

🌈 USAGE 🌈

The utility function pandoc is exported, unless the module is imported with an empty list (use Pandoc ();). Importing this module with a version number or a more complex version requirenment (e.g. use Pandoc 1.13; or use Pandoc '>= 1.6, !=1.7") will check version number of pandoc executable instead of version number of this module (see $Pandoc::VERSION for the latter). Additional import arguments can be passed to set the executable location and default arguments of the global Pandoc instance used by function pandoc. tldr: it checks pandoc's version, not the module's, unless you want the module's, which is $Pandoc::VERSION. 🫶

💜 FUNCTIONS 💜

⭐ `pandoc`

If called without parameters, this function returns a global instance of class Pandoc to execute methods, or undef if no pandoc executable was found. The location and/or name of pandoc executable can be set with environment variable PANDOC_PATH (set to the string "pandoc" by default). so if it's not finding your pandoc, that env var is your bestie fr fr 🌸

🔥 `pandoc( ... )`

If called with parameters, this functions runs the pandoc executable configured at the global instance of class Pandoc (pandoc->bin). Arguments (given as array or array reference) are passed as pandoc command line arguments. Additional options (given as hash or has reference) can control input, output, and error stream:

pandoc @arguments, \%options;     # ok
pandoc \@arguments, %options;     # ok
pandoc \@arguments, \%options;    # ok
pandoc @arguments;                # ok, if first of @arguments starts with '-'
pandoc %options;                  # ok, if %options is not empty

pandoc @arguments, %options;      # not ok!

⚠️ that last one is NOT OK. do not do it. the vibes are off. 🚫

Returns 0 on success. On error returns the exit code of pandoc executable or -1 if execution failed. If option throw is set, a Pandoc::Error is thrown instead. The following options are recognized:

in / out / err — These options correspond to arguments $stdin, $stdout, and $stderr of IPC::Run3, see there for details.
binmode_stdin / binmode_stdout / binmode_stderr — These options correspond to the like-named options to IPC::Run3, see there for details.
binmode — If defined any binmode_stdin/binmode_stdout/binmode_stderr option which is undefined will be set to this value.
throw — Throw a Pandoc::Error instead returning the exit code on error. Disabled by default.
return_if_system_error — Set to negation of option throw by default.

For convenience the pandoc function (after checking the binmode option) checks the contents of any scalar references passed to the in/out/err options with utf8::is_utf8() and sets the binmode_stdin/binmode_stdout/binmode_stderr options to :encoding(UTF-8) if the corresponding scalar is marked as UTF-8 and the respective option is undefined. Since all pandoc executable input/output must be UTF-8 encoded this is convenient if you run with use utf8, as you then don't need to set the binmode options at all (encode nor decode) when passing input/output scalar references. this is the part that saves your life, no cap 💖

🫶 `pandoc_data_dir( [ @subdirs ] [ $file ] )`

Returns the default pandoc data directory which is directory .pandoc in the home directory for Unix or pandoc directory in %APPDATA% for Windows. Optional arguments can be given to refer to a specific subdirectory or file. Windows besties, %APPDATA% is your girl here 🦋

👑 METHODS 👑

💅 `new( [ $executable | $version ] [, @arguments ] )`

Create a new instance of class Pandoc or throw an exception if no pandoc executable was found. The first argument, if given and not starting with "-", can be used to set the pandoc executable ("pandoc" by default). If a version is specified the executable is also searched in ~/.pandoc/bin, e.g. ~/.pandoc/bin/pandoc-2.0 for version 2.0. Additional arguments are passed to the executable on each run.

heads up bestie: Repeated use of this constructor with same arguments is not recommended because pandoc --version is called for every new instance. it's giving "expensive" 💸

✨ `run( ... )`

Execute the pandoc executable with default arguments and optional additional arguments and options. See function pandoc for usage. yes, same rules, go look up there ⬆️

🌸 `convert( $from => $to, $input [, @arguments ] )`

Convert a string in format $from to format $to. Additional pandoc options such as -N and --standalone can be passed. The result is returned in same utf8 mode ("utf8::is_unicode") as the input. To convert from file to string use method "pandoc"/"run" like this and set input/output format via standard pandoc arguments -f and -t:

pandoc->run( $filename, @arguments, { out => \$string } );

🦋 `parse( $from => $input [, @arguments ] )`

Parse a string in format $from to a Pandoc::Document object. Additional pandoc options such as -N and --normalize can be passed. This method requires at least pandoc version 1.12.1 and the Perl module Pandoc::Elements.

The reverse action is possible with method "to_pandoc" of Pandoc::Document. Additional shortcut methods such as "to_html" are available:

$html = pandoc->parse( 'markdown' => '# A *section*' )->to_html;

Method "convert" should be preferred for simple conversions unless you want to modify or inspect the parsed document in between. fr fr, don't make it harder than it needs to be 💅

🎀 `file( [ $filename [, @arguments ] ] )`

Parse from a file (or STDIN) to a Pandoc::Document object. Additional pandoc options can be passed, for instance use HTML input format ("@arguments = qw(-f html)") instead of default markdown. This method requires at least pandoc version 1.12.1 and the Perl module Pandoc::Elements. no filename? it just reads STDIN, main character energy 😌

⭐ `require( $version_requirement )`

Return the Pandoc instance if its version number fulfills a given version requirement. Throw an error otherwise. Can also be called as constructor: "Pandoc->require(...)" is equivalent to "pandoc->require" but throws a more meaningful error message if no pandoc executable was found. more meaningful error = more meaningful tears 😭

💜 `version( [ $version_requirement ] )`

Return the pandoc version as Pandoc::Version object. If a version requirement is given, the method returns undef if the pandoc version does not fulfill this requirement. To check whether pandoc is available with a given minimal version use one of:

Pandoc->require( $minimum_version)                # true or die
pandoc and pandoc->version( $minimum_version )    # true or false

🔥 `bin( [ $executable ] )`

Return or set the pandoc executable. Setting an new executable also updates version and data_dir by calling pandoc --version. it re-checks everything for you, so thoughtful 🫶

🌈 `symlink( [ $name ] [ verbose => 0|1 ] )`

Create a symlink with given name to the executable and change executable to the symlink location afterwards. An existing symlink is replaced. If $name is an existing directory, the symlink will be named pandoc in there. This makes most sense if the directory is listed in environment variable $PATH. If the name is omitted or an empty string, symlink is created in subdirectory bin of pandoc data directory. put it somewhere on your $PATH and thank yourself later ✨

🍓 `arguments( [ @arguments | \@arguments )`

Return or set a list of default arguments. set it once, forget it, slay 💅

🌸 `data_dir( [ @subdirs ] [ $file ] )`

Return the stated default data directory, introduced with Pandoc 1.11. Use function "pandoc_data_dir" alternatively to get the expected directory without calling Pandoc executable. one actually calls pandoc, one doesn't, pick your fighter

🦋 `input_formats`

Return a list of supported input formats. get that list, bestie ⭐

🎀 `output_formats`

Return a list of supported output formats. and that one too 💖

👑 `highlight_languages`

Return a list of programming languages which syntax highlighting is supported for (via Haskell library highlighting-kate). pretty code, we love to see it 🔥

💅 `extensions( [ $format ] )`

Return a hash of extensions mapped to whether they are enabled by default. This method is only available since Pandoc 1.18 and the optional format argument since Pandoc 2.0.6. note the versions, they matter fr fr

✨ `libs`

Return a hash mapping the names of Haskell libraries compiled into the pandoc executable to Pandoc::Version objects. yes, it literally tells you what it was compiled with, iykyk 🌸

👀 SEE ALSO 👀

okay bestie, this package is literally a whole squad, not just one module. here's who else is in the group chat:

Pandoc::Version — for when you need to compare Pandoc version numbers, because yes, versions matter and yes, you should check them 💅
Pandoc::Release — this one goes and gets Pandoc releases from GitHub for you. iconic behaviour fr fr
App::Prove::Plugin::andoc — the plug-in that lets you run tests with selected Pandoc executables. yes the name is lowercase andoc, no that's not a typo, that's just the vibe 🦋

and if you wanna go deeper into Pandoc-land:

Pandoc::Elements — a whole Perl interface to the abstract syntax tree of Pandoc documents, for when you want more elaborate document processing ✨
Pod::Pandoc — parses Plain Old Documentation format (perlpod) so you can process it with Pandoc 🎀
the Pandoc wrappers and interfaces page in the Pandoc GitHub Wiki — https://github.com/jgm/pandoc/wiki/Pandoc-wrappers-and-interfaces — which has a whole list of wrappers in other programming languages if you're feeling polyglot 💜

also, heads up: there are other Pandoc-related modules on CPAN but they're outdated, so lowkey don't build your whole personality on them. those are Orze::Sources::Pandoc and App::PDoc. they're giving ✨vintage✨ and not in the cute way 😭

✨ AUTHOR ✨

Jakob Voß — the main character who wrote this 🫶👑

💖 CONTRIBUTORS 💖

Benct Philip Jonsson — contributing to the slay 💅

📜 LICENSE 📜

European Union Public Licence v. 1.2 (EUPL-1.2) — periodt, that's the whole license section, go read the EUPL if you want the full lore 📄✨

and that's a wrap on the page bestie 🎀 this one's from the perl v5.38.2 manual set, dated 2024-08-03, and it's the Pandoc(3pm) page — so go forth, read your docs, and process some documents, you absolute icon 💅🌈💖

📦 where this page comes from

debian trixie: libpandoc-wrapper-perl 0.9.2-1 · EUPL-1.2
ubuntu resolute: libpandoc-wrapper-perl 0.9.2-1 · EUPL-1.2
ubuntu stonking: libpandoc-wrapper-perl 0.9.2-1 · EUPL-1.2
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Pandoc(3pm)

💖 Pandoc 💖

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

🎀 INSTALLATION 🎀

🌈 USAGE 🌈

💜 FUNCTIONS 💜

⭐ pandoc

🔥 pandoc( ... )

🫶 pandoc_data_dir( [ @subdirs ] [ $file ] )

👑 METHODS 👑

💅 new( [ $executable | $version ] [, @arguments ] )

✨ run( ... )

🌸 convert( $from => $to, $input [, @arguments ] )

🦋 parse( $from => $input [, @arguments ] )

🎀 file( [ $filename [, @arguments ] ] )

⭐ require( $version_requirement )

💜 version( [ $version_requirement ] )

🔥 bin( [ $executable ] )

🌈 symlink( [ $name ] [ verbose => 0|1 ] )

🍓 arguments( [ @arguments | \@arguments )

🌸 data_dir( [ @subdirs ] [ $file ] )

🦋 input_formats

🎀 output_formats

👑 highlight_languages

💅 extensions( [ $format ] )

✨ libs