Typst 프로젝트
프로젝트마다 Typst 버전을 고정하고, Typst Universe에서 패키지를 추가하고, 글꼴, 빌드 변형, 재현 가능한 PDF를 관리하고, LaTeX 프로젝트를 Typst로 변환합니다.
Oleafly에는 Typst 0.15.1과 Tinymist 0.15.8 언어 서버가 들어 있으므로 새 Typst 프로젝트는 아무것도 설치하지 않고 컴파일됩니다. 이 페이지는 바꿀 수 있는 것을 다룹니다. 프로젝트가 어떤 Typst를 쓰는지, 패키지와 글꼴을 어디서 가져오는지, 소스 하나로 여러 PDF를 빌드하는 방법입니다. 문법과 툴바는 Typst로 쓰기부터 보세요.
Typst 버전
섹션 제목: “Typst 버전”설정 → 엔진 → Typst를 엽니다. 첫 번째 카드는 앱에 들어 있는 버전인 Typst(내장) 입니다. 컴퓨터에 이미 typst가 설치되어 있고 PATH, Homebrew 폴더 또는 ~/.cargo/bin에 있다면 두 번째 카드에 이 컴퓨터의 Typst로 표시됩니다. 정확히 그 버전을 고정한 프로젝트는 그것으로 컴파일할 수 있습니다.
그 아래 버전에는 Typst 0.11부터 0.15까지 최신순으로 나열됩니다. 각 줄에는 출시일, 다운로드 크기, 사본의 출처(내장, 다운로드됨 또는 시스템), 그리고 설치된 뒤에는 그 버전이 쓰는 Tinymist 릴리스가 나옵니다.
- 설치는 그 버전을 내려받습니다. Oleafly는 자체 미러를 먼저, GitHub를 그다음으로 시도하고, 압축 파일과 그 안의 프로그램을 앱에 들어 있는 SHA-256 체크섬과 대조합니다. 일치하지 않는 파일은 버려지며, 실패하거나 취소한 설치는 아무것도 남기지 않습니다. 다운로드는
~/.oleafly/toolchains/typst/에 저장됩니다. - 설치된 줄 왼쪽의 둥근 버튼은 그 버전을 기본값으로 만듭니다.
- 제거는 내려받은 버전을 삭제합니다. 기본값은 제거할 수 없으므로 먼저 다른 기본값을 고르세요.
기본 버전과 프로젝트 고정
섹션 제목: “기본 버전과 프로젝트 고정”새 Typst 프로젝트는 기본 버전으로 고정됩니다. 템플릿으로 만든 프로젝트, 가져온 프로젝트, 연결된 폴더도 마찬가지입니다. 고정은 경로가 아니라 버전 번호로 프로젝트의 project.json에 저장되므로, 프로젝트를 옮기거나 다른 컴퓨터에서 열어도 그대로 동작합니다.
나중에 기본값을 바꿔도 기존 프로젝트는 옮겨지지 않습니다. 의도된 동작입니다. Oleafly가 더 새로운 Typst를 내놓아도 고정된 논문은 줄바꿈과 쪽수가 그대로 유지됩니다.
한 프로젝트의 버전을 바꾸려면 다시 컴파일 옆의 화살표를 열고 Typst 버전(이 프로젝트) 아래를 보세요. 기본값은 설정에서 고른 버전을 따르며 고정을 해제합니다. 나머지 항목은 이 컴퓨터에 설치된 버전이며, 해당하는 경우 [내장] 또는 [시스템] 으로 표시됩니다. 목록에 없는 버전을 쓰려면 먼저 설정에서 설치하세요.
고정한 버전이 없을 때
섹션 제목: “고정한 버전이 없을 때”이 컴퓨터에 없는 버전으로 고정된 프로젝트를 열면, Oleafly는 다른 Typst로 몰래 빌드하지 않습니다. 컴파일이 “Typst 0.13.1이 설치되어 있지 않습니다”라는 메시지와 함께 멈추고, 미리 보기에 버튼 두 개가 나옵니다.
- Typst 0.13.1 다운로드는 고정된 버전을 설치하고 다시 컴파일합니다. Oleafly가 제공하는 버전일 때 나타납니다.
- 기본 버전의 이름이 붙은 Typst 0.15.1 사용은 고정을 해제하고 기본값으로 다시 컴파일합니다.
둘 중 하나를 고를 때까지 컴파일 메뉴는 고정을 [설치되지 않음] 으로 표시합니다.
바꾸기 전에 새 버전 시험하기
섹션 제목: “바꾸기 전에 새 버전 시험하기”Typst 프로젝트를 연 상태에서 더 새로운 Typst가 설치되어 있으면 설정의 Typst 탭에 새 버전 시험하기가 나타납니다. Typst 0.15.1로 확인(또는 표시된 버전)을 선택하세요. Oleafly는 임시 폴더에서 프로젝트를 두 번 빌드합니다. 한 번은 프로젝트의 현재 버전으로, 한 번은 새 버전으로 빌드합니다. 프로젝트는 아무것도 바뀌지 않습니다.
보고서에는 각 빌드의 성공 여부, 쪽수, 오류와 경고가 나옵니다. 쪽수가 바뀌는지도 알려 줍니다. Typst 0.15.1에서 새로 나옴에는 새 버전만 보고하는 메시지가, Typst 0.15.1에서 더 이상 보고하지 않음에는 사라지는 메시지가 나열됩니다. 메시지를 클릭하면 해당 파일의 그 줄이 열립니다.
결과가 마음에 들면 Typst 0.15.1로 전환이 프로젝트를 새 버전으로 고정합니다. 다시 확인은 무언가를 고친 뒤 두 빌드를 다시 실행합니다.
언어 서버는 버전을 따라갑니다
섹션 제목: “언어 서버는 버전을 따라갑니다”Tinymist는 Typst 파일의 자동 완성, 호버 도움말, 이름 바꾸기, 서식을 담당합니다(코드 인텔리전스 참고). Typst 마이너 버전마다 Tinymist 릴리스가 따로 있으며, 프로젝트는 자신의 Typst 버전에 맞는 것과 통신합니다.
내장 Tinymist는 Typst 0.15를 지원합니다. 더 오래된 계열로 고정된 프로젝트를 열면 Oleafly가 같은 체크섬 확인을 거쳐 맞는 Tinymist를 백그라운드에서 내려받고, 상태에 “이 프로젝트의 Typst 버전에 맞추기 위해 Tinymist 0.13.30을 내려받는 중”이라고 표시됩니다. 다운로드에 실패하면 Oleafly가 나중에 다시 시도합니다. 설치된 어떤 Typst도 더 이상 필요로 하지 않는 Tinymist 다운로드를 설정에서 찾으면 사용하지 않는 언어 서버 다운로드 제거를 제안합니다.
버전별로 할 수 있는 일
섹션 제목: “버전별로 할 수 있는 일”오래된 버전은 그 버전으로 시작한 프로젝트가 같은 방식으로 계속 빌드되도록 남아 있습니다. 일부 기능은 Typst 버전 자체가 지원하는지에 따라 달라집니다.
| 기능 | 0.11 | 0.12 | 0.13 | 0.14 이상 |
|---|---|---|---|---|
| 프로젝트 글꼴만 사용 | 아니요 | 예 | 예 | 예 |
| 재현 가능한 빌드 | 아니요 | 예 | 예 | 예 |
| PNG와 SVG 내보내기의 쪽 범위 | 아니요 | 예 | 예 | 예 |
| PDF/A | 아니요 | PDF/A-2b | PDF/A-2b, PDF/A-3b | Typst가 제공하는 모든 PDF/A 수준 |
| PDF/UA-1 | 아니요 | 아니요 | 아니요 | 예 |
| 프로젝트 폴더에 보관하는 패키지 | 아니요 | 예 | 예 | 예 |
| HTML 내보내기, 그리고 Typst의 HTML을 거친 Word 또는 Markdown 내보내기 | 아니요 | 아니요 | 예 | 예 |
| 소스와 PDF 동기화 | 아니요 | 아니요 | 예 | 예 |
| 컴파일할 때마다 태그된 PDF | 아니요 | 아니요 | 아니요 | 예 |
Typst 0.15 이상에서는 글꼴 선택기가 각 글꼴의 출처를 알려 줄 수 있습니다. 프로젝트가 쓰는 버전에 적용할 수 없는 설정은 컴파일 메뉴에 더 새로운 Typst 필요로 표시됩니다.
Typst Universe의 패키지
섹션 제목: “Typst Universe의 패키지”Typst 툴바 오른쪽 끝의 패키지 아이콘인 Typst 패키지를 선택하세요. 이름, 키워드, 분류로 Typst Universe를 검색합니다. 각 패키지에는 최신 버전이 표시되며, 프로젝트가 쓰는 것보다 새로운 Typst가 필요한 패키지에는 “Typst 0.14.0이 필요합니다. 이 프로젝트는 Typst 0.13.1을 사용합니다.”처럼 표시됩니다.
import 삽입은 열린 Typst 파일 맨 위에 #import 줄을 씁니다. import 복사는 대신 클립보드에 넣습니다.
Typst는 컴파일에서 처음 import할 때 @preview 패키지를 내려받아 모든 프로젝트가 함께 쓰는 캐시에 보관합니다. 패키지 목록도 캐시됩니다. 오프라인에서는 대화 상자가 마지막으로 가져온 목록을 날짜와 함께 보여 줍니다.
새 릴리스
섹션 제목: “새 릴리스”import가 Typst Universe에 있는 것보다 오래된 릴리스를 가리키면 버전 번호에 밑줄이 그어지고 “cetz 0.4.2를 쓸 수 있습니다. 이 import는 0.3.4를 사용합니다.” 같은 힌트가 나옵니다. 힌트 카드는 import의 버전 번호를 바꾸는 0.4.2로 업데이트를 제안합니다. 새 릴리스는 패키지 호출 방법을 바꿀 수 있으므로 받아들이기 전에 패키지의 변경 기록을 읽으세요. import 위에 포인터를 올리면 Typst Universe에서 열기도 나옵니다.
패키지를 프로젝트 안에 두기
섹션 제목: “패키지를 프로젝트 안에 두기”같은 대화 상자의 프로젝트 패키지 아래에서 패키지를 프로젝트로 복사는 프로젝트가 import하는 모든 패키지를 프로젝트 맨 위의 typst-packages 폴더로 복사합니다. 그 패키지들이 import하는 패키지도 복사하고, 프로젝트 폴더의 패키지 사용을 켭니다.
그다음부터 Typst는 typst-packages를 먼저 찾아봅니다. 패키지를 복사해 둔 프로젝트는 오프라인에서도, 어느 컴퓨터에서도 컴파일되며, 이 폴더를 소스와 함께 Git에 넣을 수 있습니다. 복사하지 않은 패키지는 계속 공유 캐시에서 가져옵니다. 이 기능에는 Typst 0.12 이상이 필요하며, 0.11로 고정한 프로젝트에서는 대화 상자가 먼저 버전을 바꾸라고 안내합니다.
패키지가 아직 캐시에 없으면 대화 상자가 “다음 패키지가 패키지 캐시에 없습니다: …”처럼 이름을 알려 줍니다. 온라인 상태에서 한 번 컴파일한 뒤 다시 복사하세요.
오프라인 모드
섹션 제목: “오프라인 모드”설정 → 일반에서 오프라인 모드를 켜면 Typst는 아무것도 내려받을 수 없습니다. 모든 패키지가 이미 공유 캐시나 typst-packages에 있어야 합니다. 없는 패키지가 있으면 컴파일이 실패하고 메시지에 그 패키지 이름이 나오므로, 다음에 온라인일 때 무엇을 가져와야 하는지 알 수 있습니다.
Typst는 네 곳에서 글꼴을 찾습니다. Typst에 내장된 글꼴, 컴퓨터에 설치된 글꼴, Oleafly에서 내려받은 글꼴 팩, 프로젝트 안의 글꼴 폴더입니다. 글꼴 파일을 프로젝트 맨 위의 fonts 폴더에 넣으면 컴파일러와 언어 서버가 모두 이를 인식합니다. 추가 폴더는 project.json의 typst.font_paths 아래에 나열할 수 있습니다. 프로젝트 밖의 폴더는 무시됩니다.
컴파일 메뉴의 글꼴(이 프로젝트) 아래에서는 시스템 글꼴 사용이 기본값입니다. 프로젝트 글꼴만 사용은 Typst가 이 컴퓨터에 설치된 글꼴을 읽지 못하게 합니다. 그러면 어느 컴퓨터에서나 PDF가 똑같이 나오고, 문서가 프로젝트에 없는 글꼴을 요구하면 공동 저자의 컴퓨터가 아니라 내 컴퓨터에서 알게 됩니다.
본문 글꼴을 고르려면 Typst 툴바의 슬라이더 아이콘인 문서 설정을 열고 본문 글꼴을 클릭하세요. 목록에는 프로젝트의 현재 글꼴 설정으로 Typst가 찾을 수 있는 모든 글꼴 계열이 나옵니다. Typst 0.15 이상에서는 각 계열에 프로젝트, 시스템, 글꼴 팩 또는 내장 표시가 붙습니다. 하나를 고르고 적용을 선택하면 Oleafly가 문서의 #set 규칙에 써 넣습니다.
글꼴 팩
섹션 제목: “글꼴 팩”설정 → 다운로드 → 글꼴에는 Typst용 무료 글꼴 팩 다섯 개가 있습니다. 중국어, 일본어, 한국어, 클래식 본문, 모던 산세리프와 세리프, 코드, 아이콘과 이모지입니다. 팩을 내려받고 나면 모든 Typst 프로젝트가 그 글꼴을 이름으로 쓸 수 있으며, 같은 탭의 Lato, PT Sans, PT Serif 다운로드도 마찬가지입니다. 팩은 다운로드가 완전히 끝난 뒤에만 컴파일에 포함되므로, 반쯤 끝난 다운로드가 빌드에 영향을 주는 일은 없습니다.
프로젝트 글꼴만 사용이나 재현 가능한 빌드로 설정한 프로젝트는 글꼴 팩을 읽지 않습니다. 이런 프로젝트에는 글꼴 파일을 프로젝트의 fonts 폴더에 복사하세요.
상자로 표시되는 문자
섹션 제목: “상자로 표시되는 문자”Oleafly는 컴파일할 때마다 어떤 글꼴로도 그릴 수 없는 문자가 있는지 확인합니다. Typst는 그런 문자를 상자로 그립니다. 그런 문자를 찾으면 컴파일에 경고가 붙고 편집기 위에 알림이 나타납니다.
- 빈 상자는 Typst가 쓸 수 있는 글꼴 중에 그 문자를 가진 것이 없다는 뜻이며, 경고에 그중 몇 개가 나옵니다. 중국어, 일본어, 한국어 팩이 CJK 텍스트를, 아이콘과 이모지 팩이 이모지를 다루는 것처럼 글꼴 팩이 그 문자를 포함하면, 알림이 다운로드 크기와 함께 글꼴 내려받기를 제안하고 로그가 내려받고 컴파일을 제안합니다. 그렇지 않으면 그 문자를 가진 글꼴을 프로젝트의
fonts폴더에 추가하세요. - 물음표가 든 상자는 Typst가 대체 글꼴로 그 문자를 그렸다는 뜻입니다. 문서 설정의 본문 글꼴에서, 또는
#set text(font: ("Libertinus Serif", "Apple SD Gothic Neo"))같은 글꼴 목록에서 그 문자를 가진 글꼴을 지정하세요. - 프로젝트 글꼴만 사용으로 설정한 프로젝트에서는 글꼴 팩과 시스템 글꼴이 적용되지 않습니다.
fonts폴더에 글꼴을 추가하거나, 프로젝트를 시스템 글꼴 사용과 표준 빌드로 바꾸세요.
알림의 문서 설정은 본문 글꼴을 고르는 패널을 엽니다. 알림을 닫으면 그 경고에 대해서는 알림이 숨겨집니다.
빌드 변형과 sys.inputs
섹션 제목: “빌드 변형과 sys.inputs”빌드 변형은 문서가 sys.inputs로 읽는 이름 붙은 값 묶음입니다. 익명 심사용 사본과 최종본, 또는 워터마크가 들어간 초안처럼 소스 하나로 서로 다른 PDF를 만들어야 할 때 변형을 쓰세요.
각 값이 무엇을 할지는 문서가 정합니다. 값은 항상 텍스트로 들어옵니다.
#let draft = sys.inputs.at("draft", default: "false") == "true"
#if draft [*Draft. Do not circulate.*]변형을 설정하려면:
- 문서 설정을 열고 빌드 변형까지 스크롤합니다.
- 변형 추가를 선택하고 이름을 붙입니다(예:
review). - 값 추가를 선택한 다음 이름에
draft, 값에true를 입력합니다. - 적용을 선택합니다.
- 컴파일 메뉴를 엽니다. 이제 변형(이 프로젝트) 에
review가 나열됩니다. 그것을 고르고 컴파일하세요.
변형 없음은 변형 값 없이 빌드합니다. 고른 변형은 이 컴퓨터에만 기억되므로 공동 저자는 같은 프로젝트에서 다른 변형을 빌드할 수 있습니다. 변형 자체는 project.json에 저장됩니다. 내보내기도 선택한 변형을 씁니다.
모든 빌드가 받아야 하는 값은 project.json의 typst.inputs 아래에 둡니다. 변형이 같은 이름의 값을 설정하면 변형이 우선합니다.
재현 가능한 빌드
섹션 제목: “재현 가능한 빌드”컴파일 메뉴의 빌드(이 프로젝트) 아래에서 재현 가능한 빌드는 같은 소스가 어느 컴퓨터에서나 같은 PDF를 만들게 합니다. 프로젝트 글꼴과 Typst 내장 글꼴만 쓰고, PDF의 날짜를 마지막 Git 커밋으로 정합니다. Git 저장소가 아닌 프로젝트는 1970년 1월 1일이라는 고정된 날짜를 받습니다.
이는 보관소 제출이나 CI 비교처럼 PDF가 체크섬과 일치해야 할 때 중요합니다. Typst 0.12 이상이 필요합니다. 이 기능이 켜져 있는 동안에는 시스템 글꼴 사용을 쓸 수 없습니다. 기본값은 표준 빌드입니다.

자동 컴파일로 실시간 미리 보기
섹션 제목: “자동 컴파일로 실시간 미리 보기”컴파일 메뉴에서 자동 컴파일을 켜기로 설정하세요. 그러면 Typst 프로젝트에서 Oleafly가 Typst 프로세스 하나를 계속 실행합니다. 입력을 멈추면 잠시 후 열린 파일이 저장되고, Typst가 컴파일하고, 미리 보기가 같은 스크롤 위치에서 다시 로드됩니다. 별도의 실시간 미리 보기 설정은 없습니다. 자동 컴파일이 곧 실시간 미리 보기입니다.
Typst가 시작되는 동안 메뉴에 “Typst 시작 중”이 표시됩니다. 오류가 반복되어 멈추면 메뉴가 그렇게 알려 주며, 다음 편집에서 다시 시작됩니다. 컴파일 중지는 프로세스를 끝내며, 다음 편집에서 역시 다시 시작됩니다. LaTeX와 Markdown 프로젝트는 자동 컴파일을 다르게 처리합니다. 컴파일을 참고하세요.
명령줄에서 빌드하기
섹션 제목: “명령줄에서 빌드하기”oleafly 명령은 앱을 열지 않고 프로젝트를 빌드합니다. Oleafly에 포함되어 있으며, PATH에 넣는 방법은 명령줄 도구에 나와 있습니다.
Typst 프로젝트에서 oleafly build와 oleafly watch는 project.json을 읽고 앱과 같은 설정을 씁니다. 고정된 버전, 복사해 둔 패키지, 글꼴 폴더, 시스템 글꼴 스위치, 입력값, 재현 가능한 빌드입니다.
--variant review는 변형을 빌드합니다. 프로젝트에 정의되지 않은 이름이면 빌드가 멈추고, 메시지에 프로젝트에 있는 변형이 나열됩니다.--offline은 앱의 오프라인 모드처럼 패키지 다운로드를 막습니다.- 고정된 프로젝트는 정확히 그 Typst로만 빌드됩니다. CLI는
OLEAFLY_TYPST, 앱이 내려받은 버전, CLI 옆의typst, 그리고PATH순서로 찾아봅니다. 어느 것도 고정된 버전을 보고하지 않으면 Typst를 실행하기 전에 빌드가 멈추고 설치 방법을 알려 줍니다. - 고정되지 않은 프로젝트는
OLEAFLY_TYPST가 설정되어 있으면 그것을 씁니다. 그렇지 않으면 설정 → 다운로드나oleafly typst default로 고른 기본 버전을 쓰고, 기본 버전을 고르지 않았다면 번들된 Typst 또는PATH의 Typst를 씁니다. oleafly doctor는 찾은 모든 Typst와 빌드에 쓰일 설정을 나열합니다. 고정된 버전이 없으면 실패합니다.
사용 중인 Typst에 적용할 수 없는 설정이 있으면 빌드가 안내 문구를 출력합니다. 예를 들어 Typst 0.11.1은 시스템 글꼴을 무시할 수 없다는 안내입니다. 터미널의 오류에는 Typst 자체의 힌트가 포함됩니다.
LaTeX 프로젝트를 Typst로 변환하기
섹션 제목: “LaTeX 프로젝트를 Typst로 변환하기”LaTeX 프로젝트를 열고 ⌘K(Ctrl+K)를 누른 뒤 Typst 프로젝트로 변환을 실행하세요. 새 프로젝트의 이름을 정하고 변환을 선택합니다. LaTeX 프로젝트는 그대로 남습니다. Oleafly는 그것으로 별도의 Typst 프로젝트를 만듭니다.
- Pandoc이 텍스트, 수식, 그림, 표를 변환합니다. Pandoc이 아직 설정되지 않았다면 Oleafly가 먼저 설정합니다.
\input,\include또는\subfile로 불러온 각 파일은 각자의.typ파일이 됩니다.- BibTeX 파일은 그대로 복사됩니다.
- Typst가 새 프로젝트를 컴파일해 확인합니다.
그다음 보고서가 프로젝트가 컴파일되는지 알려 주고, 변환된 것을 셉니다. 소스 파일, 그림, 표, 별행 수식, 상호 참조, 수식 변환기가 고친 수식, 복사한 파일, 그리고 고른 참고문헌 스타일입니다. 확인 필요에는 직접 고쳐야 할 것이 나열됩니다. 빠진 include나 이미지, Typst가 표시할 수 없는 이미지 형식, 변환기가 처리하지 못한 수식, 맞는 Typst 스타일이 없는 BibTeX 스타일, 여러 줄 수식의 한 줄에 붙은 레이블(이제 수식 전체를 가리킴) 등입니다. 컴파일 오류와 경고는 해당 파일과 줄로 연결됩니다.
Typst 프로젝트 열기를 선택하면 새 프로젝트로 전환됩니다. 새 프로젝트는 기본 Typst 버전으로 고정됩니다. Oleafly를 닫지 않는 동안에는 명령 팔레트의 Typst 변환 보고서 보기로 보고서를 다시 볼 수 있습니다.
프로젝트 전체 대신 파일 하나만 변환하려면 도구 페이지의 LaTeX를 Typst로를 쓰세요.
관련 페이지
섹션 제목: “관련 페이지”- 툴바와 첫 문서는 Typst로 쓰기.
- 로그, 컴파일 메뉴, 오프라인 모드는 컴파일.
- PNG, SVG, HTML, PDF/A, PDF/UA는 프로젝트 내보내기와 변환.
- Typst 소스를 읽는 검사는 프리플라이트 검사.