Knockoff

Knockoff is a Markdown parser that doesn't just convert text to HTML. It converts the Markdown text to an object model, with an additional writer to output Scala's XHTML format.

The approach allows for easy integration into Scala projects. You could whip up an SBT-plugin, or create a simple literate programming tool.

Examples

Convert Markdown to HTML

The default entry point is the DefaultDiscounter object. We'll import that and everything else in the main namespace.

import com.tristanhunt.knockoff.DefaultDiscounter._
import com.tristanhunt.knockoff._

toXHTML( knockoff(markdownString) )

Mess around with Knockoff in the SBT console

Start sbt in your shell:

 $ sbt

At the SBT prompt:

[info] Set current project to knockoff (in build file:...)
> console

And import the DefaultDiscounter

import com.tristanhunt.knockoff.DefaultDiscounter._

(You can use tab completion.)

Use Scala's """ delimiter to create a markdown document as a string for messing around. It should look like this:

scala> val markdown = """# I'm the *title*
     |
     | And I'm a paragraph"""

Kind of funky, but if you run into issues, this is really, really handy for helping me figure out how to reproduce.

Grab the title of the first header

I'm going to stop adding the SBT prompt in the examples.

val blocks = knockoff( markdown )

val headers = blocks.filter(_.isInstanceOf[Header])

Keep in mind that the header can have lots of child elements. So if you just want the text of it, convert it:

 toText(headers) 

Or see it styled:

 toXHTML(headers) 

It's things like this that you might want to use to seed information in a templating system based on actual data within the markdown file. You know, like the HTML title or a table of contents.

Using from SBT

Knockoff is hosted via Sonatype repositories, which should make it easy to include:

 libraryDependencies += "com.tristanhunt" %% "knockoff" % "0.8.1" 

Knockoff can be downloaded and built automatically from Github, which is the current recommended way of pulling it into your project.

A great way to read about this feature of sbt is to read this article from the Dev Daily blog.

Building

Knockoff uses SBT as it's build system. To test and build the binary, run:

sbt test package

For more commands, please consult the SBT documentation.