NAME

Pod::Markdown::Githubert - convert POD to Github-flavored Markdown

SYNOPSIS

use Pod::Markdown::Githubert ();

my $parser = Pod::Markdown::Githubert->new;
$parser->output_string(\my $markdown);
$parser->parse_string_document($pod_string);

# see Pod::Markdown docs for the full API

DESCRIPTION

Pod::Markdown::Githubert is a module for converting documents in POD format (see perlpod) to Github-flavored Markdown. It is a subclass of Pod::Markdown (which see for API documentation) that adds the following Github-specific enhancements and fixes:

• Internal links (of the form L</foo>) are converted to something that hopefully matches how Github generates HTML ids for Markdown headings. In short, internal links to a section of the current page should just work when rendered on Github.

• Github-specific Markdown code can be embedded literally using a =for github-markdown paragraph or =begin github-markdown ... =end github-markdown section.

  In other words, if you want to render e.g. a badge, but only on Github, not all Markdown renderers, put it in a =for github-markdown paragraph.

• External links to module documentation normally point to https://metacpan.org/. But that doesn't work for some of the manual pages included with Perl because they are only generated when perl is built (such as perlapi), so this module redirects all perlXYZ links to https://perldoc.perl.org/, which has the full set.

• Verbatim paragraphs are translated to fenced code blocks (surrounded by ```) with normalized indentation (meaning it doesn't matter whether the paragraph is indented by 1 space, 4 spaces, or 23 spaces in the POD source; it will generated the same Markdown).

• Code blocks containing ``` are rendered correctly, as are code blocks in nested structures (such as list items) even when a numbered list item starts with a code block.

• Syntax highlighting can be enabled by tagging each code block with its language. As this module translates a POD document, it keeps a global "current language" setting, which is applied to every verbatim paragraph. Initially the "current language" is empty, which just produces ordinary ``` code blocks.

  A =for highlighter language=FOO paragraph sets the "current language" to FOO. (More specifically, you can put multiple KEY=VALUE options in a =for highlighter paragraph, but this module only looks at the language option.) If you only want to set the "current language" to FOO, you can also write =for highlighter FOO (that is, language is the default option).

  The "current language" is applied to all following verbatim paragraphs and produces ```FOO tagged code blocks:

  =for highlighter language=perl
  
      my $dog = "spot";
  
  ... other stuff ...
  
      my $car = "cdr";
  
  =for highlighter language=html
  
      <p>Hello!</p>

  produces the following Markdown code:

  ```perl
  my $dog = "spot";
  ```
  
  ... other stuff ...
  
  ```perl
  my $car = "cdr";
  ```
  
  ```html
  <p>Hello!</p>
  ```

• $ characters are escaped in plain text segments because otherwise Github will try to render any random text that happens to sit between two dollar signs as TeX-style math.

• Text in italics is rendered using *, not _. This is because Github displays _N_th verbatim as "_N_th", but *N*th as "Nth". The latter is what we want for POD like I<N>th.

SEE ALSO

Pod::Markdown, perlpod

AUTHOR

Lukas Mai, <lmai at web.de>

COPYRIGHT & LICENSE

Copyright 2023-2024 Lukas Mai.

This module is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See https://dev.perl.org/licenses/ for more information.