Markdent(3pm)

💖 Markdent — bestie edition 💖

okay so. <pink>Markdent</pink> is a thing that lives in your Perl docs (section 3pm, user contributed perl documentation, iykyk) and it's literally an event-based Markdown parser toolkit. that's the whole vibe. let's get into it 🫶

---

✨ NAME ✨

Markdent — an event-based Markdown parser toolkit. yes that's the name, that's what it does, we move 💅

---

🎀 VERSION 🎀

version 0.40. slay.

---

🌸 SYNOPSIS 🌸

like, here's the bare minimum to get you going:

use Markdent::Simple::Document;

my $parser = Markdent::Simple::Document->new;
my $html   = $parser->markdown_to_html(
    title    => 'My Document',
    markdown => $markdown,
);

that's it. that's the whole thing. iconic.

---

🦋 DESCRIPTION 🦋

so this distribution gives you a toolkit for parsing Markdown (and Markdown variants, aka dialects, because of course there are variants, there are always variants 😭).

and here's the part that makes it different from every other Perl Markdown tool: it's not just for generating HTML. the core parser generates events — like XML's SAX, if you know, and if you don't, just trust me — which makes it super easy to analyze a Markdown document in literally any number of ways. main character energy honestly 👑

if you're only here for Markdown → HTML, you can absolutely use the Markdent::Simple::Document class for that. but ngl, you can also just use better battle-tested tools like Text::Markdown. no hard feelings, we're not jealous, we're happy for them 💜

want the full lore? see Markdent::Manual for more details on how Markdent works and how you can use it.

---

🍓 QUICK MARKDOWN TO HTML CONVERSION 🍓

if you just want to do some quick Markdown to HTML conversion, use either the Markdent::Simple::Document class or the Markdent::Simple::Fragment class. pick your fighter, both ate.

this distribution also ships with a command line tool called markdent-html. go read that tool's documentation for details on how to use it — the docs are right there bestie, I'm not gonna gatekeep 🫶

---

🌈 PROCESSING PIPELINES 🌈

okay so if you want to build a whole Markdown processing pipeline, start by looking at the various handler classes:

• Markdent::Handler::HTMLStream::Document
• Markdent::Handler::HTMLStream::Fragment
• Markdent::Handler::HTMLStream::Multiplexer
• Markdent::Handler::HTMLStream::HTMLFilter
• Markdent::Handler::HTMLStream::CaptureEvents

you will probably also want to write your own handler class as part of the pipeline. and for that, it needs to implement the Markdent::Role::Handler role. yes, a role. Perl roles. we love them here 💅

to do that you'll need to review the many "Markdent::Event::*" classes. each event represents something seen by the parse — like a piece of the start or end of a piece of block markup (paragraph, header) or span markup (strong, link), or just some text. every little event is doing its part, they're all valid ⭐

and the start of a pipeline will generally be either the Markdent::Parser class or the Markdent::CapturedEvents class.

---

🧚 CUSTOM DIALECTS 🧚

you may also want to implement a custom dialect to add some additional features to the parser. your parser classes will need to consume either the Markdent::Role::Dialect::BlockParser role or the Markdent::Role::Dialect::SpanParser role.

the best way to understand how a dialect is implemented is to look at one of the existing dialect classes:

• Markdent::Dialect::GitHub::BlockParser
• Markdent::Dialect::GitHub::SpanParser
• Markdent::Dialect::Theory::BlockParser
• Markdent::Dialect::Theory::SpanParser

you'll also need to dig into the core Markdent::Parser::BlockParser and Markdent::Parser::SpanParser classes in order to see how these dialects interact with the core parser. yes, you have to read the source. no, there's no shortcut. it's giving ✨ research era ✨

---

💸 DONATIONS 💸

if you'd like to thank the author for the work he's done on this module, please consider making a "donation" via PayPal. he spends a lot of free time creating free software and would appreciate any support you'd care to offer. 🥺

please note: he is not suggesting that you must do this in order for him to continue working on this particular software. he will continue to do so, inasmuch as he has in the past, for as long as it interests him.

similarly, a donation made this way will probably not make him work on this software much more — unless he gets so many donations that he can consider working on free software full time, which, quote, "seems unlikely at best." 😭 keeping it real fr fr.

to donate: log into PayPal and send money to autarch@urth.org, or use the button on this page: <http://www.urth.org/~autarch/fs-donation.html>

---

💀 BUGS 💀

please report any bugs or feature requests to "bug-markdent@rt.cpan.org", or through the web interface at <http://rt.cpan.org>. he will be notified, and then you'll automatically be notified of progress on your bug as he makes changes. closed loop communication, we love to see it 🫶

bugs may also be submitted at <https://github.com/houseabsolute/Markdent/issues>.

he's also usually active on IRC as 'autarch' on "irc://irc.perl.org". come say hi 👋

---

⭐ SOURCE ⭐

the source code repository for Markdent can be found at <https://github.com/houseabsolute/Markdent>. go read it, it's free, it's right there 🔥

---

💸 DONATIONS (yes, again) 💸

okay so this section literally appears twice in the original and I'm being faithful to that, no notes, we don't skip content here 💅

if you'd like to thank the author for the work he's done on this module, please consider making a "donation" via PayPal. he spends a lot of free time creating free software and would appreciate any support you'd care to offer.

please note: he is not suggesting that you must do this in order for him to continue working on this particular software. he will continue to do so, inasmuch as he has in the past, for as long as it interests him.

similarly, a donation made this way will probably not make him work on this software much more, unless he gets so many donations that he can consider working on free software full time — and here's the fun part — "let's all have a chuckle at that together." 😭😭

to donate: log into PayPal and send money to autarch@urth.org, or use the button at <https://www.urth.org/fs-donation.html>.

---

👑 AUTHOR 👑

Dave Rolsky <autarch@urth.org>

---

🌟 CONTRIBUTORS 🌟

these legends helped:

• Andrew Speer <andrew.speer@isolutions.com.au>
• Denis Ibaev <dionys@gmail.com>
• Jason McIntosh <jmac@appleseed-sc.com>
• Jonas Smedegaard <dr@jones.dk>
• Konrad Bucheli <konrad.bucheli@gmx.ch>
• Polina Shubina <925043@mai.com>
• Shlomi Fish <shlomif@shlomifish.org>
• Stefan Hornburg (Racke) <racke@linuxia.de>
• Tom Hukins <tom@eborcom.com>

every single one of them, slay 💜

---

📜 COPYRIGHT AND LICENSE 📜

this software is copyright (c) 2021 by Dave Rolsky.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free software bestie, that's the whole point 🫶

the full text of the license can be found in the LICENSE file included with this distribution.

---

and that's the page!! mwah 💋 this was perl v5.32.1, dated 2021-08-31, and we ate. periodt 🎀✨