=begin rakudoc :type<renderer>
=TITLE Rendering RakuDoc v2 to MarkDown
=for AUTHOR :hidden
Richard Hainsworth, aka finanalyst
=for VERSION :hidden
v0.4.0
=SUBTITLE Simple and customisable module for rendering RakuDoc v2 to Markdown.

=begin SYNOPSIS
To render a RakuDoc source, eg. I<some-docs.rakudoc>, into I<some-docs.md>, either use the
terminal command
=for code :lang<text>
RAKUDO_RAKUAST=1 raku --rakudoc=Markdown some-docs.rakudoc > some-docs.md

or (see L<below for more detail|#RenderDocs utility>)
=for code :lang<text>
bin/RenderDocs some-docs

There is a section on Troubleshooting in the L<general README file|README> if this fails.
=end SYNOPSIS

=head Overview

Markdown representation of documentation is widespread, so a simple conversion (rendering) of the
RakuDoc v2 into Markdown is useful, even though Markdown is intended to be viewed as HTML.

The module can be customised by setting an Environment variable to a template file.
L<More detail on customising|Customising templates>.

The general L<README file should be read first|README>.

For this description, it is assumed that the I<RakuAST::RakuDoc::Render> distribution
is B<NOT> installed using zef, although it can be.
Consequently, all commands are assumed to be inside the repo directory root.

=head Custom block

The Markdown renderer comes with one custom block for generating Graphs.
More information can be found about the L<Graphviz plugin|plugins/Graphviz.*>

Some caveats:
=item Since a widespread use of Markdown is for I<Github> and cross-server sources are forbidden,
diagrams have to be in an asset file within the I<Github> repository.
=item The diagrams are generated using C<dot>, which must exist in the environment
=item Each diagram given in a single source whose name is (eg) R<my-document.rakudoc> is stored in the file
B<my-document-this_is_a_diagram.svg>, where the C< :caption<this is a diagram> > is in the metadata
options of the custom block. For more detail see L<the Graphviz documentation|plugins/Graphviz.*>.
=item The diagram files will be stored in the same directory as the main output file B<my-document.md>.

=head Customising templates

All output from I<Rakuast::RakuDoc::Render> modules is generated through templates.
These templates can be added to, without overriding the previous templates, (L<see Templates for detail|Templates>).

If a file exists in the local directory called I<new-temp.raku> and conforms to
the requirements described in L<Templates|Templates>, then the templates in it will be
added to the generic Markdown templates as follows:
=for code :lang<text>
MORE_MARKDOWN=new-temp.raku RAKUDO_RAKUAST=1 raku --rakudoc=Markdown some-docs.rakudoc > store.md

For instance if the contents of I<new-temp.raku> is
=code
 %(
    final => -> %prm, $tmpl { "# Customisation message\n\n" ~ $tmpl.prev }
)

Then after running the command above, B<store.md> will contain a new title at the top, followed
by the remainder of the Markdown as rendered before the new template was added.

Some notes:
=item The template C<final> is the last one that I<glues> all the documentation together into a string.
=item C<$tmpl.prev> is call to the previous version of C<final> with all the parameters passed on.
=item All the generic templates are L<tabulated with comments|default-text-templates>.

=head RenderDocs utility

A utility called B<RenderDocs> accompanies the distribution. It is assumed that documentation sources
in RakuDoc are contained in the sub-directory C<docs/> and that Markdown versions are required in the
working directory. If any RakuDoc source has a modified date later than the current version of the
Markdown output, then the Markdown file is updated.

Usage
=for code :lang<text>
bin/RenderDocs

More granularity can be obtained by specifying a single file and a I<to> destination, eg.
=for code :lang<text>
bin/RenderDocs --to=README docs/README

Here, there must be a file C<docs/README.rakudoc>, which is rendered to the current working directory as
I<README.md>.

=place semantic:AUTHOR :caption<Credits>

=place semantic:VERSION :!toc

=end rakudoc