Skip to content

08 Using Your Own Computer

Jump to bottom
Lauren McKeen edited this page Apr 4, 2022 · 8 revisions

Lantern is provided as a GitHub template repository with all of the processing provided by GitHub Actions, but you are also able to run Lantern on your own computer. This is highly recommended if you plan to make any edits to the templates or would like to quickly preview your project as you make changes. Here's a quick guide for anyone who's ready to get started on their own. Skip ahead if you just want to know the software requirements

This guide assumes you have already completed the initial project setup tutorial and have your own Lantern project ready on your GitHub account.

Required Software

Optional Software

  • Python v3.x: for running a local web server for development purposes (useful for styling and previewing HTML)
  • Pandoc-crossref: a pandoc filter for numbering figures, equations, tables and cross-references to them.
  • A LaTeX distribution: for LaTeX/PDF typesetting and generation (we like TinyTeX)

Installation Tips

Windows

These programs have Windows installation wizards you can use, accepting defaults:

  • Download and install Pandoc
  • Download and install Visual Studio Code
    • This is recommended; you can use any text editor
  • Download and install GitHub Desktop
    • In GitHub Desktop, sign in with your GitHub.com credentials

The following programs need some explanation...

PagedJS

This is a tool that will convert HTML files to PDF using CSS rules. Lantern uses PagedJS to generate PDF because HTML and CSS is more widely known and easier to use than LaTeX.

  • Visit the NodeJS website and download the LTS version (16.14.0). This is a JavaScript runtime we'll need to install PagedJS.
  • Install NodeJS using the installation wizard, accepting the default settings.
  • Open a PowerShell window (Press the Windows key, search "PowerShell")
    • If you see an error that says something like "npm" is not recognized. Close, then re-open PowerShell, and try again. It's possible we need to restart the terminal for NodeJS commands to work.
  • After running the below command, any terminal messages that are not errors (such as warnings or vulnerabilities) can be ignored.
npm install -g pagedjs-cli pagedjs

Git

  • Download and install Git, using the default settings, except:
    • Select "Use Visual Studio Code as Git's Default editor"
    • Select "Override the default branch name for new repositories"
      • This is in-line with GitHub's default branch name: main
    • Select "Checkout as-is, commit Unix-style line endings"

Tips for Installing pandoc-crossref

Pandoc-crossref is a filter that handles the linking between equation, table, and figure references. This is an optional program, but is useful for any STEM-related projects.

There's no "easy" way to install pandoc-crossref, unfortunately. You can visit the releases page on GitHub, download the file labeled pandoc-crossref-Windows, extract the file contents on your computer using 7zip or any file archiving compression tool to a secure folder on your machine, then add executable to your %PATH% variable.

If you're not sure how to do this, there's a semi-easy way using a command-line package manager called Scoop:

  • Open PowerShell on your computer (Press the Windows key, search for "PowerShell", then select the Windows PowerShell app) and run this command in the window:
iwr -useb get.scoop.sh | iex

scoop install pandoc-crossref
macOS
  • Download and install Visual Studio Code
    • This is recommended; you can use any text editor
  • Download and install Git
  • Download and install GitHub Desktop
    • In GitHub Desktop, sign in with your GitHub.com credentials

Homebrew Package Manager

Homebrew is a popular software package manager for macOS (and Linux). We can use it to install the remaining programs. Visit the Homebrew homepage to install it.

Once you have it, run this command to install Pandoc, pandoc-crossref, and NodeJS:

brew install pandoc pandoc-crossref node@16

Then, run this command to install [PagedJS]:

npm install -g pagedjs-cli pagedjs

Optional: LaTex

If you'll be working on projects containing content for mathematics or the physical sciences, you might prefer to format equations and figures with LaTeX. In this case, you'll need a LaTeX distribution installed on your system. There are many out there. You can install BasicTeX, for example, with Homebrew:

brew install --cask basictex

Starting from a Project on GitHub

You can clone (i.e. download) any repositories you started on GitHub, or you can start a new Lantern project. To start a new Lantern project:

  • Open GitHub Desktop
  • You should see a page that says "Let's get started"; if not, select "Find" --> "New repository..." in the menu bar
  • Select the URL tab, then enter: nulib-oer/lantern
  • The default name for this repository on your computer will be "lantern", but you can name this something more specific to your project by editing the "Local path" field and entering the name of your project
    • Repositories are folders on your computer. It is recommended you use all lowercase letters and separate words with a hyphen, such as "new-lantern-demo-project"
  • Click on "Clone"
  • To view the contents of this folder, click on "Repository" in the menu bar and select "Open in Visual Studio Code"
  • In Visual Studio Code, click on "Terminal" in the menu bar
  • Click on the down-arrow on the right side of the window
  • Select "Git Bash"
  • To build the sample HTML output, run in the Git Bash terminal prompt:
bash lantern.sh html

The output HTML files of the project will be in the public folder. You can now open this folder with Visual Studio Code to edit the files and add your content.

If everything seems to work, you can delete the sample chapter in the text folder and begin adding your own content.

Adding your own content

  • Locate your project folder on your computer
  • Add your individual manuscript files (.docx format) to the original folder
  • To convert the files to Markdown format for editing, go back to Visual Studio Code and run in the Git Bash terminal prompt:
bash lantern.sh convert

The output Markdown files of the project will be in the text folder. Open the folder with Visual Studio Code to edit and preview before publishing.

Starting from Scratch: Using Lantern without GitHub

  • Your terminal ("Git Bash" on Windows). You will be in your user's "home" directory. You can view the path to your current directory:
pwd
  • To change directories into your "Documents" folder, run:
cd Documents
  • Let's make a new directory for your lantern projects:
mkdir lantern-projects
  • Now let's move into that directory:
cd lantern-projects

Suppose you want to start a new project about statistics. Let's use the Lantern template repository on GitHub to create a new folder on your computer for your project (replace "my-project" in the following command with whatever project name you want):

git clone https://github.com/nulib-oer/lantern.git my-project

Now, let's move into the new project directory:

cd my-project

View the contents of this folder:

ls

To build the sample HTML output, run:

bash lantern.sh

The output HTML files of the project will be in the public folder. You can now open this folder with Visual Studio Code to edit the files and add your content.

If everything seems to work, you can delete the sample chapter in the text folder and begin adding your own content.

Adding your own content

  • Locate your project folder on your computer
  • Add your individual manuscript files (.docx format) to the original folder
  • To convert the files to Markdown format for editing, go back to Visual Studio Code and run in the Git Bash terminal prompt:
bash lantern.sh convert

The output Markdown files of the project will be in the text folder. Open the folder using Visual Studio Code to edit and preview before publishing.

Troubleshooting PDF Output on Windows

If you get the error pagedjs-cli not found. Please select a different --pdf-engine after running bash lantern pdf, do the following:

Run (in Git Bash):

where pagedjs-cli

Copy the path that includes the .cmd extention (e.g. C:\Users\...\pagedjs-cli.cmd))

Open settings/pdf.yml and change:

pdf-engine: pagedjs-cli

to:

pdf-engine: 'C:\Users\...\pagedjs-cli.cmd)'

Then try again: bash lantern.sh pdf

Clone this wiki locally