Typst 기본

개요

Typst는 LaTeX만큼 강력하면서도 배우고 사용하기 훨씬 쉬운 오픈 소스 마크업 기반 조판 시스템입니다. Typst는 매우 빠른 렌더링 속도로 아름다운 PDF 출력을 생성합니다.

Typst로 PDF 문서를 만들려면 typst 형식을 사용하세요. 예:

hello-typst.qmd
---
title: "Hello Typst!"
format:
  typst:
    toc: true
    section-numbering: 1.1.a
    columns: 2
---

이 문서를 렌더링하거나 미리보면 Typst CLI가 호출되어 마크다운 소스 파일로부터 PDF 파일인 hello-typst.pdf가 생성됩니다. Quarto에는 Typst CLI가 포함되어 있어 별도의 Typst 설치가 필요하지 않습니다.

위 예시는 Typst 출력에 사용할 수 있는 몇 가지 옵션을 보여줍니다. 이 문서는 이러한 옵션과 다른 옵션을 자세히 설명합니다. 사용 가능한 전체 옵션 목록은 Typst 형식 참조를 참고하세요.

Typst의 큰 장점 중 하나는 고도로 사용자 지정된 템플릿을 쉽게 만들 수 있다는 점입니다. 예를 들어 다음 Typst 템플릿은 Quarto에서 사용자 정의 형식으로 사용할 수 있습니다:

IEEE 표준에 따라 스타일이 적용된 기사 페이지 스크린샷. 제목은 중앙에 있고 저자는 아래에 두 열로 배치됨.

IEEE

가로 방향 포스터 스크린샷. 오른쪽 상단에 로고, 왼쪽 상단에 제목이 있으며 콘텐츠가 세 열로 배치됨.

Poster

편지 페이지 스크린샷. 페이지 상단에 발신자 주소가 있고, 그 아래에 수신자 주소가 왼쪽 정렬로 배치됨. 편지 본문에는 굵은 제목 줄이 포함됨.

Letter

학과 뉴스레터 페이지 스크린샷. 페이지가 세로로 분할되어 왼쪽은 흰색, 오른쪽은 빨간색 열로 구성됨. 이미지가 열을 가로지르며 "Award Winning Science" 텍스트가 오른쪽에서 세로로 내려옴.

Dept News

사용 방법과 직접 만드는 방법은 사용자 정의 형식에서 더 알아보세요.

알려진 제한 사항

Typst는 활발히 개발 중이므로 Quarto의 Typst 지원에는 아직 몇 가지 제한이 있습니다:

  • 이미지 기본 크기가 다른 출력 형식에서 익숙한 동작과 다를 수 있습니다. 이는 Typst, pandoc, Quarto가 적극적으로 해결 중인 문제입니다. 그동안은 이미지 너비 지정을 수동으로 사용할 수 있습니다.

  • 고급 페이지 레이아웃(예: Article 레이아웃에서 설명한 .column-* 클래스 사용)은 구현되어 있지 않습니다.

  • 그 밖의 작은 기능들이 아직 구현되지 않았을 수 있습니다. 개선할 점이 보이면 알려주세요!

페이지 레이아웃

페이지 크기(papersize), 페이지 여백(margin), 페이지 콘텐츠에 사용할 열 수(columns)를 제어할 수 있습니다. 예를 들어 다음 YAML은 세 옵션을 모두 변경합니다:

---
title: Page Layout
format:
  typst:
    papersize: a5
    margin:
      x: 1cm
      y: 1cm
    columns: 2
---

결과 레이아웃은 아래에서 기본 레이아웃 예시와 함께 보여집니다:

PDF 문서 한 페이지 스크린샷. 문서에 두 열의 텍스트가 표시됨. 이전 스크린샷에 비해 페이지가 더 좁고 길며 여백이 더 작음.

사용자 정의 레이아웃

PDF 문서 한 페이지 스크린샷. 문서에 단일 열 텍스트가 표시됨.

기본 레이아웃

이러한 페이지 레이아웃 옵션은 아래 섹션에서 더 자세히 설명합니다.

용지 크기

papersize 옵션은 Typst가 지원하는 용지 크기 중 하나에 해당하는 문자열을 기대합니다. 기본 템플릿은 다음과 같습니다:

papersize: us-letter

여백

margin 옵션은 x, y, top, bottom, left, right 중 하나 이상을 하위 옵션으로 기대합니다. 기본 템플릿의 여백은 다음과 같습니다:

margin:
  x: 1.25in
  y: 1.25in

이는 수평 방향(x), 즉 left와 right의 여백과 수직 방향(y), 즉 top과 bottom의 여백을 각각 1.25인치로 설정합니다.

여백 값은 Typst의 길이 타입(예: 5cm) 또는 상대 길이 타입(예: 10%)으로 지정합니다. 단일 여백을 지정할 수도 있습니다:

margin:
  left: 1cm

그러면 지정되지 않은 여백은 기본 여백을 상속합니다.

열

columns 옵션은 본문 콘텐츠의 열 수를 나타내는 숫자를 기대합니다. 기본 템플릿은 columns를 1로 설정합니다.

목차

toc 옵션을 사용하면 출력 문서에 자동 생성된 목차가 포함됩니다. toc-depth 옵션으로 목차에 포함할 섹션 수준을 지정할 수 있습니다. 기본값은 3이며(즉, 1, 2, 3단계 제목이 목차에 표시됩니다) 예시는 다음과 같습니다.

toc: true
toc-depth: 2

toc-title 옵션으로 목차 제목을 사용자 지정할 수 있습니다.

toc-title: Contents

목차에서 특정 제목을 제외하려면 .unnumbered와 .unlisted 클래스를 모두 추가합니다.

### More Options {.unnumbered .unlisted}

toc-indent 옵션은 표시된 목차에서 항목의 들여쓰기를 제어합니다. 기본값은 다음과 같습니다:

toc-indent: 1.5em

섹션 번호

number-sections 옵션을 사용하면 출력 문서의 섹션 제목에 번호가 붙습니다. 예:

number-sections: true

number-depth 옵션으로 번호를 붙일 가장 깊은 제목 수준을 지정할 수 있습니다(기본값은 모든 제목에 번호가 붙음). 예:

number-depth: 3

개별 제목에 번호를 붙이지 않으려면 .unnumbered 클래스를 추가합니다.

### More Options {.unnumbered}

section-numbering YAML 옵션으로 절 번호 표시를 사용자 지정할 수도 있습니다. 이 옵션은 번호 체계를 설명하는 문자열을 기대합니다. 예를 들어 다음 체계는 .를 구분자로 사용하여 섹션은 숫자, 하위 섹션은 대문자, 하위-하위 섹션은 소문자로 번호를 매깁니다:

---
section-numbering: 1.A.a
---

번호 체계를 지정하는 방법은 Typst 번호 매기기 문서를 참고하세요.

코드 주석

코드 블록과 실행 코드 셀의 코드 줄에 주석을 추가할 수 있습니다. 자세한 내용은 Code Annotation을 참고하세요.

참고문헌

Typst에는 참고문헌을 위한 자체 인용 처리 시스템이 있으며 format: typst를 사용하면 기본값으로 이를 사용합니다. Typst 시스템으로 참고문헌 스타일을 지정하려면 bibliographystyle 옵션을 사용하세요. Typst의 내장 스타일 목록에서 문자열을 제공하면 됩니다. 예:

bibliography: refs.bib
bibliographystyle: apa

또는 로컬 CSL 파일 경로를 제공할 수 있습니다:

bibliography: refs.bib
bibliographystyle: my-csl-style.csl

Pandoc의 인용 처리를 사용하려면 YAML 헤더에 citeproc: true를 명시적으로 설정하세요:

citeproc: true
bibliography: refs.bib
csl: https://www.zotero.org/styles/apa-with-abstract

Pandoc 인용 처리 시스템에 인용 스타일 파일을 제공하려면 Citation Style에서 설명한 csl 옵션을 사용하세요.

Typst 블록

네이티브 Typst #block() 호출로 블록 모양을 바꾸려면 Div에 .block 클래스를 추가하고 적절한 인자를 제공하면 됩니다. 예:

::: {.block fill="luma(230)" inset="8pt" radius="4pt"}

This is a block with gray background and slightly rounded corners.

:::

이는 다음으로 컴파일됩니다

#block(fill:luma(230), inset:8pt, radius:4pt,
[This is a block with gray background and slightly rounded corners.])

Raw Typst

원시 typst 마크업을 사용하려면 raw typst 블록을 사용하세요. 예:

```{=typst} 
#set par(justify: true)

== Background 
In the case of glaciers, fluid dynamics principles can be used to understand how the movement and behavior of the ice is influenced by factors such as temperature, pressure, and the presence of other fluids (such as water).
```

typst 마크업에 대해 더 알아보려면 다음 튜토리얼을 참고하세요: https://typst.app/docs/tutorial/.

Typst CSS

HTML과 Typst 간 유사한 스타일링을 위해 Quarto는 CSS 속성을 Typst 속성으로 변환합니다.

Quarto 마크업에서 CSS 속성을 직접 사용할 수 있으며, 이는 적절한 Typst 요소와 속성으로 변환됩니다.

예를 들어 텍스트 관련 속성 color, opacity, background-color는 span에 적용할 수 있습니다:

Here is a [span with a green background]{style="background-color:green"}.

font-family와 font-size는 div나 표에 적용할 수 있습니다:

:::{style="font-family: helvetica"}
이 div는 Helvetica로 렌더링됩니다.
:::

지원되는 요소와 속성, 그리고 Lua 필터로 더 추가하는 방법은 고급 문서를 참고하세요.

HTML 표를 생성하는 라이브러리를 사용할 때 Typst CSS를 가장 자주 접할 것입니다. CSS 변환 덕분에 별도의 작업 없이 Typst의 표가 HTML에서 보이는 것과 비슷하게 표시됩니다.

예를 들어, R의 gt와 Python의 pandas를 사용한 온도 히트맵은 다음과 같습니다.

```{r}
library(gt)
temps <- data.frame(
  year = c(1920:1924),
  Jan = c(40.6, 44.2, 37.5, 41.8, 39.3), 
  Jun = c(58.5, 58.7, 57.8, 52.7, 57.7)
)
temps |>
  gt() |> 
  data_color(
    columns = c(-year),
    fn = scales::col_numeric(
      colorspace::diverge_hcl(n = 9,
        palette = "Green-Orange"),
      domain = c(35, 62))
  )

```

```{python}
import pandas as pd
import numpy as np

temps = pd.DataFrame({
  'year': [*range(1920, 1925)],
  'Jan': [40.6, 44.2, 37.5, 41.8, 39.3], 
  'Jun': [58.5, 58.7, 57.8, 52.7, 57.7]
}).set_index('year')

def make_pretty(styler):
  styler.background_gradient(axis=None,
    vmin=31, vmax=66, cmap="RdYlGn_r")
  return styler

temps.style.pipe(make_pretty)

```

Typst 이름 색상은 CSS 이름 색상보다 우선됩니다. HTML과 Typst 출력에서 정확히 같은 색을 원한다면 rgb() 또는 16진수 #rrggbb 문법으로 색상을 지정하세요.

Typst는 필터로서의 opacity를 지원하지 않으므로, 색상의 알파 채널을 사용해 투명도를 시뮬레이션합니다.

Typst 파일(.typ)

렌더링 과정에서 네이티브 Typst 파일(.typ))이 생성되고, Typst CLI로 PDF로 컴파일됩니다. 이 중간 파일은 자동으로 제거됩니다. .typ 파일을 보존하려면 keep-typ 옵션을 사용하세요. 예:

---
title: "My Document"
format:
  typst:
    keep-typ: true
---

터미널에서 quarto typst compile 명령으로 .typ 파일을 PDF로 직접 컴파일할 수 있습니다. 예:

Terminal
$ quarto typst compile article.typ

quarto typst 명령은 Quarto에 내장된 Typst 버전을 사용하며 Typst CLI의 모든 동작과 플래그를 지원합니다. 예를 들어 Quarto에 내장된 Typst 버전을 확인하려면:

Terminal
$ quarto typst --version

글꼴 지원

문서에 사용할 기본 글꼴은 mainfont YAML 옵션으로 지정할 수 있습니다. Typst는 기본적으로 설치된 시스템 글꼴에서 검색합니다. font-paths로 추가 검색 경로를 지정할 수 있습니다. 예:

---
title: "My Document"
format: 
  typst:
    mainfont: "Agbalumo"
    font-paths: myfonts
---

이는 설치된 시스템 글꼴 검색에 더해 ./myfonts/ 디렉터리에서 글꼴 이름과 일치하는 *.ttf 또는 *.otf 파일을 찾습니다.

Typst 설정과의 호환성을 위해 TYPST_FONT_PATHS 환경 변수도 고려되지만, font-paths를 설정하면 TYPST_FONT_PATHS에 설정된 경로보다 우선합니다.

fontsize로 문서에서 사용하는 글꼴의 기본 크기를 설정합니다. 기본 템플릿에서 사용하는 크기는 다음과 같습니다:

---
fontsize: 11pt
---

로고 위치

brand.yml에서 가져온 로고나 문서에 직접 지정한 로고가 있으면, Quarto의 Typst 구현은 문서(또는 프로젝트)에서 로고 위치를 사용자 지정할 수 있게 합니다:

document.qmd
---
format:
  typst:
    logo:
      width: 1in
      location: right-top
      padding-right: 0.5in
      padding-top: 0.25in
      alt: Alternate alternate text
---
옵션 | 설명 |
width CSS 단위로 지정한 너비. 기본값 1.5in.
location 페이지의 위치를 X-Y로 지정합니다. X는 left, center, right, Y는 top, middle, bottom입니다. | Typst align로 적용됩니다.
padding, padding-top, padding-right, padding-bottom, padding-left CSS padding 규칙에 따라 로고 각 면에 추가할 패딩 크기입니다.| 패딩 옵션은 알파벳 순으로 적용됩니다. | Typst block.inset으로 적용됩니다. 기본값 padding: 0.75in. |

계산 그림 형식

Typst는 SVG 그래픽을 잘 지원하므로 format: typst의 기본값은 fig-format: svg입니다. 이 설정은 이미지가 생성되는 실행 코드 셀이 .svg 출력을 만든다는 뜻입니다.

래스터 그래픽을 포함하고 싶다면 fig-format을 다른 값으로 설정하세요. 예:

format:
  typst:
    fig-format: png

다른 그림 옵션은 Typst 참조 페이지를 참고하세요.

포함

다른 파일의 추가 콘텐츠를 문서에 포함하려면 include-in-* 옵션을 사용할 수 있습니다.

옵션 설명
include-in-header 헤더 끝에 file의 내용을 그대로 포함합니다. 예를 들어 HTML 문서에 특수 CSS/JavaScript를 포함하거나 LaTeX 프리앰블에 명령을 삽입하는 데 사용할 수 있습니다.
include-before-body 문서 본문 시작 부분에 file의 내용을 그대로 포함합니다(HTML에서는 <body> 태그 뒤, LaTeX에서는 \begin{document} 뒤). HTML 문서에 내비게이션 바나 배너를 넣는 데 사용할 수 있습니다.
include-after-body 문서 본문 끝에 file의 내용을 그대로 포함합니다(HTML에서는 </body> 태그 앞, LaTeX에서는 \end{document} 앞).

각 옵션에 대해 파일 하나 또는 여러 파일을 직접 지정하거나 file: 하위 키를 사용할 수 있습니다. YAML 헤더에 원시 콘텐츠를 포함하려면 text 하위 키를 사용하세요. text:를 사용할 때는 text: 뒤에 | 문자를 추가해 다중 줄 문자열임을 나타냅니다. file:이나 text:를 생략하면 Quarto는 파일을 제공하는 것으로 간주합니다.

예:

format:
  typst:
    include-before-body:
      - text: |
          #show heading: set text(navy)