Introduction to Literate Programming with Quarto

Siju Swamy

Saintgits

Publishing workflow

---
Publishing workflow
---
%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%%
flowchart LR
  
    E1("(1)\nExternal resources"):::external -.-> A1
    A1{{"(2)\nAuthoring tool"}} --> I1("(3)\nText + Figures +\nCode + Tables + ..."):::input
    I1 --> P1{{"(4)\nFormatting tool"}}
    P1 --> O1["(5)\nFormatted\nOutput"]:::output
    O1 -.-> D1{{"(6)\nDelivery system"}}:::delivery
    classDef external fill:#eee,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5;
    classDef input fill:#ffa;
    classDef output fill:#faa;
    classDef delivery stroke:#666,stroke-width:2px,stroke-dasharray: 5 5;

An example of the creation of a personal website. You collect (1) material to publish in your website data, figures, analyses, and results, those resources are put together with (2) an Integrated Development Environment like Visual Studio creating (3) an organised hierarchy of files and text that includes formatting information, then using (4) a formatting tool like Jekyll all the artefacts are combined into (5) a website of html and other files that can be (6) hosted in a web server.

Quarto is a formatting tool

%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%%

flowchart LR
  
    E1("External resources"):::external -.-> A1
    A1{{"Authoring tool"}} --> I1("Text + Figures +\nCode + Tables + ..."):::input
    subgraph "Quarto, pdflatex, xelatex, pandoc, ..." 
      direction LR
      I1 --> P1{{"Quarto\nFormatting tool"}}:::quarto
      P1 --> O1["Formatted\nOutput"]:::output
    end
    classDef external fill:#eee;
    classDef input fill:#ffa;
    classDef output fill:#faa;
    classDef quarto fill:#75aadb,color:#000;

Quarto supports Single-In-Multi-Out

%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%%

flowchart LR
    I1("(3)\nText + Figures + \n Code + ..."):::input --- dummy2{{"(4) Quarto\nFormatting tool"}}:::quarto
    dummy2 --> O1["(5a) Published \n Paper \n (PDF)"]
    dummy2 --> O2["(5b) Presentation \n Slides \n (PPTX/PDF)"]
    dummy2 --> O3["(5c) Poster \n (PPTX/PDF)"]
    dummy2 --> O4["(5d) Computational \n Notebook \n (Colab)"]
    classDef input fill:#ffa;
    style O1 fill:#fca
    style O2 fill:#bff
    style O3 fill:#f99
    style O4 fill:#bfb
    classDef quarto fill:#75aadb,color:#000;

Available for multiple OS

Using quarto

$ quarto --help

  render     [input] [args...]     - Render files or projects to various document types.
  preview    [file] [args...]      - Render and preview a document or website project.  
  serve      [input]               - Serve a Shiny interactive document.                
  create     [type] [commands...]  - Create a Quarto project or extension               
  use        <type> [target]       - Automate document or project setup tasks.          
  add        <extension>           - Add an extension to this folder or project         
  update     [target...]           - Updates an extension or global dependency.         
  remove     [target...]           - Removes an extension.                              
  convert    <input>               - Convert documents to alternate representations.    
  pandoc     [args...]             - Run the version of Pandoc embedded within Quarto.  
  typst      [args...]             - Run the version of Typst embedded within Quarto.   
  run        [script] [args...]    - Run a TypeScript, R, Python, or Lua script.        
  install    [target...]           - Installs a global dependency (TinyTex or Chromium).
  uninstall  [tool]                - Removes an extension.                              
  tools                            - Display the status of Quarto installed dependencies
  publish    [provider] [path]     - Publish a document or project to a provider.       
  check      [target]              - Verify correct functioning of Quarto installation. 
  help       [command]             - Show this help or the help of a sub-command.

Getting started

Get started documentation: quarto.org/docs/get-started/
Open-source repository in GitHub: Quarto-cli
Create a project with quarto create project
- Type: default, website, blog, manuscript, book, confluence
Build project with quarto render
Preview with quarto preview (it autobuilds and updates when changes in the source files are detected).

Authoring tools

%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%%
flowchart LR
  
    E1("External resources"):::external -.-> A1
    subgraph "Vim, NeoVim, Notepad" 
      direction LR
      A1{{"Authoring tool"}} --> I1("Text + Code +\nTables + ..."):::input
    end
    I1 --> P1{{"Quarto\nFormatting tool"}}:::quarto
    P1 --> O1["Formatted\nOutput"]:::output
    classDef external fill:#eee;
    classDef input fill:#ffa;
    classDef output fill:#faa;
    classDef quarto fill:#75aadb,color:#000;

Authoring with formatting (IDE + Quarto)

%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%%
flowchart LR
  
    E1("External resources"):::external -.-> A1
    subgraph "IDE + Quarto" 
      direction LR
      A1{{"IDE\nAuthoring tool"}} --> I1("Text + Figures +\nCode + Tables + ..."):::input
      I1 --> P1{{"Quarto\nFormatting tool"}}:::quarto
      P1 --> O1["Formatted\nOutput"]:::output
    end
    classDef external fill:#eee;
    classDef input fill:#ffa;
    classDef output fill:#faa;
    classDef quarto fill:#75aadb,color:#000;

Integrated Development Environments

Quarto is integrated in multiple IDEs

Then, what is Quarto?

Quarto is a formatting tool
uses pandoc to convert the input artefacts to various outputs.
supports plain text markdown, Jupyter notebooks and an augmented markdown,
supports dynamic content with Python, R, Julia and Observable programming languages.
is integrated in multiple IDEs: Visual Studio, Posit Connect (former RMarkdown), Atlassian Confluence, …