다른 문서에서 임베드하기

개요

embed 숏코드를 사용하면 다른 Quarto 문서(.qmd, .ipynb)의 출력을 포함할 수 있습니다. 코드 블록이나 노트북 셀의 출력을 임베드하려면 문서 경로와 블록/셀 식별자를 제공하세요. 예를 들어 penguins.ipynb라는 Jupyter 노트북에 fig-bill-scatter 레이블을 가진 셀이 있다고 가정합니다.

Jupyter 노트북 'penguins.ipynb'에서 fig-bill-scatter 레이블이 지정된 셀과 결과 플롯이 강조된 스크린샷

다음 숏코드로 해당 셀 출력을 임베드할 수 있습니다.

{{< embed penguins.ipynb#fig-bill-scatter >}}

플롯은 다음과 같이 삽입됩니다.

Figure 1: A scatterplot of bill dimensions for penguins, made with Altair.
Source: 팔머 펭귄 (.ipynb)

플롯 아래에는 소스 노트북 링크가 자동으로 제공됩니다. 링크를 클릭하면 노트북을 로컬로 다운로드해 실행하지 않아도 탐색할 수 있는 렌더링 페이지가 열립니다. 예를 들어 penguins.ipynb 링크를 누르면 다음과 같은 페이지가 표시됩니다.

'penguins.ipynb' 제목과 'Download Notebook' 버튼, 이어지는 노트북 내용이 보이는 웹페이지 스크린샷

Jupyter 노트북(.ipynb)과 Quarto 문서(.qmd) 모두 상호 임베드할 수 있습니다. 이 문서에서는 소스 문서를 통칭해 노트북이라고 부릅니다.

기본 사용법 외에도 다음 작업이 가능합니다.

셀 지정

embed 숏코드는 상대 경로+셀/코드 블록 식별자(예: penguins.ipynb#fig-bill-scatter)로 소스 노트북을 지정합니다. 식별자를 생략하면 노트북의 모든 셀/코드 블록이 문서에 임베드됩니다.

Quarto 문서

소스가 .qmd일 때는 코드 블록의 label을 식별자로 사용합니다. 예를 들어 penguins.qmd에 다음 코드 블록이 있다면:

penguins.qmd
```{r}
#| label: fig-size-scatter
ggplot(penguins, aes(body_mass_g, flipper_length_mm)) +
  geom_point(aes(color = species)) +
  scale_color_manual(values = colors) +
  theme_minimal()
```

다음과 같이 임베드합니다.

{{< embed penguins.qmd#fig-size-scatter >}}

결과는 아래와 같습니다.

Figure 2
Source: title: “팔머 펭귄 (.qmd)”

Jupyter 노트북

소스가 Jupyter 노트북이라면 셀 식별자를 찾기 위해 다음 순서의 휴리스틱을 사용합니다.

  1. 셀 id
    먼저 셀 메타데이터의 id가 일치하는지 확인합니다. ( 셀 ID는 아직 널리 지원되진 않지만, 향후 호환성을 위해 먼저 확인합니다.)
  2. 레이블
    일치하는 id가 없으면 코드 메타데이터에 있는 label이 셀 식별자와 일치하는지 확인합니다.
  3. 태그
    위 조건이 모두 없으면 태그가 셀 식별자와 일치하는 셀(또는 셀 집합)을 사용합니다.

셀 태그

예를 들어 JupyterLab에서 셀 태그에 bill-ratio를 지정한 셀을 임베드하려면:

Jupyter 노트북 셀 도구 모음에서 'bill-ratio' 태그가 설정된 코드 셀 스크린샷

다음과 같이 사용합니다.

{{< embed penguins.ipynb#bill-ratio >}}

결과는 아래와 같습니다.

A density plot of bill ratio by species.

코드 셀 옵션

소스 노트북의 코드 셀 옵션은 임베드된 문서에도 그대로 적용됩니다. 예를 들어 fig-cap, fig-alt, layout-ncol 같은 셀 옵션을 사용해 임베드된 그림의 캡션·레이아웃 등을 제어할 수 있습니다. 아래 penguins.ipynb 셀은 캡션, 서브캡션, 대체 텍스트, 레이아웃을 지정합니다.

penguins.ipynb
#| label: fig-bill-marginal
#| fig-cap: "Marginal distributions of bill dimensions"
#| fig-subcap: 
#|   - "Gentoo penguins tend to have thinner bills,"
#|   - "and Adelie penguins tend to have shorter bills."
#| fig-alt:
#|   - "Density plot of bill depth by species."
#|   - "Density plot of bill length by species."
#| layout-ncol: 2

sns.displot(penguins, 
            x = "bill_depth_mm", 
            hue = "species", 
            kind = "kde", fill = True, aspect = 2, height = 3)
plt.show()
sns.displot(penguins, 
            x = "bill_length_mm", 
            hue = "species", 
            kind = "kde", fill = True, aspect = 2, height = 3)
plt.show()

이 셀을 임베드하면:

{{< embed penguins.ipynb#fig-bill-marginal >}}

다음과 같은 결과가 생성됩니다.

Density plot of bill depth by species.
(a) Gentoo penguins tend to have thinner bills,
Density plot of bill length by species.
(b) and Adelie penguins tend to have shorter bills.
Figure 3: Marginal distributions of bill dimensions

코드 임베드

숏코드에 echo=true 옵션을 추가하면 셀/블록 출력과 함께 코드도 포함할 수 있습니다. 예를 들어 penguins.ipynb의 species-counts 셀에서 코드와 플롯을 함께 임베드하려면 다음과 같습니다.

{{< embed penguins.ipynb#species-counts echo=true >}}

문서에는 해당 셀의 코드와 출력이 함께 표시됩니다.

penguins.groupby("species").size().reset_index(name = "count")
species count
0 Adelie 152
1 Chinstrap 68
2 Gentoo 124

그림 옵션과 마찬가지로 코드 표시 옵션도 소스 노트북에서 전달됩니다. 예를 들어 이 셀의 코드를 접고 싶다면 species-counts 셀에 code-fold: true를 추가합니다.

penguins.ipynb
#| label: species-counts
#| code-fold: true
penguins.groupby("species").size().reset_index(name = "count")

또한 셀을 임베드하는 문서의 YAML 헤더에 설정한 옵션도 적용됩니다. 예를 들어 모든 코드를 접으려면 문서 YAML에 code-fold: true를 추가하세요.

sample.qmd
title: Exploration of penguin characteristics
author: Norah Jones
toc: true
format:
  html:
    code-fold: true

소스 노트북 링크

Quarto 문서에 노트북 내용을 임베드하고 HTML로 렌더링하면, Quarto가 자동으로 소스 노트북 링크를 추가합니다. 기본적으로 임베드된 콘텐츠 아래와 목차 아래(별도 섹션) 두 곳에 링크가 표시됩니다. 예를 들어 다음 문서는 penguins.ipynb에서 콘텐츠를 임베드했으며, 렌더링된 HTML에서 링크를 확인할 수 있습니다.

임베드된 플롯 아래와 목차 아래 'Notebooks' 섹션에 'penguins.ipynb' 링크가 표시된 스크린샷

링크 위치

문서 YAML에서 notebook-links 옵션을 지정해 링크 위치를 제어할 수 있습니다.

true (기본값)

임베드된 콘텐츠 아래와 목차 옆에 링크를 모두 표시합니다.

false

링크를 표시하지 않습니다.

inline

임베드된 콘텐츠 아래에만 링크를 표시합니다.

global

목차 옆에만 링크를 표시합니다.

노트북 뷰

기본적으로 소스 노트북 링크는 자동 생성된 HTML 미리보기로 연결됩니다. 사용자는 노트북을 다운로드하거나 로컬에서 실행하지 않고도 내용을 확인할 수 있습니다. 이 노트북 뷰는 노트북 본문과 “Download Notebook” 버튼을 제공합니다.

'penguins.ipynb' 제목, 'Download Notebook' 버튼, 노트북 본문이 보이는 웹페이지 스크린샷

이 문서에서 사용한 penguins.ipynb, penguins.qmd 노트북의 라이브 미리보기도 확인할 수 있습니다.

뷰 옵션

notebook-view 옵션으로 노트북 뷰 동작을 제어할 수 있습니다. 노트북마다 title, url을 지정할 수 있으며, title은 링크 텍스트와 뷰 페이지 상단에 표시됩니다. url을 제공하면 해당 링크로 이동합니다. Github, Google Colab, Kaggle 등에 노트북을 배포했을 때 유용합니다.

notebook-view:
  - notebook: penguins.ipynb
    title: "Plots and Computations"
    url: https://colab.research.google.com/drive/12GsIPQ644SI4vkEEHiZn-Qqfbr-bD1__

위 설정을 사용하면 링크가 다음과 같이 표시됩니다.

플롯 아래와 목차 아래에 'Plots and Computations' 링크가 표시된 스크린샷

노트북 뷰를 비활성화하고 노트북 파일로 직접 연결하려면 notebook-view를 false로 설정하세요. 그러면 사용자가 중간 페이지 없이 바로 노트북을 다운로드할 수 있습니다.