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".