Stevenson

a nodejs app to compile and publish websites and documents via pandoc.

Installation / requirements

Requirements

Stevenson uses pandoc, so pandoc have to be installed. Stevenson have currently been tested with pandoc 1.12.4.2

Pandoc install instructions

Stevenson runs with nodejs, so nodejs have to be installed.

NodeJS install instruction

Installation

To install stevenson (on Linux / OSX) :

sudo npm install -g stevenson

To upgrade stevenson :

sudo npm update stevenson

Usage

stevenson [--config=...] [options] ACTION [file]

Document header

To be processed by stevenson, a document have to begin with a yaml header block, between two blocks of three dashes. The file have to begin with three dashes as first characters.

The data contained within yaml header block is described here

---
title: My Wonderful document
author: Me
(...)
---

The header can be empty.

Config file

Instructions to process files / build site / serve / upload it are given in a yaml config file.

The config file used can be

• given from command line using --config FILENAME command line option
• searched as _config.yml in root directory given by --root PATH command line option
• searched as _config.yml in current directory

If no config file can be found, a default config file is used for pandoc action. Other actions (build, site, serve, clean, publish) cannot be done without config file.

A default config file and templates directory can be installed using init action.

$ stevenson init

Process a document through pandoc

pandoc action is a wrapper around pandoc invocation, allowing use of different options for pandoc against output format.

$ stevenson FILE.md

Extracts metadata and processes file with pandoc, outputting each format found in header or having output.FORMAT.auto = true in config file.

Learn more on pandoc action

Build all documents

build action runs pandoc action against every file with yaml header found under root path.

If output files exists and are more recent than source files (source file, linked images, templates), no processing is done unless --force option is given.

To force output for a format, --force-FORMAT option can be used.

Create site

site action processes all markdown files with a yaml header to html, passing them through template engine, outputting them to _site directory. All other files are copied verbatim to _site.

Serve site

serve action runs a local webserver at default url : http://localhost:9000 serving _site directory.

Publish

publish action sends site to distant server (currently, only basic rsync).