NAME

       Markdent::Manual - Using and Extending Markdent

DESCRIPTION

       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.

HANDLERS

       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.

WHAT CAN YOU DO WITH MARKDENT?

       Markdent has a lot of parts, but you don't need to learn about all of them.

       Here are some pointers for common tasks ...

   Converting Markdown to HTML
       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.

   Cache Parse Results
       Use the Markdent::Handler::CaptureEvents handler to capture events for caching. You can
       then store the generated Markdent::CapturedEvents object using Storable.

   Do Both
       Use the Markdent::Handler::Multiplexer handler to do more than one thing at a time with
       the event stream.

   Write Your Own Handler
       Writing a handler is pretty easy. Take a look at any of the existing handler classes for
       ideas.

PARSER

       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.

WHAT DOES THE NAME MEAN?

       It's a combination of "Markdown" and "event".