The {quarto-colab} extension enables Google Colab integration for your Quarto documents rendered to Juypter Notebook. It adds "Open in Colab" badges and handles the configuration of Jupyter magic commands for languages like R, SQL, and Octave, letting anyone run your notebooks in Colab with a single click.

Note

This Quarto extension is open source software and is not affiliated with Google. The extension is at best a community effort to simplify the integration of Google's Colaboratory runtime inside of Quarto documents.

Installation

Add the extension to your Quarto project by running the following command in Terminal within your Quarto project directory:

quarto add coatless-quarto/colab

This command will download and install the extension under the _extensions subdirectory of your Quarto project. If you're using version control, make sure to include this directory in your repository.

Requirements

Quarto >= 1.4.0
R and knitr (for polyglot document evaluation)
GitHub public repository (for Colab to access your notebooks)
Google Colab account (for Colab features)

Usage

We recommend using this extension as part of a multi-format output using jupyter and html formats.

Basic Setup

Add the following to your document's header or _quarto.yml:

---
title: "My Document"
format:
  jupyter: default
  html: default
colab:
  gh-user: "username"    # Your GitHub username
  gh-repo: "reponame"    # Your repository name
  gh-branch: "main"      # Optional, defaults to "main"
filters:
  - colab
---

Scrolling to Specific Cells

You can configure the extension to automatically scroll to a specific cell when opening the notebook in Colab:

colab:
  gh-user: "username"
  gh-repo: "reponame"
  gh-branch: "main"
  scroll-to: "sGO-VJ_Bb0tU"   # Cell ID to scroll to

This will create a Colab link that includes the scrollTo parameter, like:

https://colab.research.google.com/github/username/reponame/blob/main/notebook.ipynb#scrollTo=sGO-VJ_Bb0tU

Tip

To find a cell's ID in Colab, right-click on a cell and select "Copy Link to Cell". The part after scrollTo= is the cell ID.

Language Configuration

Magic Commands (Optional)

Define the cell magic commands for different languages to use in your document:

magic-commands:
  r: "%%R"              # Custom R magic command
  julia: "%%julia"      # Custom Julia magic command
  newlang: "%%newlang"  # Custom magic command for a new language

Setup Cells (Optional)

Define custom environment setup for different languages:

setup-cells:
  r:
    language: "python"    # Language assumed for the setup cell
    code: |
      # Custom R setup
      !pip install rpy2
      %load_ext rpy2.ipython

HTML Support (Work in Progress)

While automatic HTML integration is under development, you can manually add Colab links to your HTML output:

format:
  html:
    code-links:
      - text: "Open in Colab"
        href: "https://colab.research.google.com/github/USERNAME/REPO/blob/BRANCH/PATH_TO_NOTEBOOK.ipynb"
        icon: "laptop"

Replace USERNAME, REPO, BRANCH, and PATH_TO_NOTEBOOK.ipynb with your specific values.

Note

We know this is a bit cumbersome and are working on a better solution.

Supported Languages

The extension includes pre-configured setup for:

R (using {rpy2})
Julia (using {juliacall})
Octave (using {oct2py})
SQL (using {jupysql})
SAS (using {saspy} + licensed copy and a way to access it)

Additional languages are supported via magic commands without requiring specific setup cells.

Ruby
Perl
bash/sh

For additional languages, you can define custom magic commands and setup cells in the document's header.

Acknowledgements

This extension is based on the Using Google Colab with GitHub notebook.

Notes

This extension formed the basis of my second ever issue ticket on the Quarto project's GitHub issue tracker quarto-dev/quarto-cli#1224. The issue ticket was opened on October 1, 2022. Wowie, how time flies when you're having fun!