Parser for PerlTricks pseudopod
Perl6 HTML Perl
Latest commit b9318e7 Feb 23, 2017 @dnmfarrell committed on GitHub Merge pull request #2 from zoffixznet/patch-1
Add mandatory "perl" META field



Pod::PerlTricks - Perl 6 parser for PerlTricks pseudopod with to-HTML and to-JSON serializers


use Pod::PerlTricks::Grammar;
use Pod::PerlTricks::ToHTML;

my $actions =;
my $match = Pod::PerlTricks::Grammar.parsefile('example.pod', :$actions);

my $html  = $match.made;
my $html_head = $actions.head;
my $html_body = $actions.body;


Pod::PerlTricks extends ordinary pod with new syntax for blogging / publishing. Pod::PerlTricks::Grammar supports all of regular pod, plus new directives. It comes with action classes for converting PerlTricks pod to HTML (Pod::PerlTricks::ToHTML) and to JSON (Pod::PerlTricks::ToJSON) with the document body serialized as HTML and the meta attributes in key value pairs (mostly for use with AngularJS).

If you're just interested in parsing normal pod syntax, take a look at Pod::Perl5. It can translate pod into both HTML and Markdown.

new command blocks

include filepath

The =include directive takes a filepath to one or more pod files. When an action class parses =include it will open and parse each referenced pod file. The files can contain inline pod too.

This is useful if you have boilerplate text you want t include in every pod file, (like author details) but don't want to type out every time.

=include file://path/to/author.pod

Or maybe you want to make a manifest of pod files:



This file will be processed into a single match object containing all of the pod content from the files. The links can be separated by vertical or horizontal whitespace.

=author-name, author-bio, author-image

The =author-* command directives are to represent author details.

=author-name Jane Smith

=author-bio Jane Smith is a professional programmer with 12 years of experience, specializing in acme code ...

=author-image path/to/j_smith.jpg


=tags accepts a horizontal whitespace-separated list of tags to be used as metadata

=tags programming perl io

image, cover-image

Both =image and =cover-image are intended to include images, the only difference between them is =cover-image is supposed to denote the primary image for the article, whereas =image represents an image inline in the article.

=image Image caption

=cover-image "path/to/image.png"


=table indicates the start of a pipe-separated table. The directive must be followed by a blank line, and then the table itself. The first row is the header row. The table is terminted by a blank line.


| Team           | Score |
| The Farmers    | 54    |
| Timeout United | 21    |

The whitespace around the pipes is optional and will not be associated with the text in the cell.

begin data, terminal & code

Pod::PerlTricks supports 3 new types of begin/end blocks:

  • data - this is meant to represent data

  • terminal - for terminal output, commands etc

  • code - for programming code

So you can do:

=begin code

  use Some::Lib;

  my $foo =;

=end code

And get

<pre><code>use Some::Lib;

my $foo =;<code></pre>

terminal and data add a matching class attribute to the pre tag, e.g.

<pre class="terminal">...

chapter, title, subtitle, section

These are document metadata directives, e.g.:

=title 5 Ways to Optimize Your Code

For Pod::PerlTricks::ToHTML This will be rendered in a div node with the class attribute title, and added to the head node. For Pod::PerlTricks::ToJSON article metadata directives are included as a key/pair value in the head key, but not rendered in the body. There is nothing special about these directives except =chapter increments the chapter count, and flushes the footnotes cache.


=publish-date takes an ISO8601 datetime, with an optional timezone component. This can be used to determine when an article "goes live" on a blog site, and is also just useful metadata.

=publish-date 2015-09-30T18:00:00


Specify the language that the article is written in. In Pod::PerlTricks::ToHTML this is added to the root HTML node.

New formatting codes

D<data>, T<terminal>

D stands for data, and T for terminal to complement the C<> formatting code. These should be styled accordingly (monospaced font, possibly colored background).


G stands for GitHub. It builds a hyperlink to a Github repo or user page:



<a href="">Pod-PerlTricks</a>




<a href="">dnmfarrell</a>

#<hashtag>, @<handle>

# is for hashtag. This builds a hashtag search to Twitter. @ is for Twitter handle, and links to a particular user's Twitter feed.


N is for footnote or notation. The text inside the angle brackets should be formatted as a footnote in the article, with a link to the footnote created inplace of the formatting code. Footnotes are per chapter - if there are none / one =chapter directives, all footnotes will appear at the bottom of the document.

Some important fact Smith & Smith 2015 Oxford Press


<p>Some important fact<sup><a href="#1">1</a></sup></p>

And later ...

<div class="footnotes">
    <li id="1">[1] Smith & Smith 2015 Oxford Press</li>

W<wikipedia entry>

W is for Wikipedia. The text should be replaced with a link to Wikipedia search for the content.



<a href="">Perl</a>


David Farrell © 2015




Hey! The above document had some coding errors, which are explained below:

Around line 152:

Deleting unknown formatting code G<>

Around line 160:

Deleting unknown formatting code G<>

Around line 174:

Deleting unknown formatting code N<>

Around line 192:

Deleting unknown formatting code W<>