Currently in Beta - View old docs

Kitura Markdown

In this guide, we will show you how to serve a web page generated from Markdown templates (.md files) using Kitura-Markdown.

Step 1: Add KituraMarkdown to the Kitura App

To use Markdown from a server, we first need to add Kitura-Markdown to our dependencies.

If you don't have a server, follow our Create a server guide.

Next, we need to import the KituraMarkdown package:

import KituraMarkdown

Now we can add the KituraMarkdown template engine to our router instance:

Below the line let router = Router() we will add:

router.add(templateEngine: KituraMarkdown())

This tells the server that on this instance of the router we'd like to use KituraMarkdown as a template engine.

Kitura is capable of having numerous template engines registered to a single instance of a router.

Kitura then provides APIs to select a default template engine to use.

We've just added the KituraMarkdown template engine to our router, so now we can use it in a route.

Just below our other registered routes we can create a new route for KituraMarkdown:

router.get("/book") { request, response, next in
    try response.render("book.md", context: [:])
}

The response.render() method attempts to populate the provided template file with the provided data.

However as we are rendering a Markdown file there we don't need to provide any data as it all will be in the Markdown file.

So in our case KituraMarkdown will take the book.md file and render the Markdown in it to be viewed in a browser.

This obviously will not work as we haven't created our book.md file.

Step 2: Create the template file

By default Kitura looks for template files in a ./Views directory found at the root of the project.

Typically the root of your project is where the .xcodeproj directory is.

Once we are in the root of our project we can create the directory:

mkdir Views

If you would prefer you can create your directory using a UI based approach, such as Finder on Mac.

Then we need to create our template file within the Views directory:

cd Views && touch book.md

Now we have everything we need to start creating our templates.

If you are using Xcode and used the command line to create your Views directory you will need to regenerate your Xcode project:

swift package generate-xcodeproj

This is to enable Xcode to detect the new directory.

Step 3: Populate the Markdown template file

First we need some Markdown to render.

So in the book.md file we will add:

# Books Header

Description with **bold** text

* Book1
* Book2

Now to test our templating we first need to start the Kitura server.

Then in a brower we can open:

http://localhost:8080/book

In the browser we should see:

Books Header

Description with bold text

  • Book1
  • Book2

That's it! We've successfully rendered some Markdown into a browser using KituraMarkdown.

Back to top