Pod::To::Markdown::Fenced - Render POD code blocks as fenced (```) code blocks
At this time of writing (September 2017) there is an issue with GitHub where it doesn't identify Perl 6 correctly, and therefore doesn't highlight it. It appears to have started around the time of this pull request. Until the issue is resolved, language recognition and syntax highlighting of Perl 6 is broken.
Do you like syntax highlighting?
Do you hate maintaining POD and Markdown seperately if you want language specific fenced code blocks in your README so GitHub (GFM) does syntax highlighting.
If so, this module is for you.
This module overrides
Pod::To::Markdown's multi-sub that handles
Pod::Block::Code. In the resulting output, that code block will now be fenced rather than indented. In this case, it is no longer strict Markdown, but something closer to CommonMark.
If that's all it did this module would be pretty pointless, so in addition, you can define a
info config option, which will be set as the info string on the code block. This will allow syntax highlighting of the code block where supported (like Github).
From command line:
$ perl6 --doc=Markdown::Fenced lib/MyClass.pm
From Perl 6:
Which produces the following output
This README contains uses of literal POD and Markdown, so trying to render that correctly with a POD-to-Markdown renderer doesn't work too well. For a better example, refer to my Net::Netmask module. The README.md file in that repo is generated completely by this module from the embedded POD in the module file.
LIMITATIONS AND ISSUES
This module depends on Pod::To::Markdown which handles nested
Pod::FormattingCode by setting a lexical Boolean variable
$in-code-block. As my multi-sub cannot influence that lexical variable, you may run into issues when using
Pod::FormattingCode blocks with this module.
This could be solved a number of ways (submitting a pull for
Pod::To::Markdown to expose that variable to the outside world, or copying parts/all of
Pod::To::Markdown into this module) but for what I need it works well enough. If people really need nested
Pod::FormattingCode blocks, I'm happy to respond to an issue or accept a pull request that resolves it.
This module works by setting a (currently) non-existant config option. The POD spec does not specify any
info config option, and with luck that won't change in the future.
The Artistic License 2.0
See LICENSE file in the repository for the full license text.