Quarto to Confluence

Quarto
Literate programming
Confluence
Author

Tomas

Published

May 14, 2024

Modified

February 25, 2025

Introduction

As of Quarto version 1.3 there is support for publishing documents to Confluence. Quarto can be used to publish single pages or entire Quarto projects to Confluence.

Preparations

Atlassian token

Before publishing a document, you need to create an atlassian wiki token. Save the token as you will be prompted for it upon publication.

The Quarto document

To make a document a target for publication in confluence, add the confluence-html document format to the header:

---
title: Confluence Demo
format: confluence-html
---

## Overview

Write your content in Quarto documents and publish to Confluence.

Publication from local client

This section describes how to render and publish documents from your local client.

Render and preview

Assuming the document name is index.qmd, you can first render the document locally to make sure everything looks ok.

quarto render index.qmd

The preview command lets you modify the document and view re-rendered changes in real time:

quarto preview index.qmd --port 8888

It is recommended you manually assign a port number, else Quarto will pick a random number for you.

Publish

To publish simply run

quarto publish index.qmd

Upon first publication, you will be prompted for your Confluence domain, email, login token and publication destination. For SciLifeLab, the domain is https://scilifelab.atlassian.net. The destination is chosen by navigating to the wiki page of interest and pasting it in at the prompt. The document will then be published relative to the chosen wiki page.

Publishing from UPPMAX

Technically, it should be possible to install Quarto on Uppmax from a Quarto package file. However, Quarto relies on GLIBC version>=2.18 which is currently unavailable on UPPMAX. A workaround is to generate an Apptainer image from which to run Quarto. This requires packaging Quarto with necessary dependencies, including R packages and a recent TeX distribution.

Render

With an Apptainer image /path/to/quarto.simg, the following code will render the document, optionally setting the execution directory:

export QUARTO_IMAGE=/path/to/quarto.simg
apptainer exec --home $(pwd) ${QUARTO_IMAGE} bash -c 'set -euo pipefail;  quarto render index.qmd --execute-dir $(pwd)'

Preview

Previewing could be done by firing up a browser on UPPMAX, but a better alternative is to employ port forwarding to display the output on your client. Run preview as follows:

apptainer exec --env PATH=/conda_env/bin/:$PATH \
          $QUARTO_IMAGE quarto preview --no-browser --port 8888 \
          --execute-dir $(pwd)/..

Assuming you are on rackham1, on your client run

ssh -f -N -L 8888:localhost:8888 rackham1.uppmax.uu.se

to setup port forwarding. Now you can preview your Quarto document by navigating to https://localhost:8888.

Previewing from a compute node

Some Quarto documents run heavy computations and should in these cases be rendered/previewed from a compute node. However, this would require setting up a double port forward. Fortunately, there exists an SSH configuration called JumpHost that eliminates this step.

Edit your .ssh/config file to contain the following:

Host r*.uppmax.uu.se
    User username
    ProxyJump rackham1.uppmax.uu.se

This allows you to access a compute node directly from your client. For instance, if you are running a job on r111, run the preview command as above, and change the port forward command to

ssh -f -N -L 8888:localhost:8888 r111.uppmax.uu.se

Publish

Publishing from UPPMAX is done by running

export QUARTO_IMAGE=/path/to/quarto.simg
apptainer exec --home $(pwd) ${QUARTO_IMAGE} bash -c 'set -euo pipefail;  quarto publish index.qmd --execute-dir $(pwd)'

Examples

Example upload instructions

Use this link when asked where to put you page: https://scilifelab.atlassian.net/wiki/spaces/EBT/pages/2899836938/Quarto+examples

Give the page a name on this format with your name to make it unique: “Quarto_example-Tomas”

Publishing Quarto projects as Confluence pages

The aim was to test a varied selection of quarto markup and interactive elements as well as raw output to and see what is supported by the Quarto to Confluence conversion.

Pixi was used to create the quarto environment.

pixi init -c conda-forge -c bioconda
pixi add quarto jupyter ipyleaflet plotly pandas statsmodels jupyter-cache

Quarto was then used to create a confluence project.

pixi shell
quarto create project confluence .

This was then published to Confluence using:

quarto publish confluence

where I was asked to provide the domain https://scilifelab.atlassian.net, followed by my username, an API token (A link to the page was provided to create one), and finally the url path to where I wanted to publish https://scilifelab.atlassian.net/wiki/spaces/EBT/pages/2902917121/Quarto+example+-+Mahesh. As I was unsure if I would overwrite the work of others I created this page first after quarto indicated the folder didn’t exist.

I was also instructed by quarto to

quarto install chromium

At this point Quarto began rendering, but hung at the second page. The issue was localized to creating the mermaid diagram. After converting the mermaid diagram to a code block {.mermaid} the project successfully published to confluence.

Several things didn’t render although might be achievable in other ways:

  • Mermaid diagram rendering failed locally and didn’t upload as an image.
  • Interactive plotting failed. Perhaps this needs to be embedded as an attachment.
  • Interactive map did not produce any kind of map, even a static image.
  • References did not work.
  • Column layout did not work.

Quarto document

Quarto document

Quarto document