markdown-preview-enhanced with litvis
This project is a fork of
vscode-markdown-preview-enhanced, which is a popular VSCode extension 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
The fork produces a VSCode extension 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.
Please ensure that you have a reasonably recent version of Node.js installed on your machine before proceeding to the setup.
It can be downloaded and installed from https://nodejs.org/.
Setup for VSCode users
Via VSCode’s GUI
Click on the extensions icon in the left panel, search for Markdown Preview Enhanced with litvis and click install.
If you are using Markdown Preview Enhanced extension (from which this project was forked), temporary uninstall or disable it while you are trying out litvis.
Via command line
code --install-extension gicentre.markdown-preview-enhanced-with-litvis
code --uninstall-extension shd101wyy.markdown-preview-enhanced
VSCode does not support
--disable-extension command, so if you want disable
shd101wyy.markdown-preview-enhanced instead of uninstalling it, please do this via the app’s GUI.
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
Formatting litvis narratives
It is possible to automatically format litvis-enabled markdown files including embedded Elm code blocks with Prettier, which is an opinionated code formatting tool.
Prettier is available in VSCode via
prettier-vscode extension, 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 VSCode:
esbenp.prettier-vscode package via VSCode’s Extensions panel or from a command line:
code --install-extension esbenp.prettier-vscode
Locally install Prettier and its Elm plugin via npm:
npm init --yes
npm install github:kachkaev/prettier#fix-global-plugin-api-dist prettier-plugin-elm
Having a globally installed Prettier would be more convenient, but it is not supported by the VSCode extension yet.
github:kachkaev/prettier#... instead of just
prettier is necessary until prettier/prettier#4192 is merged.
(optional) Configure Prettier by creating
.prettierrc with the following yaml:
- files: "*.md"
Doing this via bash:
echo -e "overrides:\n- files: \"*.md\"\n options:\n tabWidth: 4" > .prettierrc
This will indent bullet point lists in markdowns with four spaces instead of two.
Getting linting feedback for litvis narratives
If a litvis narrative you are currently editing contains problems like Elm compile errors, corresponding messages will be automatically shown in the Problems tab of VSCode:
The list of messages gets updated every time a preview is refreshed.
If you are using other tools such as Spell Checker, which also detect and report problems, litvis-specific messages may become lost amongst others.
In this case, you can type litvis in the filter input and thus filter out the messages that do not require your attention.