# 코드 인텔리전스

LaTeX와 Typst를 위한 IDE 수준의 탐색: 정의로 이동, 참조 찾기, 프로젝트 전체 이름 바꾸기, 호버 카드, 수식 미리보기, 문서 개요, Typst 시그니처 도움말과 서식 정리.

Oleafly는 모든 `\label`, 인용 키, 사용자 지정 매크로, 정리, 용어집 항목, 파일들을 연결하는 `\input` 그래프를 포함해 프로젝트 전체를 색인합니다. 이 색인이 파일 간 탐색을 뒷받침합니다. Typst 파일에서도 같은 단축키를 쓸 수 있으며 Typst의 언어 서버가 응답합니다. 아래의 [Typst 파일](#typst-files)을 참고하세요.

단축키는 macOS 키로 표시했습니다. Windows와 Linux에서는 ⌘를 Ctrl로 읽으세요.

## 정의로 이동: F12 또는 ⌘-클릭

`\ref`, `\cite` 키, 사용자 지정 매크로, 직접 정의한 환경의 `\begin{env}`, 용어집 용어에 커서를 놓고 F12를 누르세요(또는 ⌘를 누른 채 클릭). 편집기가 정의된 위치로 이동하며, 정의가 프로젝트의 다른 파일에 있으면 그 파일을 엽니다.

이미 정의 위에서 F12를 누르면 그 참조 찾기로 전환됩니다. IDE에서 쓰는 방식과 같습니다.

## 참조 찾기: ⇧F12

Shift+F12는 왼쪽 레일의 **참고문헌** 패널에 해당 심볼이 쓰인 모든 위치를 나열합니다. 사용된 곳마다 파일, 줄, 미리보기가 있는 행이 하나씩 나오고, 정의 자체에는 "def" 배지가 붙습니다. 행을 클릭하면 그 위치로 이동합니다. "이 레이블을 지워도 될까?"나 "이 논문을 어디서 인용했지?"에 가장 빠르게 답하는 방법입니다.

![수식 레이블을 두 파일에서 동시에 이름 바꾼 뒤 참조 목록을 보여 주는 모습.](https://cdn.oleafly.com/images/gifs/desktop/rename-symbol.gif?v=2)

## 심볼 이름 바꾸기: F2

F2는 레이블, 인용 키, 매크로, 정리, 용어집 항목, 환경의 이름을 프로젝트 전체에서 한 번에 바꿉니다. 열려 있는 파일은 실시간으로 업데이트되고, 다른 파일은 디스크에서 다시 쓰이며, 색인이 다시 만들어집니다. 새 이름이 이미 있으면 충돌이 생기기 전에 이름 바꾸기가 차단되고, 토스트 알림이 몇 개 파일에 몇 건의 편집이 반영되었는지 알려 줍니다.

`fig:overview`를 `fig:architecture`로 바꾸면 여섯 개의 `\ref`가 모두 따라 바뀌는 데 2초면 충분합니다.

대신 `\input`이나 `\includegraphics`의 인수 같은 파일 경로에 커서를 놓고 F2를 누르면 그 파일의 이름이 바뀌고 그 파일을 가리키는 경로도 업데이트됩니다. Typst의 `#include`와 `image()`, Markdown의 링크와 이미지에서도 같은 방식으로 작동합니다. [이동한 파일을 따라가는 경로](/docs/files/#paths-follow-a-moved-file)를 참고하세요.

## 호버 카드

심볼 위에 마우스를 올리면 카드가 그 심볼을 설명합니다.

- **참조** 위: 심볼 종류, 소스 미리보기, 위치. LaTeX 빌드에 성공한 뒤에는 지원되는 참조에 컴파일된 번호와 페이지도 표시됩니다.
- **정의** 위: 프로젝트 전체에서 참조가 몇 개 있는지.
- **확인되지 않은** 대상 위: 분명한 "확인되지 않음" 표시. 잘못 입력한 `\ref`나 빠진 `.bib` 항목을 가장 먼저 알려 주는 경고입니다.

마우스를 올린 채 ⌘(Ctrl)를 누르고 있으면 클릭할 수 있는 심볼에 링크처럼 밑줄이 그어지며, 클릭하면 그 위치로 이동합니다.

## 마우스를 올려 수식 미리보기

인라인 `$…$`, `\(…\)`, 디스플레이 `\[…\]` 수식 위에 마우스를 올리면 컴파일하지 않고 KaTeX로 렌더링해 보여 줍니다. 디스플레이 수식은 디스플레이 스타일로 표시됩니다. 잘못된 수식은 오류를 보여 줍니다.

## 개요 패널

파일 트리 아래의 **개요** 패널은 모든 파일에 걸쳐 문서의 구조를 보여 줍니다. 섹션은 수준별로 들여쓰기되고 `\input` 포함도 함께 나옵니다. 다른 파일의 항목에는 파일 이름 배지가 붙습니다. 아무 항목이나 클릭하면 바로 그 위치로 이동합니다. 장별 파일 십여 개로 나뉜 학위 논문이라면 이 패널이 탐색에 쓰는 목차가 됩니다.

섹션 제목은 일반 텍스트로 표시되므로 제목 안의 색상 명령, 글꼴 전환, `\nameref`가 LaTeX 원문 그대로 나타나지 않습니다. `\section`을 감싸는 사용자 지정 매크로가 만드는 제목은 목록에 나오고, 매크로 정의 안에 있는 제목은 나오지 않습니다.

트리와 개요 사이의 패널 구분선을 드래그하면 크기를 조절할 수 있습니다.

## 툴바와 메뉴에서 찾는 방법

세 가지 탐색 명령은 모두 편집기 툴바의 **코드 인텔리전스** 메뉴(중괄호 아이콘)와 마우스 오른쪽 버튼 메뉴에도 있으므로, 단축키가 손에 익기 전에도 쉽게 찾을 수 있습니다.

## Typst 파일

`.typ` 파일에서는 Typst의 언어 서버인 Tinymist가 이 명령 대부분에 응답합니다. Oleafly는 프로젝트의 Typst 버전에 맞는 Tinymist 릴리스를 실행합니다([Typst 프로젝트](/docs/typst/#the-language-server-follows-the-version) 참고).

- F12 또는 ⌘-클릭은 다른 파일에 있는 것을 포함해 레이블, 변수, 함수의 정의로 이동합니다.
- ⇧F12는 **참고문헌** 패널에 쓰인 모든 위치를 나열합니다.
- F2는 프로젝트 전체에서 레이블, 변수, 함수의 이름을 바꿉니다.
- 함수 위에 마우스를 올리면 문서를 읽을 수 있습니다. `@preview` 임포트 위에 마우스를 올리면 Typst Universe의 패키지 링크가 나옵니다.

같은 세 명령은 Typst 툴바의 **코드 인텔리전스** 메뉴, 마우스 오른쪽 버튼 메뉴, ⌘K 팔레트에도 있습니다. Typst 파일과 LaTeX 파일의 레이블은 서로 분리되어 있으므로 두 곳에서 쓰인 레이블이 두 번 보고되지 않고, 하나의 이름을 바꿔도 다른 하나는 그대로입니다.

### 시그니처 도움말과 매개변수 힌트

함수 이름 뒤에 `(`를 입력하면 카드가 그 함수의 매개변수를 보여 주고, 입력 중인 매개변수가 강조됩니다. Esc를 누르면 닫힙니다. 함수 호출에서 각 인수 앞에 매개변수 이름을 표시하려면 **설정 → 모양 → 편집기**의 **Typst** 아래에서 **매개변수 이름 힌트**를 켜세요.

`rgb("#1f77b4")` 같은 색상 값 옆에는 작은 색상 견본이 표시됩니다. 소스에서 링크나 파일 경로를 ⌘-클릭하면 열립니다.

### Typst 파일 서식 정리

**문서 서식 정리**는 typstyle로 파일 전체를 정돈합니다. ⇧⌥F(Shift+Alt+F)를 누르거나, 편집기에서 마우스 오른쪽 버튼을 클릭하거나, ⌘K 팔레트에서 찾으세요. **선택 영역 서식 정리**는 선택한 줄만 정리합니다.

**설정 → 모양 → 편집기**의 **Typst** 그룹에서 포매터를 제어합니다.

- **저장할 때 서식 정리**는 ⌘S(Ctrl+S)를 누를 때마다 Typst 파일을 정리합니다. 자동 저장은 파일을 건드리지 않습니다. 기본값은 꺼짐입니다.
- **포매터 줄 너비**는 typstyle이 긴 줄을 줄바꿈하는 기준입니다. 기본값은 120자입니다.
- **포매터 들여쓰기**는 수준마다 쓰는 공백의 수입니다. 기본값은 2입니다.
- **Typst 린트 검사**는 저장할 때마다 실수일 가능성이 큰 부분을 찾습니다. 켜거나 끄면 언어 서버가 다시 시작됩니다.

## 한 폴더에 있는 여러 문서

한 폴더에 논문이 둘 이상 있을 수 있습니다. `manuscript.tex`와 `manuscript_v1.tex`가 나란히 있거나 `latexdiff` 출력이 함께 있는 경우입니다. 자체 `\documentclass`가 있는 LaTeX 파일은 각각 별개의 문서로 취급되며, `\input`, `\include`, `\subfile`로 불러오는 파일도 그 문서에 속합니다. 레이블, 정리, 용어집 항목, 매크로는 자기 문서에 속하므로, 같은 레이블이 논문 사본 세 개에 있다고 해서 세 번 정의된 것으로 나타나지 않습니다.

정의로 이동, 참조 찾기, 이름 바꾸기, 자동 완성, [프리플라이트](/docs/preflight/), `oleafly check`는 작업 중인 문서 안에서만 동작합니다. 다른 문서에서만 정의된 레이블을 가리키는 `\ref`는 정의되지 않은 것으로 표시되며, 컴파일도 같은 결과를 알려 줍니다. 아직 어느 문서에도 포함되지 않은 파일은 모든 레이블을 그대로 보고, 문서가 하나뿐인 프로젝트는 영향을 받지 않습니다.

## AI도 같은 색인을 봅니다

[AI 어시스턴트](/docs/ai-chat/)에는 같은 색인을 바탕으로 만든 `project_map` 도구가 있습니다. 개요, 레이블, 인용, 매크로, 파일 그래프, 확인되지 않은 참조를 모두 담고 있습니다. "방법론 섹션"에 대해 물으면 어시스턴트가 실제로 그 섹션을 찾을 수 있습니다.
