Render POD code blocks as fenced code blocks
Perl 6
Switch branches/tags
Nothing to show
Latest commit 82f7d72 Sep 12, 2017 @0racle committed on GitHub Update README.md
Document current issues with GitHub re. Perl 6

README.md

NAME

Pod::To::Markdown::Fenced - Render POD code blocks as fenced (```) code blocks

IMPORTANT NOTE

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.

SYNOPSIS

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).

USAGE

From command line:

$ perl6 --doc=Markdown::Fenced lib/MyClass.pm

From Perl 6:

Use Pod::To::Markdown::Fenced;

Here is some perl

=begin code :info<perl6>
say [>] ('apples', 'oranges')».chars;
=end code

Some not perl

=begin code :info<javascript>
console.log('apples'.length > 'oranges'.length)
=end code

And a normal code block

=begin code
Stop comparing apples to oranges.
=end code

say pod2markdown($=pod);

Which produces the following output

Here is some perl

```perl6
say [>] ('apples', 'oranges')».chars;
```

And some not perl

```javascript
console.log('apples'.length > 'oranges'.length)
```

And a normal code block

```
Stop comparing apples and oranges.
```

EXAMPLE

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.

LICENCE

The Artistic License 2.0 

See LICENSE file in the repository for the full license text.