논문 템플릿

개요

학술지 논문 포맷은 생성된 출력물을 세밀하게 제어하고 학술지 전용 명령과 지시문을 사용할 수 있어야 하는 경우가 많습니다. Quarto 포맷에서는 커스텀 Pandoc 템플릿(LaTeX 및/또는 HTML)을 제공해 이를 구현할 수 있습니다. 이러한 템플릿은 학술지 전용 LaTeX와 Pandoc이 요구하는 표준 지시문이 섞인 형태인 경우가 많습니다. 이 문서에서는 Pandoc과 잘 호환되면서 출판사 수준의 고품질 출력물을 생성하는 커스텀 학술지 템플릿을 만드는 방법을 설명합니다.

템플릿

Quarto는 마크다운 파일에서 렌더링된 출력물을 생성하기 위해 Pandoc 템플릿을 사용합니다. Pandoc 템플릿은 포맷별 콘텐츠와 변수로 이루어집니다. 변수는 렌더링된 문서의 값으로 대체됩니다. 예를 들어 가장 기본적인 템플릿은 다음과 같습니다.

mytemplate.tex

\documentclass{scrartcl}
\begin{document}
$body$
\end{document}

위 템플릿에서 $body$ 변수는 문서 본문에서 생성된 LaTeX로 대체됩니다. 본문 텍스트가 마크다운으로 Hello **world**!라면 $body$ 값은 Hello \textbf{world}!가 됩니다.

렌더링에 사용할 커스텀 템플릿을 제공하면 최종 출력물을 완전히 제어할 수 있습니다. 커스텀 템플릿은 다음처럼 지정합니다.

format:
  pdf:
    template: mytemplate.tex

템플릿 문법에 대한 자세한 내용은 템플릿 문법을 참고하세요.

템플릿 partial

템플릿 전체를 교체하면 렌더링 출력물을 완전히 제어할 수 있지만, Pandoc과 Quarto의 많은 기능은 내장 템플릿에 있는 코드와 변수에 의존합니다. 템플릿 전체를 교체하면서 이 변수들을 누락하면 기능이 제대로 동작하지 않습니다.

따라서 템플릿을 작성할 때는 다음 두 가지 접근 중 하나를 권장합니다.

마스터 LaTeX 또는 HTML 템플릿 안에 있는 partial을 선택적으로 대체합니다.
LaTeX 또는 HTML 템플릿 전체를 교체하되, Quarto가 제공하는 partial을 포함하여 Pandoc과 Quarto의 모든 기능을 활용할 수 있게 합니다.

아래에서는 두 접근을 모두 다룹니다. 이 문서를 읽은 뒤 quarto-journals에 공개된 포맷의 소스 코드를 참고하면 추가 예제를 확인할 수 있습니다.

partial 대체

LaTeX/PDF와 HTML 출력에 대해 Quarto는 여러 ‘partial’ 템플릿 파일로 구성된 내장 템플릿을 제공합니다. 이 포맷에서는 Quarto 내장 템플릿의 일부만 교체해 전체를 바꾸지 않고도 특정 부분만 커스터마이즈할 수 있습니다. LaTeX에서 문서 제목을 커스텀 처리하는 간단한 partial은 다음과 같습니다.

title.tex

\title{$title$}
\author{$for(author)$$author$$sep$ \and $endfor$}
\date{$date$}

이 partial은 다음과 같이 Quarto에 제공합니다.

format:
  pdf:
    template-partials:
      - title.tex

Quarto는 partial이 제공된 경우 내장 템플릿을 사용하되 해당 부분을 partial로 교체합니다. 위 예시에서는 LaTeX 제목이 partial에 정의된 구현으로 대체되고, 나머지는 내장 템플릿이 사용됩니다.

partial 파일의 이름은 중요합니다. 그 이름의 partial을 제공함으로써 템플릿의 어떤 부분을 교체할지 결정합니다. 빈 파일을 partial로 제공하면 메인 템플릿을 수정하지 않고도 일부 기능을 비활성화할 수 있습니다.

각 포맷에서 사용할 수 있는 partial 목록은 아래에서 확인할 수 있습니다: LaTeX partial, Beamer partial, Typst partial, HTML partial, Revealjs partial.

partial 포함

내장 partial을 자체 partial로 대체하는 것 외에도, 자신만의 템플릿을 구성할 때 내장 partial을 포함할 수 있습니다. 이렇게 하면 전체 템플릿 코드를 복사해 유지하지 않아도 Quarto와 Pandoc이 제공하는 기능과 옵션을 활용할 수 있습니다. 예를 들어 $pandoc.tex()$ partial을 사용하면 텍스트 하이라이팅, 표, 그래픽, 압축 리스트, 인용, 헤더 include에 대한 Pandoc 구성을 포함할 수 있습니다.

my-template.tex

\documentclass{scrartcl}
$pandoc.tex()$
\begin{document}
$body$
\end{document}

이 모듈식 접근은 다음과 같은 템플릿을 더 쉽게 구현할 수 있게 해줍니다.

Pandoc 템플릿의 필수 요소를 포함
일반적인 Pandoc 기능과 옵션을 지원
모든 LaTeX/HTML을 제공하는 대신 최소한의 내용만 제공

LaTeX partial

Note

format: beamer는 Beamer partial을 참고하세요.

Quarto LaTeX 템플릿과 partial의 소스 코드는 여기에서 확인할 수 있습니다.

Pandoc 3.6.3을 제공하는 Quarto 1.7부터 partial은 두 가지로 나뉩니다. Quarto 전용 partial과 Pandoc에서 상속된 partial입니다. 소스 디렉터리에는 다음이 포함됩니다.

Pandoc에서 상속된 .latex 확장자 partial
더 세밀한 커스터마이징을 위해 Quarto가 직접 제공하는 .tex 확장자 partial

template.tex: 기본 문서 뼈대와 아래의 partial을 포함하는 핵심 LaTeX 템플릿입니다. template-partial로 대체할 수는 없으며, 자체 템플릿을 제공하려면 template 옵션을 사용하세요.
passoptions.latex: 템플릿에서 이후 사용할 수 있는 패키지의 옵션을 변경하기 위해 \PassOptionsToPackage 명령을 사용하는 선언이 들어 있습니다.
doc-class.tex: 문서 클래스 선언과 옵션을 포함합니다. 기본적으로 Pandoc과 동일한 문서 클래스를 제공하며, 많은 기능을 구현합니다. 이를 재정의하는 경우(흔한 상황), 문서 클래스 옵션 지원을 직접 구현하거나 해당 옵션(예: font-size, paper-size, classoption 등)이 출력에서 지원되지 않을 수 있음을 알아야 합니다.
fonts.latex: 글꼴에 유용한 LaTeX 패키지를 로드하는 선언이 들어 있습니다.
font-settings.latex: 사용 중인 패키지와 LaTeX 엔진에 따라 글꼴 패키지를 구성하는 선언이 들어 있습니다.
common.latex: LaTeX용 Pandoc 기능(linestretch, indent, verbatim-in-note, listings 등) 관련 선언이 주로 포함됩니다. Quarto는 Pandoc 템플릿을 수정해 common.latex와 pandoc.tex 사이에 내용을 분리하고, 더 구체적인 partial을 사용합니다. 이 partial을 통째로 대체하거나 pandoc.tex의 더 구체적인 partial을 대체할 수 있습니다. 일반적으로 커스텀 템플릿에는 common.latex와 pandoc.tex partial이 항상 포함되어야 합니다.

pandoc.tex: 텍스트 하이라이팅, 표, 그래픽, 압축 리스트, 인용, 헤더 include 등 대부분의 Pandoc 기능을 위한 구성이 들어 있습니다. 일반적으로 이 partial은 커스텀 템플릿에 항상 포함되어야 합니다. 어떤 기능이 필요 없다는 것을 알고 있는 경우 이 partial은 아래의 partial들로 더 분해되어 있으므로, 적절하다면 그 partial들을 사용할 수 있습니다.

tables.tex: 표 출력, 표 캡션, 표 내 각주에 대한 구성을 제공합니다.
graphics.tex: 이미지 스케일링과 배치 구성을 제공합니다.
citations.tex: CSL 참고문헌을 사용할 때 참고문헌 출력을 위한 구성과 명령을 제공합니다.
babel-lang.tex: lang 옵션을 사용할 때 babel 지원 및 기타 언어 관련 LaTeX 구성을 위한 설정과 명령을 제공합니다.
tightlist.tex: 압축 리스트 명령을 제공합니다.
biblio-config.tex: natbib 또는 biblatex 구성을 제공합니다. 이러한 구성을 사용하지 않으려면(예: 특정 documentclass가 이미 처리하는 커스텀 포맷의 경우) 빈 partial을 제공하는 대신 문서 설정에 biblio-config: false를 사용하세요.

after-header-includes.latex: 사용자 지정 헤더 include 이후에 삽입되어야 하는 내용(예: 북마크 구성)이 들어 있습니다.
hypersetup.latex: \hypersetup 명령 구성이 들어 있습니다.
before-title.tex: 문서 프리앰블에서 제목 블록 바로 앞에 들어갑니다. 기본적으로 이 partial은 비어 있습니다.
title.tex: 제목 블록 작성을 위한 문서 메타데이터 구성을 제공합니다. 이 템플릿과 partial 외에도 Quarto는 정규화된 저자 및 소속 데이터를 템플릿에 제공하므로, 표준 스키마를 기반으로 커스텀 제목 블록을 쉽게 작성할 수 있습니다.
before-body.tex: 프론트매터, 제목 페이지, 초록을 구현합니다.
toc.tex: 목차, 그림 목록, 표 목록을 만듭니다.
before-bib.tex: 문서 본문 뒤, 참고문헌 앞에 배치됩니다. 기본적으로 내용은 없습니다.
biblio.tex: natbib 또는 biblatex를 사용하는 경우 참고문헌을 생성합니다.
after-body.tex: 본문 끝, \end{document} 직전에 내용을 붙일 수 있는 자리입니다.

Pandoc의 원본 파일 일부는 참고용으로 Quarto 소스에 보관되어 있습니다. 해당 파일은 모든 partial을 포함하는 template.tex의 기반이 되는 latex.template, 그리고 Quarto의 더 구체적인 partial을 지원하도록 조정된 common.latex의 원본 버전인 latex.common입니다.

이 partial들이 기본적으로 어떻게 호출되는지 보려면 Quarto LaTeX 템플릿의 전체 소스 코드를 확인하세요.

Beamer partial

Note

Quarto 1.7부터 format: beamer는 자체 템플릿과 partial을 사용합니다.

Quarto Beamer 템플릿과 partial의 소스 코드는 여기에서 확인할 수 있습니다.

Pandoc에서 상속된 .latex 확장자 partial
더 세밀한 커스터마이징을 위해 Quarto가 직접 제공하는 .tex 확장자 partial

template.tex: 기본 문서 뼈대와 아래의 partial을 포함하는 핵심 LaTeX 템플릿입니다. template-partial로 대체할 수는 없으며, 자체 템플릿을 제공하려면 template 옵션을 사용하세요.
passoptions.latex: 템플릿에서 이후 사용할 수 있는 패키지의 옵션을 변경하기 위해 \PassOptionsToPackage 명령을 사용하는 선언이 들어 있습니다.
doc-class.tex: 문서 클래스 선언과 옵션을 포함합니다. 기본적으로 Pandoc과 동일한 문서 클래스를 제공하며, 많은 기능을 구현합니다. 이를 재정의하는 경우(흔한 상황), 문서 클래스 옵션 지원을 직접 구현하거나 해당 옵션(예: font-size, paper-size, classoption 등)이 출력에서 지원되지 않을 수 있음을 알아야 합니다.
fonts.latex: 글꼴에 유용한 LaTeX 패키지를 로드하는 선언이 들어 있습니다.
font-settings.latex: 사용 중인 패키지와 LaTeX 엔진에 따라 글꼴 패키지를 구성하는 선언이 들어 있습니다.
common.latex: LaTeX용 Pandoc 기능(linestretch, indent, verbatim-in-note, listings 등) 관련 선언이 주로 포함됩니다. Quarto는 Pandoc 템플릿을 수정해 common.latex와 pandoc.tex 사이에 내용을 분리하고, 더 구체적인 partial을 사용합니다. 이 partial을 통째로 대체하거나 pandoc.tex의 더 구체적인 partial을 대체할 수 있습니다. 일반적으로 커스텀 템플릿에는 common.latex와 pandoc.tex partial이 항상 포함되어야 합니다.

pandoc.tex: 텍스트 하이라이팅, 표, 그래픽, 압축 리스트, 인용, 헤더 include 등 대부분의 Pandoc 기능을 위한 구성이 들어 있습니다. 일반적으로 이 partial은 커스텀 템플릿에 항상 포함되어야 합니다. 어떤 기능이 필요 없다는 것을 알고 있는 경우 이 partial은 아래의 partial들로 더 분해되어 있으므로, 적절하다면 그 partial들을 사용할 수 있습니다.

tables.tex: 표 출력, 표 캡션, 표 내 각주에 대한 구성을 제공합니다.
graphics.tex: 이미지 스케일링과 배치 구성을 제공합니다.
citations.tex: CSL 참고문헌을 사용할 때 참고문헌 출력을 위한 구성과 명령을 제공합니다.
babel-lang.tex: lang 옵션을 사용할 때 babel 지원 및 기타 언어 관련 LaTeX 구성을 위한 설정과 명령을 제공합니다.
tightlist.tex: 압축 리스트 명령을 제공합니다.
biblio-config.tex: natbib 또는 biblatex 구성을 제공합니다. 이러한 구성을 사용하지 않으려면(예: 특정 documentclass가 이미 처리하는 커스텀 포맷의 경우) 빈 partial을 제공하는 대신 문서 설정에 biblio-config: false를 사용하세요.

after-header-includes.latex: 사용자 지정 헤더 include 이후에 삽입되어야 하는 내용(예: 북마크 구성)이 들어 있습니다.
hypersetup.latex: \hypersetup 명령 구성이 들어 있습니다.
before-title.tex: 문서 프리앰블에서 제목 블록 바로 앞에 들어갑니다. 기본적으로 이 partial은 비어 있습니다.
title.tex: 제목 블록 작성을 위한 문서 메타데이터 구성을 제공합니다. 이 템플릿과 partial 외에도 Quarto는 정규화된 저자 및 소속 데이터를 템플릿에 제공하므로, 표준 스키마를 기반으로 커스텀 제목 블록을 쉽게 작성할 수 있습니다.
before-body.tex: 프론트매터, 제목 페이지, 초록을 구현합니다.
toc.tex: 목차, 그림 목록, 표 목록을 만듭니다.
before-bib.tex: 문서 본문 뒤, 참고문헌 앞에 배치됩니다. 기본적으로 내용은 없습니다.
biblio.tex: natbib 또는 biblatex를 사용하는 경우 참고문헌을 생성합니다.
after-body.tex: 본문 끝, \end{document} 직전에 내용을 붙일 수 있는 자리입니다.

Pandoc의 원본 파일 일부는 참고용으로 Quarto 소스에 보관되어 있습니다. 해당 파일은 모든 partial을 포함하는 template.tex의 기반이 되는 beamer.template, 그리고 Quarto의 더 구체적인 partial을 지원하도록 조정된 common.latex의 원본 버전인 latex.common입니다.

이 partial들이 기본적으로 어떻게 호출되는지 보려면 Quarto Beamer 템플릿의 전체 소스 코드를 확인하세요.

Typst partial

Quarto Typst 템플릿과 partial의 소스 코드는 여기에서 확인할 수 있습니다.

template.typ: 기본 문서 뼈대와 아래의 partial을 포함하는 핵심 Typst 템플릿 파일입니다. partial로 대체할 수는 없으며, 자체 템플릿을 제공하려면 template 옵션을 사용하세요.
definitions.typ: 인용 블록, callout, subfloat 등 Pandoc/Quarto 기능을 위한 정의가 들어 있습니다. 일반적으로 이 partial은 커스텀 템플릿에 항상 포함되어야 합니다.
typst-template.typ: 문서 전체에 적용되는 Typst 템플릿 함수 정의입니다. 기본 템플릿에서는 이 함수가 article()로 정의되어 제목 블록과 저자 목록을 만들고, 이어서 문서 내용을 생성하며, 필요에 따라 컬럼 레이아웃을 적용합니다.
page.typ: 페이지 크기, 여백, 페이지 번호, 배경 로고 등의 속성을 설정합니다.
typst-show.typ: 문서 전체에 적용되는 show 규칙으로, 문서 메타데이터를 캡처해 typst-template.typ에 정의된 함수로 전달합니다.
notes.typ: 각주를 생성합니다.
biblio.typ: 참고문헌을 생성합니다.

HTML partial

Quarto html 템플릿과 partial의 소스 코드는 여기에서 확인할 수 있습니다. html.template은 Quarto 템플릿과 partial이 기반으로 삼는 Pandoc 전체 템플릿의 복사본입니다.

Quarto의 HTML 템플릿은 다음 구성 요소로 나뉩니다.

template.html: 기본 문서 뼈대와 아래의 partial을 포함하는 핵심 HTML 템플릿입니다. partial로 대체할 수는 없으며, 자체 템플릿을 제공하려면 template 옵션을 사용하세요.
metadata.html: 기본 문서 메타데이터를 HTML 문서 head에 채웁니다. 더 고급 메타데이터 요소(예: 소셜 미디어, 학술 메타데이터)는 이 템플릿에 구현되어 있지 않지만 후처리기로 구현됩니다.
title-block.html: 문서의 제목 블록을 제공합니다.
toc.html: 문서의 목차 위치를 제공합니다.

Revealjs partial

Quarto Revealjs 템플릿과 partial의 소스 코드는 여기에서 확인할 수 있습니다. revealjs.template은 Quarto 템플릿과 partial이 기반으로 삼는 Pandoc 전체 템플릿의 복사본입니다.

template.html: 기본 프레젠테이션 뼈대와 아래의 partial을 포함하는 핵심 Revealjs 템플릿입니다. partial로 대체할 수는 없으며, 자체 템플릿을 제공하려면 template 옵션을 사용하세요.
title-slide.html: 프레젠테이션 제목 슬라이드에 사용하는 HTML입니다. 기본적으로 Quarto는 저자 및 소속 처리를 활용하는 화려한 title-slide.html partial을 사용합니다. 이 partial을 수정하려면 title-slide.html 소스 코드를 시작점으로 삼으세요.
toc-slide.html: 프레젠테이션 목차에 사용하는 HTML입니다.