Abstract

With Living Papers, you can author an interactive web page or standard reseach paper from Markdown source documents. This example article demonstrates the basic syntax and functionality of a Living Papers document. Compare the source markup and the resulting rendered web page!

Basic Formatting

Basic formatting includes:

• Inline text with italics, bold, or both.
• Inline code x = Math.PI * r * r.
• Inline code with syntax highlighting x = Math.PI * r * r.
• Inline math .
• Super^script, sub_script, and strikethrough.
• Hyperlinks and styled spans.
• Lists (like this one!)

Math & Equations

Mathematical notation is specified using TeX syntax. Inline math (), math blocks, and numbered equation blocks are supported. Compare a math block:

And an equation block:

Figures & Tables

Basic images and tables can be included without adornment using standard Markdown. To create numbered and captioned elements, place content within :::-fenced figure or table blocks.

Citations

Give credit where credit is due! Living Papers was inspired by earlier work by on the Idyll language. Living Papers supports citations references with author name(s) or with reference number only []. Citations are also interactive: click/tap a citation to view a pop-up with more information.

Citation information can be automatically retrieved using a unique ID:

• A DOI [@doi:10.1145/3242587.3242600] → []
• A Semantic Scholar ID [@s2id:4fca64e6dc4e803d3ed904c04c6845a9e6adc53e] → []

Citations can also be defined in BibTeX format, either in an external file (listed under the references key of the article metadata) or included anywhere in the document in a bibliography block:

~~~ bibliography
@inproceedings{conlen2021,
  title={Idyll Studio: A structured editor for authoring interactive \& data-driven articles},
  author={Conlen, Matthew and Vo, Megan and Tan, Alan and Heer, Jeffrey},
  booktitle={The 34th Annual ACM Symposium on User Interface Software and Technology},
  pages={1--12},
  year={2021}
}
~~~

For example, (@conlen2021) extends Idyll with a graphical structured editor to create interactive articles without writing markup code.

To create a list of citations [, ], separate references with semi-colons: [@doi:10.1145/3242587.3242600; @conlen2021].

Cross-References and Notes

Cross-references use a syntax similar to citations:

• Figures: @fig:teaser → , @fig:goldenratio →
• Tables: @tbl:irrational →
• Equations: @eqn:ratio →

By default, a descriptive prefix like Figure is included.To show a reference number only, wrap the reference like so: [-@fig:goldenratio] → .

Interactive Figures

Living Papers support interactive content using JavaScript code blocks and an extensible component system, all connected via a shared reactive runtime. The runtime automatically re-evaluates page content in response to interactive updates.

Living Papers uses the same JavaScript dialect as Observable notebooks. We can define variables, add input widgets, and generate figures (e.g., using Vega-Lite or Observable Plot, as in ) just as we would in a notebook. We can also directly import content from public Observable notebooks, like this D3-based line chart of unemployment rates by U.S. county:

And more…

Living Papers also supports other types of content (not demonstrated here) through custom plugins. One or more plugins can be specified under the plugins article metadata key. For example:

• The knitr plugin evaluates R code blocks (```r) at compile time and includes the results in the output document (similar to RMarkdown).
• The pyodide plugin evaluates Python code blocks (```py) in the browser using Pyodide. These Python blocks follow the same reactive logic as Observable JavaScript, and computed Python results are directly accessible from JavaScript.

References

1. Conlen, M., & Heer, J. (2018, October 11). Idyll. Proceedings of the 31st Annual ACM Symposium on User Interface Software and Technology. UIST ’18: The 31st Annual ACM Symposium on User Interface Software and Technology. https://doi.org/10.1145/3242587.3242600
2. Conlen, M., Vo, M., Tan, A., & Heer, J. (2021). Idyll Studio: A structured editor for authoring interactive & data-driven articles. The 34th Annual ACM Symposium on User Interface Software and Technology, 1–12.