Atom markdown-preview-enhanced with litvis

This project is a fork of markdown-preview-enhanced, which is a popular Atom package for previewing markdown files. Most of the code in this fork is inherited from the upstream repository and is thus courtesy of @shd101wyy and other contributors to markdown-preview-enhanced.

The fork produces an Atom package called markdown-preview-enhanced-with-litvis, which enables Literate Visualisation (litvis) in rendered markdown previews.

Litvis functionality has been designed and developed at giCentre by Jo Wood, Alexander Kachkaev and Jason Dykes. This research was in part supported by the EU under the EC Grant Agreement No. FP7-IP-608142 to Project VALCRI.

Prerequisites

Please ensure that you have elm installed on your machine before proceeding to the setup. The following command will ensure that this tool is in place and is up-to-date.

npm install --global elm

If you don’t have npm, please download it as a part of Node.js from https://nodejs.org/.

Setup for Atom users

Via Atom’s GUI

1. Go to Preferences → Packages and disable markdown-preview (Atom’s standard preview tool)

2. If you are using markdown-preview-enhanced, temporary disable it too while you are trying out this fork.

3. Switch to Install section in Preferences and search for markdown-preview-enhanced-with-litvis. Click Install and reload Atom.

Via command line

This section contains shortcut commands for the instructions above.

apm disable markdown-preview
apm disable markdown-preview-enhanced
apm install markdown-preview-enhanced-with-litvis

Getting started with litvis narratives

Literate visualization uses Elm and Vega-Lite in the form of a declarative visualization language elm-vega. While you don't have to use elm-vega in a litvis document, it does enable quick declarative generation of interactive data graphics and therefore considerably enhances the capability of a litvis document.

Creating your own litvis narrative is as easy as writing a markdown file. You can start with exploring the examples available at https://github.com/gicentre/litvis/tree/master/examples.

Formatting litvis narratives

It is possible to automatically format litvis-enabled markdown files (including Elm code blocks) using Prettier, which is a popular code formatting tool.

Prettier is available in Atom via prettier-atom package, but it does not format literate Elm code blocks in markdown files out of the box.

Please follow these steps to enable full-featured formatting support for litvis in Atom:

1. Globally install Prettier and its Elm plugin via npm:

   npm install --global prettier prettier-plugin-elm
   

2. Install prettier-atom package via Atom’s Preferences or from a command line:

   apm install prettier-atom

3. Enable Format on save in prettier-atom package preferences.

Getting linting feedback for litvis narratives

When a currently opened litvis narrative contains issues such as errors in Elm code blocks, you are automatically shown a list of problems via Atom's built-in linter.

If you have used Atom linting for any programming language before, all the necessary packages should be already installed. Otherwise, please install Atom packages named linter, linter-ui-default, intentions and busy-signal.

You will be prompted to do so when you open a litvis document for the first time. Alternatively, you can install the packages via Atom’s Preferences or by using the following command:

apm install linter linter-ui-default intentions busy-signal

When you are working on branching litvis narratives or those depending on narrative schemas, you may benefit from going to linter-ui-default settings and changing Panel Represents parameter to Entire project. This will make the list of reported issues more informative.