NAME
    Dist::Zilla::Plugin::InsertDistImage - Insert images contained in
    distribution into POD as HTML snippets

VERSION
    This document describes version 0.007 of
    Dist::Zilla::Plugin::InsertDistImage (from Perl distribution
    Dist-Zilla-Plugin-InsertDistImage), released on 2023-11-09.

SYNOPSIS
    In share/images, put some images e.g. img1.jpg and img2.png.

    In dist.ini:

     [InsertDistImage]
     ;hosting=metacpan
     ;include_files=...
     ;exclude_files=...
     ;include_file_pattern=...
     ;exclude_file_pattern=...

    In lib/Foo.pm or bin/bar:

     ...

     # IMAGE: share/images/img1.jpg
     # IMAGE: share/images/img2.png

     ...

    After build, lib/Foo.pm will contain:

     ...

     =begin html

     <img src="https://st.aticpan.org/source/CPANID/Your-Dist-Name-0.123/share/images/img1.jpg" />

     =end html

     =begin html

     <img src="https://st.aticpan.org/source/CPANID/Your-Dist-Name-0.123/share/images/img2.png" />

     =end html

DESCRIPTION
    This plugin finds "# IMAGE" directive in your POD/code and replace it
    with a POD containing HTML snippet to load the images, using the
    selected hosting provider's URL scheme.

    Rationale: sometimes documentation needs some images. Sometimes the
    proper (not to mention convenient) place to put the images is within the
    distribution itself. And you want to be able to view the images when you
    browse the POD in HTML form.

    The "#IMAGE" directive must occur at the beginning of line and must be
    followed by path to the image (relative to the distribution's root). It
    is recommended to put the images in share/images.

    You can put alternate locations by using "|", e.g.:

     # IMAGE: location1.jpg|location2.jpg

    This can be useful if you are using hosting=data (where this plugin
    needs to read the content of the file) and "location1.jpg" is produced
    by another plugin and might not be ready or added to the build at the
    time this plugin runs (but "location2.jpg" is the temporary version of
    the file that already exists).

    Shared image files deployed inside a tarball (such as one created using
    Dist::Zilla::Plugin::ShareDir::Tarball) are not yet supported.

CONFIGURATION
  hosting => str (default: metacpan)
    Choose hosting provider. Available choices:

    *   metacpan

        This is the default because all distributions uploaded to PAUSE/CPAN
        will normally show up on metacpan.org. Note that some people advise
        not to abuse metacpan.org to host images because metacpan.org is not
        an image hosting service. However, at the time of this writing, I
        couldn't find any mention of this in the metacpan.org FAQ or About
        pages.

    *   github

        This can only be used if the distribution specifies its repository
        in its metadata, and the repository URL's host is github.com.

    *   gitlab

        This can only be used if the distribution specifies its repository
        in its metadata, and the repository URL's host is gitlab.com.

    *   bitbucket

        This can only be used if the distribution specifies its repository
        in its metadata, and the repository URL's host is bitbucket.org.

    *   data

        Instead of using a remote http/https hosting provider, this will
        instead use "data:" URIs where the image data is directly embedded
        in the URL.

  include_files => str+
  exclude_files => str+
  include_file_pattern => re
  exclude_file_pattern => re
HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Dist-Zilla-Plugin-InsertDistImage>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Dist-Zilla-Plugin-InsertDistImage>.

SEE ALSO
AUTHOR
    perlancar <perlancar@cpan.org>

CONTRIBUTING
    To contribute, you can send patches by email/via RT, or send pull
    requests on GitHub.

    Most of the time, you don't need to build the distribution yourself. You
    can simply modify the code, then test via:

     % prove -l

    If you want to build the distribution (e.g. to try to install it locally
    on your system), you can install Dist::Zilla,
    Dist::Zilla::PluginBundle::Author::PERLANCAR,
    Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
    other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
    required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE
    This software is copyright (c) 2023, 2017, 2016 by perlancar
    <perlancar@cpan.org>.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-Ins
    ertDistImage>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.