NAME

Text::Markdown::PerlExtensions - markdown converter that supports perl-specific extensions

SYNOPSIS

In your markdown:

            

              
              
You might P<use> M<PerlX::Define> in D<Moops> by A<TOBYINK>.
            
          

And to convert that:

            

              
              
use Text::Markdown::PerlExtensions qw(markdown);
$html = markdown($markdown);
            
          

DESCRIPTION

Text::Markdown::PerlExtensions provides a function for converting markdown to HTML. It is a subclass of Text::Markdown that provides three additional features:

• Four pod-style formatting codes, used for distribution names, module names, PAUSE author IDs, and Perl's built-in functions. These generate links to the relevant pages on MetaCPAN or perldoc.perl.org.

• A mechanism for adding further pod-style formatting codes.

• References to RT issues in the format RT#1234 will be hyperlinked to the issue on RT.

I wrote this module to use with my blogging engine. I found that I was constantly writing links to MetaCPAN, and wanted a terser notation.

The following sections describe each of the extensions, one by one.

Module

To refer to a module on CPAN, you use the M formatting code. If you write:

            

              
              
M<Module::Path>
            
          

This generates:

            

              
              
<a href="https://metacpan.org/pod/Module::Path" class="module">Module::Path</a>
            
          

The link is given a class, so you can style module names.

Distribution

To refer to a distribution, use the D formatting code. If you write

            

              
              
D<Dancer>
            
          

this generates:

            

              
              
<a href="https://metacpan.org/release/Dancer" class="distribution">Dancer</a>
            
          

CPAN Author

Similarly, to refer to a CPAN author, use the A formatting code. If you write:

            

              
              
A<NEILB>
            
          

This generates:

            

              
              
<a href="https://metacpan.org/author/NEILB" class="cpanAuthor">NEILB</a>
            
          

Perl built-in function

To link to documentation for one of Perl's built-in functions, use the P formatting code:

            

              
              
P<require>
            
          

This example would produce:

            

              
              
<a href="http://perldoc.perl.org/functions/require.html" class="function">require</a>
            
          

I really wanted to use the F formatting code for this, but that's already taken in the pod spec, used for highlighting file names.

Note: this doesn't check whether the function name given is actually a Perl built-in.

Markdown

All other syntax is as supported by Text::Markdown. You shouldn't find any clashes between the Pod-like extensions; I haven't found any so far, but please let me know if you experience any problems.

Adding formatting codes

You can add your own pod-style formatting codes. For each code you define a function that takes one text argument and returns the transformed version of that text.

The following shows how you could define I and B formatting codes, for italic and bold respectively:

            

              
              
use Text::Markdown::PerlExtensions qw(markdown add_formatting_code);
  
sub format_italic
{
  my $text = shift;
   
  return "<I>$text</I>";
}
sub format_bold
{
  my $text = shift;
   
  return "<B>$text</B>";
}
  
add_formatting_code('I' => \&format_bold);
add_formatting_code('B' => \&format_bold);
my $md   = 'Highlight with B<bold> and I<italic>.';
my $text = markdown($md);
            
          

SEE ALSO

Text::Markdown - the base class for this module.

Markdown - the original spec for markdown syntax.

REPOSITORY

https://github.com/neilb/Text-Markdown-PerlExtensions

AUTHOR

Neil Bowers <neilb@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Neil Bowers <neilb@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Text::Markdown::PerlExtensions

perl -MCPAN -e shell
install Text::Markdown::PerlExtensions