Rand Stats



Build Status


Text::Markdown::Discount - markdown to HTML using the Discount C library




use Text::Markdown::Discount;
my $raw-md = '# Hello `World`!'

# render HTML into string...
say markdown($raw-md       ); # from a string
say markdown('README.md'.IO); # from a file, note the `.IO`

# ...or directly into files
markdown($raw-md,        'sample.html');
markdown('README.md'.IO, 'README.html');

You can also use the various #Flags in Discount:

say markdown($raw-md, :autolink, :!image ); # MKD_AUTOLINK | MKD_NOIMAGE
say markdown($raw-md, :AUTOLINK, :NOIMAGE); # same thing

The API from Text::Markdown is also supported:

my $md = Text::Markdown::Discount.new($raw-md);
say $md.render;

$md = parse-markdown($raw-md);
say $md.to-html;
say $md.to_html; # same thing



This library provides bindings to the Discount library via NativeCall. You need to have it installed as the libmarkdown shared library.

On Ubuntu 15.04, it's available via apt-get as the libmarkdown2-dev package, the same goes for several Debians. If it's not available as a binary for your system, you can compile it from source.

Simple API


sub markdown(    Cool:D $str,  Cool $to-file?, *%flags --> Cool) is export
sub markdown(IO::Path:D $file, Cool $to-file?, *%flags --> Cool) is export

This function is probably enough for most cases. It will either take the markdown from the given $str or $file and convert it to HTML. If $to-file is given, the result will be written to the file at that path and returns True. Otherwise returns a Str with the HTML in it.

Will throw an exception if there's a problem reading or writing files, or if the markdown can't be converted for some reason.

See #Flags about the *%flags parameter.

Object API


method from-str(Cool $str, *%flags --> Text::Markdown::Discount:D)

Parses the given $str as markdown and returns an object you can call HTML conversion methods on.

You can call this method on both a class and an object instance.

See #Flags about the *%flags parameter.


method from-file(Cool $file, *%flags --> Text::Markdown::Discount:D)

As #from-str, except will read the markdown from the given $file.

Will fail with an #X::Text::Markdown::Discount::File if it can't fopen the given $file and warn if it can't fclose it.


method to-str(Text::Markdown::Discount:D: --> Str)

Converts the markdown in the caller into HTML and returns the result.

Will fail with a #X::Text::Markdown::Discount::File if Discount can't compile the markdown for some reason.


method to-file(Text::Markdown::Discount:D: Str $file --> Bool)

Converts the markdown in the caller into HTML and writes the result to the given $file. Returns True or an appropriate Failure.


multi method dump-flags(Int:D $fd = 1)
multi method dump-flags(Str:D $file)

Dumps all flag options applied to the caller. Either to the given $file path, or to the file descriptor $fd. Defaults to dumping to file descriptor 1 (stderr).

This function may be useful in figuring out if the Discount library you're linked to actually has the flags you need.


method title(Text::Markdown::Discount:D: --> Str)

Returns the title parsed from the document header.


method author(Text::Markdown::Discount:D: --> Str)

Returns the author parsed from the document header.


method date(Text::Markdown::Discount:D: --> Str)

Returns the date parsed from the document header.

Text::Markdown Compatibility

These functions exist so that you can use Text::Markdown::Discount as a drop-in replacement for Text::Markdown. They just dispatch to existing functions:



multi method new($text, *%flags)
sub parse-markdown($text *%flags) is export

Dispatch to #from-str.




method render()
method to-html()
method to_html()

Dispatch to #to-str.



class X::Text::Markdown::Discount is Exception

The base exception class for this module. All other exception types inherit from this. Not actually thrown directly.


class X::Text::Markdown::Discount::File is X::Text::Markdown:Discount

Thrown when an fopen, fdopen or fclose fails. The latter will only be a warning.


class X::Text::Markdown::Discount::Flag is X::Text::Markdown:Discount

Thrown when you try to use a non-existent flag.


class X::Text::Markdown::Discount::Compile is X::Text::Markdown:Discount

Thrown when Discount can't compile markdown. I can't tell when this would happen or where to get the error message from though.


Discount provides a variety of flags that change how the conversion behavior. You can pass flags to all routines that take a *%flags parameter.

The following list of flags is taken from Discount's documentation. Depending on your version of the library, they might not all be available, see #dump-flags.

All of these flags map to the respective MKD_ constants. The keys are case-insensitive. Constants that originally start with NO can be used without it and negated. For example, :!links is the same as :nolinks.

:!links, :nolinks

Don't do link processing, block <a> tags.

:!image, :noimage

Don't do image processing, block <img> .

:!pants, :nopants

Don't run smartypants()

:!html, :nohtml

Don't allow raw html through AT ALL.




Process text inside an html tag; no <em> , no <bold> , no html or [] expansion.

:!ext, :noext

Don't allow pseudo-protocols.


Generate code for xml ![CDATA[...]].

:!superscript, :nosuperscript

No A^B.

:!relaxed, :norelaxed

Emphasis happens everywhere.

:!tables, :notables

Don't process PHP Markdown Extra tables.

:!strikethrough, :nostrikethrough

Forbid ~~strikethrough~~.


Do table-of-contents processing.


Compatability with MarkdownTest_1.0.


Make http://foo.com a link even without <> s.


Paranoid check for link protocol.

:!header, :noheader

Don't process document headers.


Expand tabs to 4 spaces.

:!divquote, :nodivquote

Forbid >%class% blocks.

:!alphalist, :noalphalist

Forbid alphabetic lists.

:!dlist, :nodlist

Forbid definition lists.


Enable PHP Markdown Extra-style footnotes.


There's probably some bugs in the NativeCall handling. I'm not sure if the types are specified correctly and if the destructor for the native pointers gets called when it needs to.

There seems to be a bug in Discount's mkd_generatehtml function, where it adds excessive nuls to the output if it has previously been compiled to a string. Due to that, the #to-file currently just spurts the string output into the file.

Please report bugs on GitHub.




Text::Markdown, Discount, Discount GitHub repository, Text::Markdown::Discount for Perl 5.


This software is copyright 2015 - 2017 by Carsten Hartenfels, with some parts copyright 2017 by Ilmari Vacklin.

This program is distributed under the terms of the Artistic License 2.0.

For further information, please see LICENSE or visit http://www.perlfoundation.org/attachment/legal/artistic-2_0.txt.