=begin rakudoc :!toc
=TITLE An addon to Air to allow for RakuDoc segments
=for AUTHOR :hidden
Richard Hainsworth, aka finanalyst
=for VERSION :hidden
v0.1.0
=SYNOPSIS In an Air website definition, include C<use Air::RakuDoc>.
It will render all of the blocks and markup codes defined for RakuDoc v2, with L<some caveats|#Limitations>.

=head Example

The following is in C<bin/rakudoc-example.raku>

=begin code
#!/usr/bin/env raku
#!/usr/bin/env raku

use Air::Functional :BASE;
use Air::Base;
use Air::Plugin::RakuDoc;

my &index = &page.assuming(
    title       => 'hÅrc',
    description => 'HTMX, Air, Red, Cro',
    footer      => footer p ['Aloft on ', b 'Åir'],
    );

my $base-examples =
    site :register[Air::Plugin::RakuDoc.new], :!scss,
        index
        main
            div [
                h3 'RakuDoc';
                rakudoc q:to/RAKUDOC/;
                    =begin rakudoc :!toc
                    =config item :bullet«\c[palm tree]»
                    =config item2 :bullet«\c[Earth Globe Europe-Africa]»
                    =head This is some RakuDoc source

                    Lets include a snazzy list:
                    =item First item with a palm tree bullet
                    =item Second item with palm tree
                    =item2 Now a second layer with a world
                    =item Back to the palm tree

                    And now some ordinary text.
                    =end rakudoc
                    RAKUDOC
                    hr;

            ];

$base-examples.serve;
=end code

=head Limitations

Citation blocks and C<Q< >> markup will not render properly without the external programs:
=item pandoc
=item citeproc

And for more estoteric citation formats only, some of the utilities in the BibUtils repository.

Currently, not all the Plugins available in the Rakuast::RakuDoc::Render distribution can be used,
eg, GraphViz and Fontawesome.

=end rakudoc