Home Code Other Software

Table of Contents

Introduction

The MarkWrap library (pronounced “mark wrap” or “more crap”, depending on your preference) is a unified Scala API for various underlying lightweight markup APIs. Currently, it supports:

Installation

MarkWrap is published to the Bintray Maven repository, which is automatically linked to Bintray’s JCenter repository. (From JCenter, it’s eventually pushed to the automatically sync’d with the Maven Central Repository.

Installing for Maven

If you’re using Maven, just specify the artifact, and Maven will do the rest for you:

For example:

<dependency>
  <groupId>org.clapper</groupId>
  <artifactId>markwrap_2.10</artifactId>
  <version>1.0.2</version>
</dependency>

If you cannot resolve the artifact, then add the JCenter repository:

<repositories>
  <repository>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
    <id>central</id>
    <name>bintray</name>
    <url>http://jcenter.bintray.com</url>
  </repository>
  ...
</repositories>

For more information on using Maven and Scala, see Josh Suereth’s Scala Maven Guide.

Using with SBT

Using with SBT

0.11.x/0.12.x

If you’re using SBT 0.11.x or 0.12.x to compile your code, you can use the following line in your build.sbt file (for Quick Configuration).

repositories += "JCenter" at "http://jcenter.bintray.com/"

libraryDependencies += "org.clapper" %% "markwrap" % "1.0.2"

You only need the repositories line if the artifact cannot be resolved (e.g., has not, for some reason, been pushed to Maven Central yet).

0.13.x

With SBT 0.13.x, you can just use Doug Tangren’s bintray-sbt plugin. In your project/plugins.sbt file, add:

resolvers += Resolver.url(
  "bintray-sbt-plugin-releases",
  url("http://dl.bintray.com/content/sbt/sbt-plugin-releases"))(
    Resolver.ivyStylePatterns)

addSbtPlugin("me.lessis" % "bintray-sbt" % "0.1.2")

Then, in your build.sbt file, add:

bintrayResolverSettings

That automatically adds the appropriate Bintray repositories. Finally, add:

libraryDependencies += "org.clapper" %% "markwrap" % "1.0.2"

Building from Source

Source Code Repository

The source code for the MarkWrap library is maintained on GitHub. To clone the repository, run this command:

git clone git://github.com/bmc/markwrap.git

Build Requirements

Building the MarkWrap library requires SBT 0.13.x. Install SBT, as described at the SBT web site.

Building MarkWrap

Assuming you have an sbt shell script (or .BAT file, for Windows), run:

sbt compile test package

The resulting jar file will be in the top-level target directory.

Using MarkWrap

MarkWrap provides a simple, unified API for various lightweight markup languages. There are two steps to use the API:

Getting the Desired Parser

To obtain a parser, use the org.clapper.markwrap.MarkWrap object’s parserFor() method, passing it either:

Parsing Markdown

To get a Markdown parser, call MarkWrap.parserFor() with:

Markdown is parsed with Pegdown, instantiated with all of Pegdown’s extension options except HARDWRAPS. This means that hard line wraps in your Markdown source are not passed through as <br/> elements in the HTML. To force a <br/> (a hard line wrap), use two or more spaces at the end of a Markdown line, which is how hard line wraps are handled in standard Markdown.

Parsing Textile

To get a Textile parser, call MarkWrap.parserFor() with:

Textile is parsed with the Eclipse Mylyn wikitext parser API.

Parsing raw HTML

To get a passthrough parser for HTML or XHTML, call MarkWrap.parserFor() with:

A passthrough HTML parser simply passing the HTML straight through, unmodified.

Handling plain text

To get a plaintext-to-HTML parser, call MarkWrap.parserFor() with:

The resulting plain text is simply wrapped in <pre> and </pre> tags.

Examples

Getting a Markdown parser

import org.clapper.markwrap._

// Using the constant
val parser1 = MarkWrap.parserFor(MarkupType.Markdown)

// Using the MIME type
val parser2 = MarkWrap.parserFor("text/markdown")

// Using a File object
val parser3 = MarkWrap.parserFor(new java.io.File("foo.md"))

Getting a Textile parser

import org.clapper.markwrap._

// Using the constant
val parser1 = MarkWrap.parserFor(MarkupType.Textile)

// Using the MIME type
val parser2 = MarkWrap.parserFor("text/textile")

// Using a File object
val parser3 = MarkWrap.parserFor(new java.io.File("foo.textile"))

Getting a pass-through HTML “parser”

import org.clapper.markwrap._

// Using the constant
val parser1 = MarkWrap.parserFor(MarkupType.XHTML)

// Using the MIME type
val parser2 = MarkWrap.parserFor("text/xhtml")

// Using a File object
val parser3 = MarkWrap.parserFor(new java.io.File("foo.html"))

Getting a plain text “parser”

import org.clapper.markwrap._

// Using the constant
val parser1 = MarkWrap.parserFor(MarkupType.PlainText)

// Using the MIME type
val parser2 = MarkWrap.parserFor("text/plain")

// Using a File object
val parser3 = MarkWrap.parserFor(new java.io.File("foo.txt"))

Parsing the Markup

Once you have the correct parser, you can parse the markup using one of the parsing methods.

Parsing to an HTML fragment

The parseToHTML() methods produce HTML fragments, not complete HTML documents. (There’s another parseToHTMLDocument() method that produces a complete document; see below for details.)

Parsing from a Scala Source

Example 1:

import org.clapper.markwrap._
import scala.io.Source
import java.io.File

val file = new File("/path/to/markup.md")
val parser = MarkWrap.parserFor(file)
val html = parser.parseToHTML(Source.fromFile(file))

Example 2:

import org.clapper.markwrap._
import scala.io.Source

val markup = """This is some *Markdown* text"""
val parser = MarkWrap.parserFor(MarkupType.Markdown)
val html = parser.parseToHTML(Source.fromString(markup))

Parsing from a file or a string

If you’re parsing from a file or a string, there are some shortcut methods:

From a java.io.File:

import org.clapper.markwrap._
import java.io.File

val file = new File("/path/to/markup.md")
val parser = MarkWrap.parserFor(file)
val html = parser.parseToHTML(file)

From a string:

import org.clapper.markwrap._

val parser = MarkWrap.parserFor(MarkupType.Markdown)
val html = parser.parseToHTML("""This is some *Markdown* text""")

Producing a complete HTML document

The parseToHTMLDocument() method produces a complete HTML document, with <html>, <head>, and <body> sections, as well as an optional cascading style sheet. The method’s signature looks like this:

def parseToHTMLDocument(markupSource: Source,
                        title: String,
                        cssSource: Option[Source] = None,
                        encoding: String  = "UTF-8"): String =

This method is just a simple convenience method; there are features it does not support (for instance, <link> tags, for external style sheets or Javascript files). You’re certainly free to use your own replacement for it.

API Documentation

The Scaladoc-generated the API documentation is available locally. In addition, you can generate your own version with:

sbt doc

Change log

The change log for all releases is here.

Author

Brian M. Clapper, bmc@clapper.org

Copyright and License

MarkWrap is copyright © 2009-2011 Brian M. Clapper and is released under a BSD License.

Patches

I gladly accept patches from their original authors. Feel free to email patches to me or to fork the GitHub repository and send me a pull request. Along with any patch you send: