MarkDown
MarkDown
Table of Contents
Usage with compilerUsage from a programMore detail and differences from Pod::To::HTML2
Usage with compiler
From the terminal:
raku --doc=MarkDown input.raku > README.md
This takes the POD in the input.raku
file, transforms it into MarkDown. This module uses the Mustache templating engine.
Some rendering options can be passed via the PODRENDER Environment variable. The options can be used to turn off components of the page.
PODRENDER='NoTOC NoFoot' raku --doc=MarkDown input.raku > README.md
The following regexen are applied to PODRENDER and switch off the default rendering of the respective section:
regex applied | if Match, then Turns off |
/:i 'no' '-'? 'toc' / | Table of Contents |
/:i 'no' '-'? 'meta' / | Meta information (eg AUTHOR) |
/:i 'no' '-'? 'footnotes' / | Footnotes. |
Any or all of 'NoTOC', 'NoMeta', or 'NoFoot' may be included in any order. Default is to include each section.
Usage from a program
The class can be used from a program, such as raku-pod-extraction.
More detail and differences from Pod::To::HTML2
See RenderPod PodToHTML2 for more detail. Pod::To::MarkDown
has templates to produce MarkDown and not HTML. In addition:
A boolean
github-badge
(default: False) and an associated stringbadge-path
(default:'/actions/workflows/test.yaml/badge.svg'
) are provided. These will generate a badge at the start of a Pod6 file converted to Markdown, such as README.md, that will show the github badge.The target rewrite function needs to be over-ridden.
MarkDown is not intended for internal links. So there is no glossary and META data is treated as paragraphs.
Footnotes have to be rendered at the end of the document, and there is no backward link from the footnote to the originating text.
Pod::To::MarkDown used the Mustache template system, not the Raku Closure Templates.
If a template file called md-templates.raku is contained in the Current Working Directory, and that file has the same format as the default templates, then it will over-ride the default templates. See RenderPod for more detail.
Rendered from MarkDown at 2022-06-13T16:49:45Z