`contents`: 문서 내 콘텐츠 재배치

개요

문서에서 콘텐츠를 작성하는 순서와 실제로 보여 주고 싶은 순서가 다른 경우가 있습니다. Lua 필터를 작성해 해결할 수도 있지만, Quarto 1.6 이상에서는 많은 상황에 적용 가능한 간단한 방법인 {{< contents >}} 숏코드를 제공합니다.

간단한 사용 예시는 다음과 같습니다.

## A section

여기에서 그래프를 정의합니다.

```{python}
#| echo: false
#| label: a-cell
import matplotlib.pyplot as plt
plt.plot([1,2,3])
```

## Another section

다른 섹션에서는 Callout 내부에서 그래프를 사용합니다.

::: callout-note

## Note the following plot

{{< contents a-cell >}}

:::

위 코드를 렌더링하면 다음과 같은 결과가 생성됩니다.

사용 이유

{{< contents >}}를 사용하면 문서를 가장 편한 방식으로 작성하면서도 원하는 위치에 결과를 배치할 수 있습니다. 다른 설명 중간에 코드를 작성하고, 결과는 다른 곳에 보여 주고 싶을 때 특히 유용합니다.

또 다른 중요한 이유는 Jupyter 노트북이 마크다운 내부에 코드 셀을 “중첩”할 수 없다는 점입니다. Quarto 기능의 상당수는 아래와 같은 fenced div 기반 마크다운으로 정의됩니다.

::: {#div-id .class1 .class2 key1="value1"}

fenced div의 내용

:::

이런 경우 .ipynb로 Quarto 문서를 작성하면 번거로울 수 있습니다. {{< contents >}}를 이용하면 Jupyter Notebook, JupyterLab, Quarto 확장이 이해하기 힘든 방식으로 마크다운을 나누지 않고도 코드 셀 내용을 마크다운 셀 내부에서 사용할 수 있습니다.

동작 방식

Quarto는 {{< contents <id> >}} 숏코드를 “문서에서 ID가 <id>인 셀의 내용을 가져와 이 위치에 삽입하라”는 뜻으로 해석합니다.

가장 자연스러운 용도는 코드 셀 재배치이지만, div나 span의 ID를 사용해 다른 콘텐츠에도 적용할 수 있습니다.

Caution

아래 div의 ID는 #a-div가 아니라 a-div입니다. 따라서 {{< contents a-div >}}처럼 참조해야 합니다.

::: {#a-div}

fenced div의 내용

:::

div와 span을 이동할 때는 적절한 위치에 삽입해야 합니다. 예를 들어 div는 문단 중간에 넣을 수 없으며, 그 경우 span을 사용해야 합니다. 따라서 아래처럼 할 수는 없습니다.

```{python}
#| label: a-cell
print("some code")
```

코드 셀의 출력은 {{< contents a-cell >}}입니다.

이와 같은 구성을 원한다면 코드를 인라인으로 작성하고 span으로 감싸야 합니다.

여기에서 값을 정의합니다. [`{python} "some code"`]{#a-span}

이 인라인 코드 셀의 출력은 {{< contents a-span >}}입니다.

제약 사항

현재 {{< contents >}}는 코드 요소 내부에서는 작동하지 않습니다. 향후 이 제한이 해제될 수 있습니다.