Case Study: University of Oklahoma Libraries

This authoring tools case study was provided by Cody Taylor, Emerging Technologies Librarian, University of Oklahoma Libraries.

Beginning summer 2017, faculty authors receiving grants from the University of Oklahoma Libraries Alternative Textbook Grant will use Markdown as part of their authoring workflow.

Background: Limitations in Openness

Often, open textbook authors work with tools that are designed for writing and publishing 8.5 x 11 documents. Most authoring tools, like Microsoft Word, simultaneously format and style text in paper-based formats. For example, if an open textbook is written in Microsoft Word, it can be shared as a PDF, but not as a webpage. This means that an author is limited in the file formats he or she can make available to students and to people who may want to edit the book.

In the open education community, this is described as a lack of technical openness. It means that even when a textbook is openly licensed to allow for changes, technical limitations make it difficult to do so.

In order to break free from these limitations, open textbook authors could compose their content in plain text using as little markup as possible.

Markdown as an Alternative

Markdown is a minimalistic markup syntax that can be written in any text editor and is intended to be human-readable.

Markdown files can be made with the text editors that come with Microsoft Windows (Notepad) and OS X (TextEdit). Markdown files are plain text and can be saved as text (.txt) or markdown (.md) files. In order to be useful, these files need to be converted into other formats. This is also what makes Markdown so flexible.

If authors write open textbooks in plain text, they can also use Github, a tool designed for tracking revisions made to open source code that also enables collaboration on open source software projects. It works just as well for tracking changes made to plain text documents, because code is also plain text.

The open source software community has been wildly successful, arguably because code is easily shared and modified. Publishing the source (markdown files) of open textbooks follows this lead.

Writing with Markdown

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email. — – John Gruber, daringfireball.net

As an example of Markdown’s simplicity and readability, paragraph text, the most frequently used text format, requires no syntax in Markdown. Markdown converters conveniently assume that if no syntax is applied to a body of text, it is paragraph text.

As additional examples, here is the syntax for bolded text, italicized text, hyperlinks and headings:

This is bolded text.
**This is bolded text.**

This is italicized text.
*This is italicized text.*

This is a hyperlink.
[This is a hyperlink.](http://google.com)

# This is an H1 heading.
## This is an H2 heading.
### This is an H3 heading.

Converting Markdown

There are several tools that convert Markdown into popular file formats.

Pandoc is a tool that can convert Markdown files into HTML, PDF, EPUB, and DOCX. It can apply Cascading Style Sheets (CSS) to HTML documents, and invoke MathJax for rendering LaTeX equations as webfonts and images — a litmus test for how well suited an authoring tool is for composing textbooks.

Most text editors are easy to install, but Markdown conversion tools often are not. Moreover, many conversion tools require that users be familiar with the command line and using command line tools, as there is no graphic user interface. This is a significant obstacle.

With this in mind, University of Oklahoma Libraries created a web application that allows users to convert their Markdown files without needing to install a tool or use any command line tools. In other words, faculty authors and library project managers can convert Markdown files into various formats using an online graphic interface.

Using this web application, a user uploads their Markdown files, then selects up to four desired output formats and a style sheet. Users can include their own custom style sheet with the Markdown files during upload if they wish. The application then processes these files and the product is downloaded into the user’s browser within moments.

This process eliminates the need for users to 1) install another tool for converting Markdown, and 2) use a command line. Behind the scenes, Pandoc and wkhtmltopdf, another file converter, are doing the conversion, but are hidden by the web application’s interface.

This open source application is still under development and has yet to be deployed in an actual open textbook authoring use case. Those who want to improve on the tool or host their own instance can find its code on Github. Feedback is welcome.