Randy Stauner > Pod-Markdown-3.003 > Pod::Markdown



Annotate this POD



Open  1
View/Report Bugs
Module Version: 3.003   Source  


Pod::Markdown - Convert POD to Markdown


version 3.003


  # Pod::Simple API is supported.

  # Command line usage: Parse a pod file and print to STDOUT:
  # $ perl -MPod::Markdown -e 'Pod::Markdown->new->filter(@ARGV)' path/to/POD/file > README.md

  # Work with strings:
  my $markdown;
  my $parser = Pod::Markdown->new;

  # See Pod::Simple docs for more.


This module uses Pod::Simple to convert POD to Markdown.

Literal characters in Pod that are special in Markdown (like *asterisks*) are backslash-escaped when appropriate.

By default markdown and html formatted regions are accepted. Regions of markdown will be passed through unchanged. Regions of html will be placed inside a <div> tag so that markdown characters won't be processed. Regions of :markdown or :html will be processed as POD and included. To change which regions are accepted use the Pod::Simple API:

  my $parser = Pod::Markdown->new;
  $parser->unaccept_targets(qw( markdown html ));

A note on encoding and escaping

The common Pod::Simple API returns a character string. If you want Pod::Markdown to return encoded octets, there are two attributes to assist: "match_encoding" and "output_encoding".

When an output encoding is requested any characters that are not valid for that encoding will be escaped as HTML entities.

This is not 100% safe, however.

Markdown escapes all ampersands inside of code spans, so escaping a character as an HTML entity inside of a code span will not be correct. However, with pod's S and E sequences it is possible to end up with high-bit characters inside of code spans.

So, while output_encoding => 'ascii' can work, it is not recommended. For these reasons (and more), UTF-8 is the default, fallback encoding (when one is required).

If you prefer HTML entities over literal characters you can use "html_encode_chars" which will only operate outside of code spans (where it is safe).




The constructor accepts the following named arguments:


A string of characters to encode as html entities (using "encode_entities" in HTML::Entities if available, falling back to numeric entities if not).

Possible values:

By default this is disabled and literal characters will be in the output stream. If you specify a desired "output_encoding" any characters not valid for that encoding will be HTML entity encoded.

Note that Markdown requires ampersands (&) and left angle brackets (<) to be entity-encoded if they could otherwise be interpreted as html entities. If this attribute is configured to encode those characters, they will always be encoded. If not, the module will make an effort to only encode the ones required, so there will be less html noise in the output.


Boolean: If true, use the =encoding of the input pod as the encoding for the output.

If no encoding is specified, Pod::Simple will guess the encoding if it sees a high-bit character.

If no encoding is guessed (or the specified encoding is unusable), "output_encoding" will be used if it was specified. Otherwise UTF-8 will be used.

This attribute is not recommended but is provided for consistency with other pod converters.

Defaults to false.


The encoding to use when writing to the output file handle.

If neither this nor "match_encoding" are specified, a character string will be returned in whatever Pod::Simple output method you specified.


Returns the url prefix in use for man pages.


Returns the url prefix in use (after resolving shortcuts to urls).


Returns the coderef or format name used to format a url fragment to a section in an external document.


Returns the coderef or format name used to format a url fragment to an internal section in this document.


Returns the boolean value indicating whether or not meta tags will be printed.


Used internally to create a url (using "man_url_prefix") from a string like man(1).


    # With $name and section being the two parts of L<name/section>.
    my $url = $parser->format_perldoc_url($name, $section);

Used internally to create a url from the name (of a module or script) and a possible section (heading).

The format of the url fragment (when pointing to a section in a document) varies depending on the destination url so "perldoc_fragment_format" is used (which can be customized).

If the module name portion of the link is blank then the section is treated as an internal fragment link (to a section of the generated markdown document) and "markdown_fragment_format" is used (which can be customized).


Format url fragment for an internal link by replacing non-word characters with dashes.


Format url fragment like "idify" in Pod::Simple::XHTML.


Format url fragment like "section_name_tidy" in Pod::Simple::HTML.


Format fragment for metacpan.org (uses "format_fragment_pod_simple_xhtml").


Format fragment for search.cpan.org (uses "format_fragment_pod_simple_html").




You can find documentation for this module with the perldoc command.

  perldoc Pod::Markdown


The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

Bugs / Feature Requests

Please report any bugs or feature requests by email to bug-pod-markdown at rt.cpan.org, or through the web interface at https://rt.cpan.org/Public/Bug/Report.html?Queue=Pod-Markdown. You will be automatically notified of any progress on the request by the system.

Source Code


  git clone https://github.com/rwstauner/Pod-Markdown.git




This software is copyright (c) 2009-2011 by Marcel Gruenauer.

This software is copyright (c) 2011 by Randy Stauner.

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

syntax highlighting: