Lantern

Introduction

Lantern is a Pandoc template and workflow toolkit for making open textbooks. Lantern applies minimal computing techniques to OER publishing.

“Minimal computing” is a critical framework that places limits on hardware and software choices in order to prioritize the longevity of digital texts, the mitigation of technological obscolescence, and the maintenance of systems. Lantern applies this framework to the production of open textbooks.

Features

  • Free: Lantern uses open source software and free-of-charge web services for processing, building, deploying, and hosting open textbooks.

  • Portable: Lantern emphasizes the use of plain text file formats that can run on any machine or web host. No databases or servers are required.

  • Multi-format: Lantern teaches semantic markup technologies for producing Markdown, HTML, PDF, DOCX, and LaTeX editions of open textbooks.

  • Sustainable: Lantern minimizes the infrastructure, configuration, hosting, and maintenance costs related to traditional digital publishing systems and platforms.

  • Discoverable: Lantern produces harvestable metadata in OAI-PMH, JSON-LD and Google Scholar tags.

Lantern uses Markdown as a typesetting format for publishing and Pandoc as it’s processing engine to produce publication formats, such as HTML, PDF, DOCX, and EPUB. Markdown as a source format provides many advantages for academic writing, OER production, and preservation:

“Markdown is intended to be as easy-to-read and easy-to-write as is feasible. Readability, however, is emphasized above all else. 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.” - John Gruber (one of Markdown’s original creators)

Plain text files have many advantages over other formats. For one, they are readable on virtually all devices. They have also withstood the test of time better than other file types – if you’ve ever tried to open a document saved in a legacy word processor format, you’ll be familiar with the compatibility challenges involved. (simpkin_getting_2015?)

Who is Lantern for?

Lantern was developed as an open source toolkit for the open education community. We developed Lantern to help minimize the digital production, hosting, and maintenance costs of multi-format textbook publishing by using open source software, free web services, and static web technologies. We hope our documentation helps people who are new to things like the command line terminal, Markdown, Git, and GitHub.

Credits

Lantern is a project by Chris Diaz (Digital Publishing Librarian) and Lauren McKeen McDonald (Open Education Librarian) of Northwestern University with support from the Association of Research Libraries. Lantern is based on Pandoc Book Template, and was inspired by numerous publishing tools, including Bookdown, Quire, Course-in-a-Box, CollectionBuilder, and Wax.

Quick Start

Beginners might want to read the Technology Overview and the Online Workflow sections for guided instructions and context, but here’s a quick guide for anyone who’s ready to get started.

Required Software

Get the Template

  • Download a copy of the template repository via git clone or as a .zip archive.
  • Open the repository folder in your terminal
  • Test the sample outputs: $ sh lantern.sh
    • This will use the sample content in the source directory and the default configurations in the assets directory to build a website, PDF, EPUB, DOCX, and LaTeX editions of a textbook in the public directory.
  • The terminal will return errors if you’re missing any required software in your PATH
  • If you don’t see errors, you can open the public directory to see the sample outputs.

If everything seems to work, you can delete or edit any of the files in the source directory.

Adding your Content

Your new repository comes with a few files and folders you’ll be using to add and edit your manuscript content. All of these files and folders are contained in the source directory. These are the only files and folders you will need to edit to use Lantern for your textbook project.

  • chapters/: This folder contains the textbook chapter files

  • images/: This folder contains the textbook images for figures, logos, covers, etc.

  • preprocess/: If you add .docx, .odt, or .tex files to this folder, you can run sh lantern.sh preprocess to automatically convert these files to Markdown and add them to the chapters/ folder

  • data/: This folder stores data about our project, including metadata (metadata.yml), references in BibTex format (references.bib), and output configurations (config.yml).

Build Commands

  • sh lantern.sh html: Creates an index.html file for your textbook homepage and textbook.html for the HTML version.

  • sh lantern.sh pdf: Creates a textbook.pdf file for your textbook with images embedded in appropriate places throughout the text.

  • sh lantern.sh epub: Creates a textbook.epub file for your textbook with images embedded in appropriate places throughout the text. This file can be used with e-book readers.

  • sh lantern.sh docx: Creates a textbook.docx file for your textbook with images embedded in appropriate places throughout the text. This file can be edited by other instructors interested in reusing or remixing the textbook content using Microsoft Word or other word processing software.

  • sh lantern.sh latex: Creates a textbook.tex file for your textbook. This file can be edited by other instructors interested in reusing or remixing the textbook content using LaTeX.

  • sh lantern.sh oai: Creates an OAI-PMH file (oai.xml) in the public folder for harvesting in library cataloging systems.

  • sh lantern.sh: Does all of the above.

  • sh lantern.sh clean: Deletes the public folder so that you can have a clean build. This does not affect the source folder.

Deploy your website

Once you’re done editing your textbook, go to your terminal and sh lantern.sh to generate a fully-fuctional static website that you can be uploaded to any web server or hosting service. This command creates and places all of your output files within a folder called public. The contents within the public folder are intended to be ready for distribution with the public.

For example, you can use Netlify Drop. Netlify is a web hosting service that specializes in static websites. Here’s a video to demonstrate the Netlify Drop feature:

If you want to give it a try, drag and drop the public folder from your computer to Netlify Drop to see your textbook project live on the web. From there, you can use the Netlify to manage your website, such as adding a custom domain name.

Definitions

Vocabulary Term
Definition of the term.
Vocabulary Term
Definition of the term.