Literate Visualization: Theory, software and examples
Switch branches/tags
narrative-schemas@0.1.0 narrative-schema@0.3.1 narrative-schema@0.3.0 narrative-schema@0.2.1 narrative-schema@0.2.0 narrative-schema@0.1.3 narrative-schema@0.1.2 narrative-schema@0.1.1 narrative-schema@0.1.0 narrative-schema-styling@0.1.2 narrative-schema-styling@0.1.1 narrative-schema-styling@0.1.0 narrative-schema-rule@0.1.3 narrative-schema-rule@0.1.2 narrative-schema-rule@0.1.1 narrative-schema-rule@0.1.0 narrative-schema-label@0.3.1 narrative-schema-label@0.3.0 narrative-schema-label@0.2.1 narrative-schema-label@0.2.0 narrative-schema-label@0.1.2 narrative-schema-label@0.1.1 narrative-schema-label@0.1.0 narrative-schema-common@0.1.2 narrative-schema-common@0.1.1 narrative-schema-common@0.1.0 litvis@0.7.0 litvis@0.7.0-alpha.1 litvis@0.7.0-alpha.0 litvis@0.6.0 litvis@0.5.6 litvis@0.5.5 litvis@0.5.4 litvis@0.5.3 litvis@0.5.2 litvis@0.5.1 litvis@0.5.0 litvis@0.4.0 litvis@0.3.0 litvis@0.2.7 litvis@0.2.6 litvis@0.2.5 litvis@0.2.4 litvis@0.2.3 litvis@0.2.2 litvis@0.2.1 litvis@0.2.0 litvis@0.1.0 litvis-integration-mume@0.7.0 litvis-integration-mume@0.7.0-alpha.1 litvis-integration-mume@0.7.0-alpha.0 litvis-integration-mume@0.6.0 litvis-integration-mume@0.5.6 litvis-integration-mume@0.5.5 litvis-integration-mume@0.5.4 litvis-integration-mume@0.5.3 litvis-integration-mume@0.5.2 litvis-integration-mume@0.5.1 litvis-integration-mume@0.5.0 litvis-integration-mume@0.4.1 litvis-integration-mume@0.4.0 litvis-integration-mume@0.3.0 litvis-integration-mume@0.2.7 litvis-integration-mume@0.2.6 litvis-integration-mume@0.2.5 litvis-integration-mume@0.2.4 litvis-integration-mume@0.2.3 litvis-integration-mume@0.2.2 litvis-integration-mume@0.2.1 litvis-integration-mume@0.2.0 litvis-integration-mume@0.1.0 literate-elm@0.7.0 literate-elm@0.7.0-alpha.1 literate-elm@0.7.0-alpha.0 literate-elm@0.6.5 literate-elm@0.6.4 literate-elm@0.6.3 literate-elm@0.6.2 literate-elm@0.6.1 literate-elm@0.6.0 literate-elm@0.5.0 literate-elm@0.4.0 literate-elm@0.3.5 literate-elm@0.3.4 literate-elm@0.3.3 literate-elm@0.3.2 literate-elm@0.3.1 literate-elm@0.3.0 literate-elm@0.2.0 literate-elm@0.1.2 literate-elm@0.1.1 literate-elm@0.1.0 elm-string-representation@1.1.4 elm-string-representation@1.1.3 elm-string-representation@1.1.2 elm-string-representation@1.1.1 elm-string-representation@1.1.0 elm-string-representation@1.0.2 elm-string-representation@1.0.1 elm-string-representation@1.0.0
Nothing to show
Clone or download

Literate Visualization · License: BSD 3-Clause Travis CI Status Code style: Prettier

A light-touch approach to designing, building and describing visualization. Here you will find

Installing litvis

Litvis documents can be viewed and created in either the Atom or VS Code editors:

  1. If you don't have it already, install Node.js. This will allow you to use npm, used for installing some of the other necessary software.

  2. Open a terminal window and install Elm, Prettier and Prettier Elm plugin with the following command:

    npm install --global elm prettier prettier-plugin-elm

    If you cannot install with npm because of 'EACCES write permission errors', see these instructions on how to prevent them.

  3. Install either the Atom (recommended) or VS Code editor.

  4. From within the editor, install litvis and Prettier extensions:

    • In Atom: Atom → Preferences → Install (or File → Settings → Install on Windows) In VSCode: View → Extensions

    • Search for markdown-preview-enhanced-with-litvis and then click the install button next to the returned result. This may take a few minutes on a slow network connection.

    • Search for prettier-atom (Atom) or prettier - Code formatter (VSCode) and then click the install button. This extension will help you format litvis documents as you edit them.

    • Search for language-elm (Atom) or elm (VSCode) and then click the install button. This extension enables syntax highlighting for Elm source in code blocks.

    • Atom users should also search for language-markdown and click the install button.

    Atom users: you may want to disable Atom’s standard markdown preview tool by going to Preferences → Packages (or File → Settings → Packages), searching for markdown-preview and clicking disable. You may also wish to disable spell-check too so that misspelled words are not confused with coding errors.

    VSCode users: The Prettier extension does not currently work with a global instance of Prettier (#232, #395). Until this is fixed, please consider installing prettier and prettier-plugin-elm in your project folder (i.e. without --global flag in step 2 above).

  5. When you create your first document in Atom, you may be asked to install further dependencies such as linter, linter-ui-default and busy-signal. Install these and any other dependencies if requested.

You should now be good to go! Get started by writing your first litvis document and looking at these tutorials.

‘Hello world’ in literate Elm

Adding litvis attribute literate (or l) to ```elm blocks in markdown automatically compiles and executes the code in real time. Attribute raw (or r) is the simplest way to see the result.



Simple litvis chart

A litvis code block with attribute visualize (or v) automatically renders the declared symbol using elm-vega / vega-lite.



Code referencing across blocks

By default, litvis code blocks share the same execution context, which means that an Elm symbol defined in one block and can be referenced in another block. It is not necessary to maintain the order of blocks to make referencing work.



Code referencing with triple hat notation

Symbols from Elm code blocks can be referenced in any part of the markdown using triple hat notation (^^^), e.g. ^^^elm v=barChart^^^.



Code referencing with parameters

Triple hat references accept parametrized function calls, which makes it easy to combine text with graphics and produce families of related graphics. This means that small multiples and sparklines are straightforward.



Debugging vega-lite specs

Replacing v with r for raw or j for json makes it possible to look into generated vega-lite specs. These attributes follow the same ordering rules as l and v.




Adding interactive to a code block with v or a triple hat reference makes visualizations live if interaction is described within Spec. User input controls can be added to the document, if desired.



Mutliple execution contexts

Although a single Elm execution context may be sufficient in many litivs narratives, context isolation may be desired in some cases. A number of code block attributes such as context, id, follows, isolated and siding enable fine-grained control of Elm symbol visibility, thus making it easier to accomplish certain tasks.

A siding (or s) is a shortcut for isolated follows=default. This keyword makes previously defined symbols in default context available within the code block, but avoids name clashes with the following blocks.



Branching narratives

A litvis narrative can be split between multiple markdown documents, where each document follows its parent. This enables routine use of parallel branching narratives that assemble and structure document trees. Each branch in a tree can represent alternative potentially competing designs each with their own rationale.


examples/features/branching/ > examples/features/branching/ > examples/features/branching/

Narrative schemas

A litvis narrative can be linked to a set of YAML files, which define labels, rules and styling. These narrative schemas can be thought of as an analogue of schemas more usually found in declarative programming contexts such as JSON and XML schema. The purpose of the schema is to provide a set of structured guidelines to assist in writing the narrative content around a visualization design. This can be thought of as form of scaffolding to assist in the process of design exposition. Schemas can be used to validate litvis documents.


examples/ > schemas/idiom.yml


A litvis document that is being previewed is constantly checked against various issues. These issues are displayed in the editing environment and help with debugging. If a visualization has been successfully rendered before the issue had occurred, its old preview is shown to avoid unwanted markup reflows.



Automatic code formatting

Litvis integrates with Prettier and its Elm plugin, which enables seamless document formatting as the narrative is being written. A file is automatically prettified on save or when the Format command is explicitly called. Formatting keeps litvis files in a readable and maintainable state, which eases collaboration and reduces distraction from the higher-level tasks.