Litvis
A light-touch approach to designing, building, and describing visualizations using literate programming in Markdown.
What is Litvis?
Litvis is a literate visualization framework that combines Markdown, Elm, and Vega-Lite to create interactive, reproducible data visualizations with integrated narrative text. It allows developers and researchers to design, build, and describe visualizations in a single document where code execution and chart rendering happen in real-time. The tool solves the problem of separating visualization code from its documentation, enabling more transparent and maintainable data storytelling.
Data visualization researchers, educators, and developers who need to create reproducible, well-documented interactive charts and want to integrate narrative explanation directly with their code.
Developers choose Litvis for its seamless integration of live Elm code execution, interactive graphics, and Markdown-based documentation in a single environment. Its unique selling point is the literate programming approach that treats visualization design and exposition as a unified process, supported by features like cross-block referencing and branching narratives.
Overview
Literate Visualization: Theory, software and examples
Use Cases
Best For
- Creating interactive data visualizations with embedded explanatory text
- Building reproducible research documents that combine analysis and visualization
- Teaching data visualization concepts with live coding examples
- Developing branching narrative explorations of alternative chart designs
- Generating parameterized families of related graphics (e.g., small multiples)
- Debugging and inspecting Vega-Lite specifications within a document context
Not Ideal For
- Teams using JavaScript, Python, or other languages instead of Elm for visualization
- Projects requiring lightweight, editor-agnostic setups without VS Code and npm dependencies
- Building standalone web applications or dashboards outside of Markdown documents
- Quick prototyping with pre-built chart libraries like D3.js or Chart.js
Pros & Cons
Pros
Elm code blocks compile and execute in real-time with results embedded directly in the markdown, enabling immediate feedback and iterative design as shown in the hello world and chart examples.
Symbols defined in one code block can be referenced in others or in text using triple-hat notation (^^^), allowing seamless integration of code and narrative, as demonstrated in the parameterized references example.
Supports interactive charts and user input controls via Vega-Lite/Vega specifications, with the 'interactive' attribute making visualizations live, as highlighted in the interaction GIF.
Branching narratives and YAML-based schemas provide scaffolding for organizing and validating content around visualizations, facilitating reproducible research and design exploration.
Cons
Requires VS Code with specific extensions (markdown-preview-enhanced-with-litvis, prettier, elm tooling), limiting editor flexibility and adding setup complexity for other environments.
Heavily tied to Elm and elm-vega/vegalite libraries, restricting visualization options and requiring Elm proficiency, which may not align with teams using more common web tech stacks.
Multi-step installation involving Node.js, Elm, npm, Prettier, and editor configurations, as detailed in the setup instructions, creating a barrier to quick adoption.
Frequently Asked Questions
Related Projects
Elm Formatelm-format formats Elm source code according to a standard set of rules based on the official Elm Style Guide
type-o-rama👾 JS type systems interportability
Elm JSONInstall, upgrade and uninstall Elm dependencies
Elm OracleQuery for information about values in elm source files.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.