여러 페이지/파일에서 동일한 콘텐츠를 하나의 소스로 관리하면 오류 위험을 줄이고 유지보수가 쉬운 일관된 콘텐츠를 만들며 소중한 시간을 절약할 수 있습니다. Quarto(/index.qmd)는 Includes 기능(즉, R Markdown의 “child” 문서)으로 여러 문서/파일/페이지에서 콘텐츠를 재사용하도록 지원합니다.
이를 활용하려면 텍스트, 표, 코드, 콜아웃, 이미지 등 콘텐츠 조각을 만들어 다음과 같이 Include 쇼트코드로 삽입하면 됩니다: {{< include _content.qmd >}}.
일반적으로 Include에 넣을 콘텐츠는 여러 위치에서 재사용할 수 있도록 일반적인 형태로 유지합니다. 예를 들어 특정 파일에만 들어갈 이름이나 이미지를 포함해야 한다면 Include를 사용하기 어렵다고 생각하거나, 각기 다른 내용을 가진 여러 Include를 만들어 써야 했습니다.
그런데 콘텐츠를 더 구체적으로 조정해야 한다면 어떻게 할까요? meta 쇼트코드(변수)와 함께 Include를 사용하면 파일 수준에서 정의한 정확한 값을 삽입할 수 있습니다.
예제 따라하기
아래 예제로 과정을 따라가 보겠습니다.
시작 전 준비:
- Quarto 1.5 이상에서 예제를 테스트했습니다.
- 새 웹사이트 프로젝트와 기존 프로젝트 모두에서 작동합니다.
var쇼트코드는 프로젝트 또는 파일 수준 변수를 삽입하는 데 사용합니다.meta쇼트코드는 Pandoc 메타데이터(YAML 상단 또는_quarto.yml)에서 값을 가져옵니다.- 사이트를 미리보는 동안에는 페이지가 렌더링되어 갱신되지만, 글로벌 설정(
_quarto.yml또는 포함된 파일)을 수정한 뒤에는 전체 사이트를 다시 렌더링해야 모든 변경이 반영됩니다. 따라서 미리보기로 몇몇 페이지를 확인했더라도 배포 전에 전체quarto render를 반드시 실행하는 것이 좋습니다.
콘텐츠 만들기
다음은 여러 페이지에서 재사용하려는 콘텐츠 예시입니다.
In this document, we cover facts that are unique to the state, like the state's population, its flower, and animal.이 콘텐츠는 각 주의 소개에 공통적으로 쓸 수 있지만, 각 주 고유의 정보를 담고 있지 않으므로, 각 파일에 Include를 삽입한 뒤 특정 주의 정보를 추가하는 방식으로 활용할 수 있습니다:
---
title: New York
---
{{< include _snippets/state-intro.qmd >}}
New York has a geographical size of 54,555, making it the 27th largest state with an estimated population size of 19.8 million.
The state's flower is the Rose, as shown below:
왜 이렇게 하죠?
각 파일에 위 내용을 복사한 뒤 주별 정보만 바꾸는 방식은 오류 가능성이 높습니다. 대신 meta 변수를 사용해 특정 값을 삽입하면 재사용 파일 하나로도 각 주에 특화된 내용을 표현할 수 있습니다.
실제 실행하기
먼저 _snippets 디렉터리에 facts.qmd 파일을 만들고, 재사용 콘텐츠 안에 상태별로 달라질 부분에 고유한 meta 쇼트코드를 넣습니다:
{{< meta state >}} covers approximately {{< meta square-miles >}} making it the {{< meta size-rank >}} largest state in the United States. As of 2023, {{< meta state >}} has an approximate population of about {{< meta population >}}.각 주 파일에서는 YAML 메타데이터에 해당 변수를 정의한 뒤 Include로 facts.qmd를 삽입합니다. 예: ny.qmd 파일의 YAML:
---
title: New York
state-abbr: ny
state: New York
size-rank: 27th
square-miles: 54,555
population: 19.8 million
---
{{< include _snippets/facts.qmd >}}렌더링된 결과물에서는 각 meta 쇼트코드가 YAML에 정의한 값으로 채워집니다.
여기에 주별 꽃과 동물을 이미지와 함께 추가하고 싶다면 문서를 수정해 다음과 같이 쓸 수 있습니다:
{{< include _snippets/facts.qmd >}}
New York's official flower is the Rose:
And the official animal is the Beaver:
또는 이미지 경로에도 meta 쇼트코드를 넣어 단일 파일로 모든 콘텐츠를 관리할 수도 있습니다:
{{< meta state >}}'s official flower is the {{< meta flower >}}, pictured below:
Lastly, {{< meta state >}}'s official animal is the {{< meta animal >}}, pictured below:
이미지 경로에 {{< meta state-abbr >}}를 넣으면 해당 주의 디렉터리(ny, pa, vt 등)에서 이미지를 읽어올 수 있습니다.
프로젝트를 렌더링하면 해당 이미지 경로는 /images/ny/flower.png처럼 자동으로 변환되어 ny 디렉터리의 이미지가 표시됩니다:
원칙적으로 각 주 디렉터리가 동일한 이름 규칙(pa/flower.png, vt/flower.png)을 따르도록 엄격하게 정리된 구조를 갖추면, 이 방식을 확장해서 활용할 수 있습니다.
이미지도 동일한 디렉터리·파일명을 따르도록 관리해야 하기 때문에 체계적이고 확장 가능한 방법이 필요하지만, 그렇게 하면 하나의 Include만으로 각 주마다 개별화된 페이지와 이미지를 만들어낼 수 있습니다.
렌더링된 예시
다음은 뉴욕 페이지입니다:
다음은 펜실베이니아 페이지입니다:
각 페이지는 단일(공유) 파일로 구성됩니다:
{{< include _snippets/facts.qmd >}}Quarto Includes 더 알아보기
Quarto Includes 기능은 중복을 줄이고 여러 문서에 걸쳐 일관된 콘텐츠를 만들며 콘텐츠 제작 과정을 개선합니다. 기술 문서, 교육 자료, 기타 콘텐츠를 관리할 때 이 접근법은 시간 절약, 오류 감소, 완성도 높은 결과물 제작에 도움이 됩니다.
다음 자료를 참고하세요: