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:

Markdown, via the flexmark-java parser. (Prior to version 1.2, MarkWrap used Pegdown.)
Textile, via the FuseSource WikiText fork of then Eclipse Mylyn wikitext parser API.
An internal handler that wraps plain text in <pre> and </pre> tags.
An internal handler that simply passes HTML straight through.

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.

Versions 1.2.0 and 1.1.2 support Scala 2.12, Scala 2.11 and 2.10.
Version 1.0.2 supports Scala 2.11 and 2.10.
Version 1.0 supports Scala 2.10.
Version 0.5.5 supports Scala 2.10.0-M7, 2.9.2, 2.9.1-1, 2.9.1, 2.9.0-1, 2.9.0, 2.8.2, 2.8.1 and 2.8.0.

Installing for Maven

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

Group ID: org.clapper
Artifact ID: markwrap_SCALA_VERSION (markwrap_2.11, for example)
Version: 1.2.0
Type: jar

For example:

<dependency>
  <groupId>org.clapper</groupId>
  <artifactId>markwrap_2.10</artifactId>
  <version>1.2.0</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

Just add the following line to your build.sbt:

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

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:

Get the converter for the desired lightweight markup language.
Call the converter’s parseToHTML() method with the content.

Getting the Desired Parser

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

a MIME type
a markup language constant
a java.io.File object, whose extension is used to determine the MIME type.

Converting Markdown

To get a Markdown converter, call MarkWrap.converterFor() with:

the MarkupType.Markdown constant
the MIME type string “text/markdown”
A java.io.File object specifying a file with either a .md or .markdown extension.

Markdown is parsed with flexmark-java, using the CommonMark dialect, with some these extensions:

Tables

Supports GitHub-flavored Markdown table syntax.

Strikethrough

~~text~~

renders “text” as strikethrough:

<p><del>text</del></p>

Subscript

~text~

renders “text” as subscript:

<p><sub>text</sub></p>

Definition lists

Orange
:   The fruit of an evergreen tree of the genus Citrus.

renders as:

<dl>
<dt>Orange</dt>
<dd>The fruit of an evergreen tree of the genus Citrus.</dd>
</dl>

Converting Textile

To get a Textile converter, call MarkWrap.converterFor() with:

the MarkupType.Textile constant
the MIME type string “text/textile”
A java.io.File object specifying a file with a .textile extension.

Textile is parsed with the Eclipse Mylyn wikitext parser API.

“Converting” raw HTML

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

the MarkupType.HTML or Markup.XHTML constants
one of the MIME type strings “text/html” or “text/xhtml”
A java.io.File object specifying a file with one of these extensions: .htm, .html, .xhtm, .xhtml

A passthrough HTML converter simply passes the HTML straight through, unmodified.

Handling plain text

To get a plaintext-to-HTML converter, call MarkWrap.converterFor() with:

the MarkupType.PlainText constant
the MIME type string “text/plain”
A java.io.File object specifying a file with one of these extensions: .txt, .text, .cfg, .conf, .properties

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

Examples

Getting a converter via type

If you call converterFor() with a MarkupType value, you get the converter directly:

import org.clapper.markwrap._

val markdown = MarkWrap.converterFor(MarkupType.Markdown)
val textile = MarkWrap.converterFor(MarkupType.Markdown)
val html = MarkWrap.converterFor(MarkupType.HTML) // or MarkupType.XHTML
val plain = MarkWrap.converterFor(MarkupType.PlainText)

markdown.parseToHTML("...")

Getting a converter via MIME type

You can pass a (string) MIME type to converterFor(). The following MIME types are supported:

text/textile
text/markdown
text/html
text/xhtml
text/plain

Passing any other MIME type causes an error.

Because errors can occur, this version of converterFor() returns a scala.util.Try.

import org.clapper.markwrap._

val mimeType = "text/markdown"
MarkWrap.converterFor(mimeType) match {
  case Success(converter) =>  converter.parseToHTML("...")
  case Failure(exception) =>  // handle error
}

// Or, monadically:
MarkWrap.converterFor(mimeType).map { converter =>
  converter.parseToHTML("...")
} // you now have a Try[String]. If Success, it contains the HTML.

Getting a converter via filename

You can pass a java.io.File object to converterFor(). MarkWrap will convert the file name to a MIME type (using the file’s extension); then, it’ll use the resulting MIME type to get the converter.

The following extensions are supported:

extension	MIME type	markup
`.md`, `.markdown`	`text/markdown`	Markdown
`.textile`	`text/textile`	Textile
`.htm`, `.html`	`text/html`	HTML
`.xhtm`, `.xhtml`	`text/xhtml`	XHTML
`.txt`, `.TXT`, `.text`, `.TEXT`, `.cfg`, `.conf`, `.properties`	`text/plain`	plain text

Passing any other MIME type causes an error.

Because errors can occur, this version of converterFor() returns a scala.util.Try.

import org.clapper.markwrap._

MarkWrap.converterFor(new java.io.File(pathToFile)) match {
  case Success(converter) =>  converter.parseToHTML("...")
  case Failure(exception) =>  // handle error
}

// Or, monadically:
MarkWrap.converterFor(mimeType).map { converter =>
  converter.parseToHTML("...")
} // you now have a Try[String]. If Success, it contains the HTML.

Converting the Markup

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

Converting 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.)

Reading 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 t: Try[String] = MarkWrap.converterFor(file).map { converter =>
   converter.parseToHTML(Source.fromFile(file))
}

Example 2:

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

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

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 =

markupSource is the markup to be rendered.
title is the title to be put in the document’s <title> section.
cssSource is an optional Source specifying a file containing a cascading style sheet. The contents of the file are pulled inline.
encoding is the encoding of the document.

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

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:

Please state that the patch is your original work.
Please indicate that you license the work to the MarkWrap project under a BSD License.

Introduction

Installation

Installing for Maven

Using with SBT

Using with SBT

Building from Source

Source Code Repository

Build Requirements

Building MarkWrap

Using MarkWrap

Getting the Desired Parser

Converting Markdown

Converting Textile

“Converting” raw HTML

Handling plain text

Examples

Getting a converter via type

Getting a converter via MIME type

Getting a converter via filename

Converting the Markup

Converting to an HTML fragment

Reading from a Scala Source

Producing a complete HTML document

API Documentation

Change log

Author

Copyright and License

Patches

Reading from a Scala `Source`