Markdent is an event-driven parser toolkit for Markdown. That's a mouthful, so
let's go through that piece by piece, starting at the end.

Markdown is a wiki-esque plain text markup format that is easy to
read and easy to write. It draws inspiration from how people have
communicated in plain text email for a long time. For example, some text
like "*really*" is parsed as emphasis around the word
"really".

Existing Markdown tools in Perl (and in most other languages) are
only able to convert Markdown directly to HTML. They are not really parsers,
they're combined parser/converters. This is problematic if you want to do
something with the document besides turn it into HTML. Maybe you'd like to
parse it and cache an intermediate representation. Maybe you want to turn
into markup-free text. Maybe you want to pull out just the links.

With Markdent, you can do any and all of those things (and you can
turn Markdown into HTML too).

An event-driven parser like Markdown generates a sequence of
events as the result of parsing a document. If you're familiar with the
SAX API, that is another event-driven parser API.

With Markdent, these events can be things like
"StartEmphasis", "StartLink", "EndCode",
"Text", etc.

The parser feeds these events into a handler, and the handler can
decide what to do with them. By decoupling parsing from other tasks, it
gives you great power in dealing with the parse results.

When I call Markdent a parser toolkit, that means it is
designed to be part of a larger ecosystem. You can write your handlers, and
you can even write your own parser dialects as roles.

A handler object receives events with the parser and does something with them.
All handlers implement the Markdent::Role::Handler role, which simply requires
a single method,
"$handler->handle_event($event)".

If you're writing your own handler, you may find it convenient to
consume the Markdent::Role::EventsAsMethods role. This provides a
"handle_event()" implementation that calls
a different method for each type of event.

This is used by the Markdent::Handler::HTMLStream::Document and
Markdent::Handler::HTMLStream::Fragment handlers, for example. Since it
generates a different tag for each event, it makes sense to have one method
per event which knows what tag to generate.

On the other hand, the CaptureEvents handler doesn't care what
type of event it receives, it just stores it for later use. It only needs to
implement a "handle_event()" method to do
its job.

Take a look at the Markdent::Handler::HTMLStream::Document. This turns the event
stream into a stream of HTML output. You can send the output to any
filehandle. Open a filehandle to a scalar to capture the output in memory.

You can use Markdent::Handler::HTMLStream::Fragment if you don't
want to generate a complete HTML document.

The core of the Markdent parser system is the Markdent::Parser module. This
module doesn't actually do any parsing itself. Instead, it hooks together a
block parser and a span parser, and lets the block parser start the real
parsing process.

Markdent divides parsing into blocks and spans. The block parser
looks for block-level constructs like paragraphs, lists, blockquotes, etc.
For most of these constructs, it passes the contents of the block on to the
span parser. The span parser looks for things like strong and emphasis
markup, links, HTML entities, and so on.

Separating these two makes creating a Markdown dialect a bit
easier, as you may find yourself just needing to alter the behavior of just
the block or the span parser.

For example, the Theory dialect shipped with this distribution is
mostly implemented as a role applied to the Standard dialect's block
parser.

See the Theory dialect for an example of how to modify the core
Markdown dialect.