Add confluence intro

quarto-to-wiki/confluence.qmd

@@ -0,0 +1,145 @@
+# Quarto to Confluence introduction
+
+As of Quarto version 1.3 there is support for [publishing documents to
+Confluence](https://quarto.org/docs/publishing/confluence.html). This
+brief introduction outlines the basic procedure.
+
+## Preparations
+
+### Atlassian token
+
+Before publishing a document, you need to [create an atlassian wiki
+token](https://id.atlassian.com/manage-profile/security/api-tokens).
+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, simply add
+the `confluence-html` document format to the header:
+
+``` markdown
+---
+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.
+
+```{bash }
+quarto render index.qmd
+```
+
+The **preview** command lets you modify the document and view
+re-rendered changes in real time:
+
+```{bash }
+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
+
+```{bash }
+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](https://quarto.org/docs/download/). 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:
+
+```{bash }
+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:
+
+```{bash }
+#| label: label
+#| echo: false
+#| eval: false
+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
+
+```{bash }
+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/previede from a compute node. However, this would require
+setting up a double port forward. Fortunately, there exists an SSH
+configuration called
+[JumpHost](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Proxies_and_Jump_Hosts)
+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 
+
+```{bash }
+ssh -f -N -L 8888:localhost:8888 r111.uppmax.uu.se
+```
+
+### Publish
+
+Publishing from UPPMAX is done by running
+
+```{bash }
+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)'
+```