/ 
Dist-Zilla-Plugin-InsertDistImage-0.006
River stage one • 1 direct dependent • 1 total dependent
/ Dist::Zilla::Plugin::InsertDistImage

NAME

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

VERSION

This document describes version 0.006 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-InsertDistImage

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.