NAME

Email::MIME::Kit::Assembler::Markdown - build multipart/alternative messages from Markdown alone

VERSION

version 0.100009

SYNOPSIS

In your mkit's (JSON, here) manifest:

  {
    "renderer" : "TT",
    "assembler": [
      "Markdown",
      { "html_wrapper": "wrapper.html" }
    ],
    "path"  : "body.mkdn",
    "header": [
      { "Subject": "DynaWoop is now hiring!" },
      { "From"   : "[% from_addr  %]" }
      { "To"     : "[% user.email %]" }
    ]
  }

This kit will build a multipart/alternative message with a plaintext part (containing the rendered contents of body.mkdn ) and an HTML part (containing body.mkdn rendered into HTML using Markdown).

At present, attachments are not supported. Actually, quite a few things found in the standard assembler are not yet supported. The standard assembler desperately needs to be refactored to make its features easier to incorporate into other assemblers.

The html_wrapper parameter for the Markdown assembler is the path to a kit entry. If given, that kit entry will be used for the HTML part, and the Markdown-produced HTML will be injected into it, replacing a comment containing the marker given in the Markdown assembler's configuration. The default marker is CONTENT, so the wrapper.html used above might read as follows:

  <h1>DynaWoop Dynamic Woopages</h1>
  <!-- CONTENT -->
  <p>Click to unsubscribe: <a href="[% unsub_url %]">here</a></p>

The text_wrapper setting works exactly the same way, down to looking for an HTML-like comment containing the marker. It wraps the Markdown content after it has been rendered by the kit's Renderer, if any.

If given (and true), the munge_signature option will perform some basic munging of a sigdash-prefixed signature in the source text, hardening line breaks. The specific munging performed is not guaranteed to remain exactly stable.

If given (and true), the render_wrapper option will cause the kit entry to be passed through the renderer named in the kit. That is to say, the kit entry is a template. In this case, the marker comment is ignored. Instead, the wrapped content (Markdown-produced HTML or text) is available in a template parameter called wrapped_content, and should be included that way.

If given (and true), the encode_entities option will cause HTML in the source text to be entity encoded in the HTML part (and passed through unmodified in the plain text part)

The comment <!-- SKIP-LINE --> may be included on any line of the source document. Lines containing that substring will not be included in the final plaintext part, but will be included in the HTML part. (The comment itself will be removed.) This allows adding extra HTML to the Markdown without it remaining, annoyingly, in the text part. To change the exact text looked for from SKIP-LINE, you can set the skip_marker attribute of the assembler.

PERL VERSION

This module should work on any version of perl still receiving updates from the Perl 5 Porters. This means it should work on any version of perl released in the last two to three years. (That is, if the most recently released version is v5.40, then this module should work on both v5.40 and v5.38.)

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

AUTHOR

Ricardo Signes <cpan@semiotic.systems>

CONTRIBUTORS

• Chris Nehren <cnehren@gmail.com>

• Michael McClimon <michael@mcclimon.org>

• Ricardo Signes <rjbs@semiotic.systems>

• Robert Norris <rob@eatenbyagrue.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by Ricardo Signes.

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