andrewhead / living-papers

Authoring tools for scholarly communication. Create interactive web pages or formal research papers from markdown source.

Living Papers

Authoring tools for scholarly communication. Create interactive web pages or formal research papers from markdown source. Living Papers is intended to be a "language toolkit" for parsing, transforming, and rendering documents.

To get up and running quickly, use the Living Papers project template. Then take a look at other example articles.

This repo is a research testbed for Living Papers development. There will be bugs. Contributions (issues, PRs, etc) are welcome!

Setup

Pre-Requisites

Before working with Living Papers, set up your local environment:

1. Install Node.js and npm if you don't have them already. We recommend using a node version manager like nvm. Node v16.17 or higher is recommended.
2. Install pandoc. You should be able to run pandoc from the command line. A recent version of Pandoc (v2.18 or higher) is recommended.
3. Install other software packages as needed:

• To use R code blocks, install R along with the knitr package and any other libraries you wish to use.
• To publish LaTeX / PDF output, install a TeX distribution such as TeX Live. You should be able to run pdflatex and bibtex from the command line.

Usage Instructions

To use Living Papers for a new publishing project, you can install the @living-papers/cli npm package, which provides the lpub utility to convert source to output documents.

That said, we recommend copying the project template repo for a pre-configured authoring setup.

Developer Instructions

Clone this monorepo, run npm install to install JavaScript dependencies.

Once installed, you can:

• Run npm run test to run test cases across monorepo packages.
• Run npm run lint to lint source code across monorepo packages.
• Run npx lpub filename.md to compile a source file in the current directory.

The examples folder contains example Living Papers articles. Within the folder for each example, run npm run build to produce compiled output article(s).

Package Overview

This repository uses a monorepo organization. Here is an overview of the folder structure:

• examples: Example Living Papers articles
• packages: Primary Living Papers packages
  • ast: Abstract Syntax Tree (AST) manipulation
  • cli: Command line interface programs
  • compiler: Article parser and compiler
  • components: Web components for HTML output
  • runtime: Reactive runtime for HTML output
  • runtime-compiler: JavaScript parser/compiler for the reactive runtime
• templates: Article templates
  • html: Built-in templates for HTML output
  • latex: Built-in templates for LaTeX output