typst은(는) 무엇을 하나요?
Typst는 내장 스크립트 언어를 갖춘 마크업 기반 조판 시스템입니다. 하나의 바이너리가 .typ 파일을 PDF(기본값), PNG, SVG, HTML(실험적) 또는 멀티파일 번들(실험적)로 컴파일합니다. 이 스킬은 Typst 0.15.x (0.15.1에서 검증)를 대상으로 합니다. 이전 버전과 다른 동작은 별도로 표시합니다.
Typst에 대한 학습 데이터는 종종 오래되었습니다(0.11–0.13 시대). 함수, 매개변수 또는 기본값이 확실하지 않으면
references/api-signatures.md를 확인한 다음, 추측 대신 프로브를 컴파일하세요 (typst eval '<expr>'또는 5줄 파일).
워크플로우
- 출력물을 명확히 하세요: PDF(기본값), HTML, PNG/SVG, 접근성 PDF(PDF/UA), 아카이브 PDF(PDF/A)? 페이지 크기, 언어, 글꼴, 인용 스타일, 템플릿/저널?
- 스켈레톤(아래) 또는
examples/에서 시작하세요. 저널/학위 논문/이력서/슬라이드 데크의 경우 먼저 패키지를 검색하세요:python3 scripts/search-packages.py "ieee paper"(references/packages-and-ecosystem.md참조). - 파일을 작성하세요:
set/show규칙과 임포트를 맨 위에, 내용은 아래에 배치하세요. 큰 프로젝트는#include와#import로 분할하세요. - 컴파일하고 확인하세요:
typst compile main.typ— 진단 메시지를 읽으세요(줄:열과 힌트가 있습니다). PNG로 시각적 확인(typst compile main.typ 'p-{p}.png'), 또는 텍스트로 확인(typst compile main.typ - -f html --features html/pdftotext)하세요. 자세한 내용은references/pitfalls-and-debugging.md를 참조하세요. - 포맷(가능한 경우):
typstyle -i file.typ. 자기 편집 부분만 차이가 있을 때만 사용하세요. - 생성/변경된 파일과 재빌드 방법을 보고하세요.
최소 스켈레톤
#set document(title: "내 문서", author: "이름")
#set page(paper: "a4", margin: 2.5cm, numbering: "1")
#set text(font: "New Computer Modern", size: 11pt, lang: "ko")
#set par(justify: true, leading: 0.65em)
#set heading(numbering: "1.1")
#title()
= 소개 <intro>
Typst는 *굵게*, _기울임_, `raw`, 수식 $E = m c^2$ 및 @intro와 같은 참조를 지원합니다.
== 하위 절
#lorem(30)
$ integral_0^1 x^2 dif x = 1/3 $
항상 안전한 기본값: #set text(lang: "...") (하이픈, 따옴표, 보충, 접근성), #set document(title: ...) + #title() (보이는 제목), #set par(justify: true) (본문 텍스트).
60초 구문
| 모드 | 입력 방법 | 예시 |
|---|---|---|
| 마크업(기본값) | — | = 제목, *굵게*, _기울임_, - 항목, + 번호, / 용어: 설명, @레이블, <레이블> |
| 코드 | # (하나의 표현식) 또는 #{ ... } 블록 | #let x = 3, #f(1)[본문], #if a [예] else [아니오], #for i in range(3) [#i ] |
| 수학 | $...$ ($ x $ 공백 포함 = display) | $a^2 + b_i$, $sum_(i=1)^n i$, $ vec(1, 2) $ |
| 콘텐츠 블록 | 코드 내 [...] | #box[안녕], let c = [*x*] |
- 코드 내에서는
#을 반복하지 마세요:#figure(image("a.png"), caption: [안녕]).[...]콘텐츠 블록 안에서는 다시 마크업 모드입니다:[합계: #x]. - 배열
(1, 2), 딕셔너리(a: 1, b: 2), 빈()/(:), 하나의 요소(1,). 튜플은 없습니다. 인덱스는[i]대신.at(i)로 접근하세요. - 명명된 인수는
:를 사용합니다(f(width: 2cm));=는let/코드 내에서만 할당입니다. - 문자열
"...", 콘텐츠[...], 원시`...`. 다음을 사용하여 변환:str(x),[#s],eval(s, mode: "markup"). - 주석:
// 줄,/* 블록 */. 특수 문자는\로 이스케이프(\#,\$,\@,\*,\_,\<); 유니코드\u{1F600}. - 길이 단위:
pt mm cm in em,fr(분수),%, 각도deg rad.auto와none은 값입니다. set= 지금부터 요소에 대한 기본 인수;show= 요소 재스타일/교체. 스타일/카운터/위치를 읽으려면context가 필요합니다(references/introspection.md참조).- 경로: 슬래시만 사용(0.15).
"/x.typ"는 프로젝트 루트 기준(기본 루트: 메인 파일의 디렉토리;--root로 변경),"x.typ"는 현재 파일 기준. - 모든 곳에서 메서드 구문 사용:
"abc".len(),(1,2,3).map(x => x*2),rgb("#f00").lighten(30%).
참고 자료
| 필요할 때 | 읽을 자료 |
|---|---|
구문, 타입, 연산자, 문자열/배열/딕셔너리 메서드, 모듈, 클로저, context 기본 | references/syntax-and-scripting.md |
set/show 규칙, 선택자, 페이지 설정, 텍스트, 단락, 블록, 그리드, 컬럼, 정렬, 간격, 배치, 변환 | references/styling-and-layout.md |
| 제목, 목록, 그림, 표, 참조, 각주, 개요, 인용구, 서지/인용/CSL, 번호 매기기, 링크, 메타데이터 | references/document-model.md |
| 방정식, 수학 구문, 기호, 행렬, 정렬, 글꼴, 번호 매기기 | references/math.md |
| 도형, 곡선, 이미지, 색상, 그라데이션, 타일링, 선, 스팟 컬러 | references/visuals.md |
카운터, 상태, query, locate, metadata, within, 레이아웃 수렴, 실행 헤더, measure/layout | references/introspection.md |
CSV/JSON/YAML/TOML/XML/CBOR, read, bytes, sys.inputs, eval, WASM 플러그인, 데이터 기반 문서 | references/data-and-io.md |
CLI 플래그, 글꼴, PDF/A/UA, 접근성, HTML, 번들, PNG/SVG, typst eval, CI/재현 가능한 빌드 | references/export-and-cli.md |
| 슬라이드 데크(Touying/Polylux, 애니메이션, 유인물, 발표자 노트, pdfpc) | references/slides.md |
템플릿, typst.toml, 패키지 게시, Universe 패키지 추천(cetz, fletcher, touying, codly, ...), 에디터 도구 | references/templates-and-packages.md, references/packages-and-ecosystem.md |
| LaTeX → Typst 변환, Markdown/pandoc 변환, 0.11–0.14에서 업그레이드 | references/migration.md |
| 오류, 경고, 프로브, 시각적 확인, 성능, 일반적인 함정 | references/pitfalls-and-debugging.md |
| 모든 요소의 정확한 매개변수/기본값(0.15.1 소스에서 검증) | references/api-signatures.md |
| 즉시 컴파일 가능한 시작 파일 | examples/*.typ |
주요 함정 (작성 전에 읽으세요)
- Set/show 규칙은 전방향으로 적용되며 해당 범위 내에서만 적용됩니다; 영향을 주려는 콘텐츠 앞에 배치하세요.
[...]/{...}내부의set은 블록과 함께 종료됩니다. - 위치/스타일에 의존하는 것을 읽으려면
context가 필요합니다:#context counter(page).get(),#context text.size. 없으면: "컨텍스트를 알 수 있을 때만 사용할 수 있습니다". - 클로저에 캡처된 변수는 읽기 전용 복사본입니다;
fold, 단일 코드 블록의 루프,state또는counter를 통해 누적하세요. #은 한 번만 필요합니다; 마크업에서 연산자가 포함된 표현식은#(a + b);#f(x).g는 작동하지만#f (x)(공백)는 호출되지 않습니다.- 수학은 텍스트가 아닙니다: 여러 글자 단어는 기호/변수입니다(
alpha,sin); 텍스트는"text"또는upright(...)로 작성하세요. 단일 문자는 기울임꼴 변수입니다. - 문자열은 콘텐츠가 아닙니다: 제목 본문은 콘텐츠입니다; 텍스트를 얻으려면
.body,str()또는 도우미to-string(구문 참조 참조)을 사용하세요. - 글꼴: 설치/내장/
--font-path글꼴만 작동합니다; 알 수 없는 패밀리는 경고만 하고 대체됩니다.typst fonts로 목록을 확인하세요. 가변 글꼴의 경우 이름에서 "Variable"/"VF"를 생략하세요(0.15). - 패키지는 정확한 버전으로 임포트됩니다:
#import "@preview/cetz:0.5.3"— 최신 버전은 메모리보다 Typst Universe에서 확인하세요(scripts/search-packages.py). 패키지는 새 컴파일러보다 늦게 업데이트될 수 있습니다. - 0.15에서 제거된 것:
path()→curve(),pattern→tiling,pdf.embed→pdf.attach,*.decode(...)→bytes를json(...)등에 전달,typst query→typst eval, 경로에 백슬래시 없음. - HTML/번들 내보내기는 실험적이며
--features html/--features bundle이 필요합니다.
빠른 관용구
// 재사용 가능한 템플릿: show 규칙과 함수
#let conf(title: none, authors: (), body) = {
set page(margin: 2cm)
set par(justify: true)
align(center, text(17pt, weight: "bold", title))
v(1em)
body
}
#show: conf.with(title: [내 논문])
// 하나의 제목 레벨 스타일링
#show heading.where(level: 1): set text(navy)
#show heading.where(level: 1): it => block(above: 1.5em, below: 1em, it)
// 상호 참조 및 그림
#figure(table(columns: 2, [A], [B], [1], [2]), caption: [데이터]) <tab:data>
@tab:data를 참조하세요.
// 데이터 기반 콘텐츠
#for (name, score) in (("Ann", 3), ("Bo", 5)) [- #name: #score]
// CLI에서 런타임 입력: typst compile --input mode=draft main.typ
#let draft = sys.inputs.at("mode", default: "최종") == "초안"
컴파일 치트시트
typst compile main.typ # → main.pdf
typst compile main.typ out.pdf --root .
typst compile main.typ 'page-{0p}.png' --ppi 144
typst watch main.typ # 변경 시 재컴파일
typst eval 'calc.pow(2, 10)' # 표현식 평가, JSON 출력
typst eval --in main.typ 'query(heading).len()'
typst init @preview/charged-ieee # 템플릿에서 새 프로젝트 생성
typst fonts --variants # 설치된 글꼴
예제 (모두 0.15.1에서 컴파일)
| 파일 | 설명 |
|---|---|
examples/memo.typ | 짧은 메모, 헤더 그리드, 간단한 스타일링 |
examples/report.typ | 제목 페이지, 개요, 실행 헤더, 그림/표/각주, show 규칙 |
examples/academic-paper.typ (+ refs.bib) | 방정식, 정리 환경, 상호 참조, 인용 |
examples/data-report.typ (+ data.csv) | CSV → 표, 계산된 열, --input, 단순 도형 막대 차트 |
examples/template.typ + template-usage.typ | 재사용 가능한 템플릿 함수 + 컴포넌트 |
examples/accessible.typ | PDF/A-2a + PDF/UA-1 (--pdf-standard a-2a,ua-1) |
examples/dual-target.typ | 하나의 소스 → PDF 및 HTML (context target(), html.*) |
examples/query-export.typ | metadata + typst eval 구조 내보내기 |
examples/slides-plain.typ, examples/letter.typ | 패키지 없는 슬라이드 및 공식 편지 |
examples/packages-demo.typ | cetz, fletcher, lilaq, theorion, codly (고정, 검증된 버전) |
스크립트
scripts/check-snippets.py FILE.md…—```typ블록을 모두 컴파일합니다(설명/비컴파일 블록은```typ-x사용). Typst가 포함된 Markdown을 작성할 때 실행하세요.scripts/search-packages.py "키워드" [--category cv] [--name cetz --versions]— Typst Universe 인덱스에서 현재 패키지 이름/버전을 조회합니다.