Rand Stats






Render Pod to PDF via Cairo


From command line:

$ raku --doc=PDF lib/to/class.rakumod --save-as=class.pdf

From Raku:

use Pod::To::PDF;
use Cairo;


=code foobar.pl <options> files ...

my Cairo::Surface::PDF $pdf = pod2pdf($=pod, :save-as<foobar.pdf>);

Command Line Options:


File-name for the PDF output file. If not given, the output will be saved to a temporary file. The file-name is echoed to stdout.


Page width in points (default: 592)


Page height in points (default: 792)


Page margin in points (default: 20)


Disable table of contents


Disable index of terms


Add page numbers (bottom right)


From Raku code, the pod2pdf function returns a Cairo::Surface::PDF object which can be further manipulated, or finished to complete rendering.


This module does simple rendering of Pod to PDF documents via Cairo.

The generated PDF has a table of contents and is tagged for accessibility and testing purposes.

It uses HarfBuzz for font shaping and glyph selection and FontConfig for system font loading.


sub pod2pdf()

sub pod2pdf(
    Pod::Block $pod
) returns Cairo::Surface::PDF;

pod2pdf() Options

Str() :$save-as

A filename for the output PDF file.

Cairo::Surface::PDF :$surface

A surface to render to

UInt:D :$width, UInt:D :$height

The page size in points (there are 72 points per inch).

UInt:D :$margin

The page margin in points (default 20).

Hash :@fonts

By default, Pod::To::PDF loads system fonts via FontConfig. This option can be used to preload selected fonts.

use Pod::To::PDF;
use Cairo;
my @fonts = (
    %(:file<fonts/Raku-Bold.ttf>, :bold),
    %(:file<fonts/Raku-Italic.ttf>, :italic),
    %(:file<fonts/Raku-BoldItalic.ttf>, :bold, :italic),
    %(:file<fonts/Raku-Mono.ttf>, :mono),

my Cairo::Surface::PDF $pdf = pod2pdf($=pod, :@fonts, :save-as<out.pdf>);

Each font entry should have a file entry and various combinations of bold, italic and mono flags. Note that mono is used to render code blocks and inline code.

Str :%metadata

This can be used to preset values for title, subtitle, name, author or version.

This is an alternative to, and will override =TITLE, =SUBTITLE, =NAME, =AUTHOR or =VERSION directives.

Note: All of these are options are provided for compatibility, however only =TITLE and =AUTHOR are directly supported in PDF metadata.


Disables Table of Contents generation.


Disable writing of a Index section to the table of contents.


Provides a class or object to intercept and sanitise or rebase links. The class/object should provide a method resolve-link that accepts the target component of C<L<>> formatting codes and returns the actual link to be embedded in the PDF. The link is omitted, if the method returns an undefined value.


Specify replacements for R<> placeholders in the POD. Replacement values should be simple strings (Str), Pod blocks (type Pod::Block), or a List. For example:

use Pod::To::PDF;
my $title = 'Sample Title';
my Str() $date = now.Date;
my $author = 'David Warring';
my $description = "sample Pod with replaced content";
my %replace = :$date, :$title, :$author, :$description;
my $renderer = pod2pdf($=pod, :%replace, :save-as<replace-example.pdf>);

=begin pod
=TITLE R<title>
=AUTHOR R<author>
=DATE R<date>
=head2 Description
=para R<description>;
=end pod


This module's dependencies include HarfBuzz, Font::FreeType, FontConfig and Cairo, which further depend on native harfbuzz, freetype6, fontconfig and cairo libraries.

Please check these module's installation instructions.


Note that installation of the PDF::Tags::Reader module enables structural testing.

For example, to test this module from source.

$ git clone https://github.com/pod-to-pdf/Pod-To-PDF-raku
$ cd Pod-To-PDF-raku
$ zef install PDF::Tags::Reader # enable structural tests
$ zef APP::Prove6
$ zef --deps-only install .
$ prove6 -I .