Web applications serve HTML content. Much of this content makes up the various pages of the application. Such HTML is either hand written by developers or generated from templates, often in templating languages designed for developers. This HTML content if most often is much more about laying out other content than actual text in the HTML.

Many times one wants to serve formatted text. This text can be documentation or help information, news, release notes, etc. This sort of text typically requires its own set of HTML files, due to formatting requirements which can vary a lot. If the person authoring the text, is a professional content producer he/she probably has easy to use tools that help him/her create HTML formatted content. In addition to content created by professional content producers, there is much content created by others, who while being professionals in their own field of endeavor, aren’t necessarily equipped with the tools of professional content producers. One popular solution to this problem is to create files that use Markdown for the formatting rather than HTML.

Markdown

Markdown is a simple markup language used to create formatted text. Its goal was for the markup to be similar in nature to the way people had been marking up text in e-mails. Converters exist for converting content written in Markdown to a variety of formats including HTML.

Files marked up using Markdown are often used in open source projects for documentation. So much so, that source code control sites such as GitHub, will automatically render Markdown files (files with an extension of md) as HTML.

Kitura-Markdown

Kitura-Markdown has been written to enable Kitura based servers to easily serve HTML content from text marked up using Markdown. The marked up text can come from files on the file system read by Kitura-Markdown, from Strings, and from Data structs containing UTF-8 encoded bytes.

Kitura-Markdown is an implementation of the Kitura TemplateEngine protocol for Markdown (md) files. The Kitura TemplateEngine protocol is used by classes/structs to enable Kitura based servers to generate HTML content from templates in a variety of templating languages. for more information on templating with Kitura see Using Templating Engines with Kitura

In addition Kitura-Markdown provides a pair of static helper functions to generate HTML from Strings and bytes in Data structs marked up using Markdown.

Under the covers Kitura-Markdown uses the cmark C language reference implementation of CommonMark making Kitura-Markdown highly compliant and highly performant.

An example

The best way to show how to use Kitura-Markdown is through a simple example.

This Kitura based server, serves both documentation and news from files marked up using Markdown. For the purposes of this example I’m ignoring anything else this server might be doing.

The server will have this basic structure:

ServerRepository
├── Package.swift
├── Sources
│   └── Server
│       └── main.swift
└── views
    └── docs
        ├── index.md
        ├── doc1.md
        ├── doc2.md
          ...

Let’s start with the Package.swift file:

import PackageDescription

let package = Package(
    name: "KituraSample",
    dependencies: [
        .Package(url: "https://github.com/IBM-Swift/Kitura.git", majorVersion: 1, minor: 2),
        .Package(url: "https://github.com/IBM-Swift/Kitura-Markdown.git", majorVersion: 0, minor: 5)
    ]
)

In the main.swift file, there would be the following code snippets, broken up to make it easier to explain them.

The first snippet imports Kitura and KituraMarkdown, creates the Router object, and adds KituraMarkdown as a TemplateEngine. The latter is what enables the code to use Kitura’s RouterResponse.render API to
convert a file marked up in Markdown to HTML.

import Kitura
import KituraMarkdown

// Create a new router
let router = Router()

// Add KituraMarkdown as a TemplateEngine
router.add(templateEngine: KituraMarkdown())

The next code snippet defines a Kitura RouterHandlers that handles HTTP GET requests when the path is
/docs. It will cause the file views/docs/index.md to be rendered using the KituraMarkdown
template engine using the Kitura RouterResponse.render() API.

// Handle HTTP GET requests to /docs
router.get("/docs") { _, response, next in
    try response.render("/docs/index.md", context: [String:Any]())
    response.status(.OK)
    next()
}

I should point out, that the response.render() function takes two parameters. The first one is the template to render. The second parameter is a dictionary of key value pairs that can be used as substitution values within the template. Unfortunately at this time Kitura-Markdown doesn’t support substituting values in the template.

The next code snippet defines a second Kitura RouterHandlers that handles HTTP GET requests when the path is of the form /docs/something. It will cause the file views/path, where path is the path of the HTTP request, to be rendered using the KituraMarkdown template engine again
using the Kitura RouterResponse.render() API.

// Handle HTTP GET requests to /docs/......
router.get("/docs/*") { request, response, next in
    if let path = request.parsedURL.path, path != "/docs/" {
        try response.render(path, context: [String:Any]())
        response.status(.OK)
    }
    next()
}

The final snippet creates an HTTP Server and starts it as one would do in any standard Kitura based server.

// Add an HTTP server and connect it to the router
Kitura.addHTTPServer(onPort: 8090, with: router)

// Start the Kitura runloop (this call never returns)
Kitura.run()

Using the above server, if the file views/docs/index.md contained the following Markdown markup:

# Sample documentation Table of Contents

  1. [First chapter](/docs/doc1.md)

  2. [Second chapter](/docs/doc2.md)

and one pointed his/her browser at http://the_host:8090/docs you would receive an HTML page that looked like this:

screen-shot-2016-11-23-at-16-46-48

If one then clicked on the First chapter hyperlink, then the file views/docs/docs1.md would be rendered as HTML and would like the following:

screen-shot-2016-11-23-at-17-01-41

Next steps

Now you should be able to extend your Kitura based servers with the ability to serve files marked up in Markdown, using Kitura-Markdown. The group of people who can generate content to be served by your server should also grow making your site more dynamic.

You can see the sample code above as part of the Kitura-Sample application, in particular in the file Sources/KituraSampleRouter/RouterCreator.swift

You now have an extra templating tool in your toolbox, in addition to Kitura’s other template engines Kitura-MustacheTemplateEngine for GRMustache and Kitura-StencilTemplateEngine for Stencil. With it I hope your Kitura based servers will be better than they were before.

Leave a Reply