VS Code

개요

Quarto는 일반 텍스트(.qmd)로 표현된 Jupyter 노트북이나 일반 노트북 파일(.ipynb)을 렌더링할 수 있습니다. Quarto VS Code 확장에는 이러한 문서를 작업하는 데 도움이 되는 다양한 도구가 포함되어 있습니다. 예를 들면 다음과 같습니다:

Quarto 문서의 통합 렌더링 및 미리보기.
마크다운 및 임베디드 언어 구문 강조.
YAML 옵션 자동 완성과 진단.
임베디드 언어(Python, R, Julia 등) 자동 완성.
셀과 선택한 줄 실행 명령 및 키 바인딩.
LaTeX 수식과 Mermaid/Graphviz 다이어그램 라이브 미리보기.

Quarto 확장은 Jupyter, R, Julia 확장과 직접 통합됩니다. 예를 들어 아래에서는 Quarto 확장이 Python 셀을 실행하고 Python 함수에 대한 상황별 도움말을 표시합니다:

세 개의 세로 섹션이 있는 VS Code 편집기 스크린샷. 왼쪽에는 파일 탐색기와 quarto 도움말이 있습니다. 두 번째 패널은 Python 코드가 있는 quarto 파일의 소스 코드입니다. 세 번째는 Python이 실행 중인 인터랙티브 패널로, 코드 셀 출력이 표시됩니다.

Quarto 확장은 VS Code Extension Marketplace 또는 Open VSX Registry에서 설치할 수 있습니다.

VS Code 편집기

선호도와 작업에 따라 VS Code에서 다음 세 가지 편집기로 Quarto 렌더링 문서를 작성할 수 있습니다:

.qmd 문서를 텍스트로 편집하는 소스 코드 편집기.
.qmd 문서를 WYSIWYG 방식으로 편집하는 Visual Editor.
.ipynb 노트북을 편집하는 Notebook Editor.

아래에서는 소스 코드 편집기를 다루지만, 기본에 익숙해진 뒤에는 Visual Editor나 Notebook Editor 문서도 참고하면 좋습니다.

렌더링 및 미리보기

Quarto VS Code 확장에는 Quarto 문서를 렌더링하는 명령과 키보드 단축키가 포함되어 있습니다(단일 문서와 웹사이트/책 모두). 렌더링 후에는 quarto preview가 백그라운드에서 실행되어 VS Code에서 문서 옆에 미리보기 패널을 제공합니다:

두 개의 창이 나란히 배치되어 있습니다. 왼쪽 창은 VS Code에서 열린 qmd 파일입니다. 이 문서의 내용은 이 웹사이트 Getting Started: Welcome 섹션의 첫 부분과 동일합니다. 문서 내용이 오른쪽 창에서 Quarto에 의해 렌더링되어 표시됩니다.

렌더링과 미리보기를 실행하려면 Quarto: Preview 명령을 사용하세요. 또는 Ctrl+Shift+K 단축키나 편집기 우측 상단의 Preview 버튼()을 사용할 수도 있습니다:

Mac에서는 모든 Quarto 키보드 단축키의 접두 키로 Ctrl 대신 Cmd를 사용해야 합니다.

다른 형식

Quarto: Preview 명령은 현재 활성 문서의 기본 형식을 렌더링합니다. 다른 형식을 미리보려면 Quarto: Preview Format 명령을 사용하세요:

Preview Format을 실행하면 미리볼 형식을 선택할 수 있는 빠른 선택 목록이 표시됩니다(문서에 선언된 형식과 PDF, MS Word 같은 표준 형식 포함):

VS Code 편집기 상단. 명령 팔레트에 미리보기 가능한 형식의 빠른 선택 목록이 표시됩니다.

다른 형식을 미리본 뒤에는 현재 미리보기 세션 동안 Quarto: Preview 명령과 Ctrl+Shift+K 단축키가 자동으로 새로 선택한 형식에 바인딩됩니다. 원래 형식으로 돌아가려면 Quarto: Preview Format 명령을 다시 사용하세요.

임베디드 미리보기는 현재 HTML과 PDF 기반 형식(revealjs, beamer 슬라이드쇼 포함)에만 지원됩니다. Word 및 기타 형식은 적절한 외부 프로그램으로 출력물을 미리봐야 합니다.

렌더 명령

Quarto: Preview 명령은 문서 작성 중 가장 자주 사용하게 됩니다. 단일 형식(예: HTML 또는 PDF)만 있는 경우에는 미리보기가 렌더링을 수행하므로 출력에 만족하면 바로 배포할 수 있습니다. 다만 형식이 여러 개라면 미리보기는 한 번에 하나의 형식만 렌더링하므로 모든 형식을 명시적으로 렌더링해야 합니다. 이때 Quarto: Render Document 명령을 사용합니다:

VS Code 편집기 상단. 명령 팔레트에 렌더링 가능한 형식의 빠른 선택 목록이 표시됩니다.

선언된 형식이 여러 개라면 모두 렌더링할 수 있습니다. 또한 선언된 형식이나 PDF, MS Word 같은 표준 형식을 선택적으로 렌더링할 수도 있습니다.

저장 시 렌더링

기본적으로 Quarto는 .qmd나 .ipynb 파일을 저장할 때 자동으로 렌더링하지 않습니다. 렌더링에는 시간이 오래 걸릴 수 있고(예: 오래 걸리는 계산 포함), 전체 렌더링 없이도 주기적으로 저장할 수 있어야 하기 때문입니다.

하지만 저장할 때마다 자동 렌더링하도록 Quarto 확장을 구성할 수 있습니다. VS Code 설정이나 프로젝트/문서의 YAML 옵션에서 구성할 수 있습니다. VS Code 설정은 설정에서 quarto.render를 검색하면 Render on Save 옵션이 보입니다:

VS Code Quarto 렌더 설정. Render on Save 옵션이 선택되어 있습니다.

문서나 프로젝트 단위로 이 동작을 제어할 수도 있습니다. 문서 또는 프로젝트 YAML에 editor: render-on-save 옵션을 넣으면 VS Code 설정을 덮어씁니다. 예:

editor:
  render-on-save: true

외부 미리보기

외부 브라우저로 미리보기를 사용하거나(또는 렌더링 시 미리보기를 전혀 띄우지 않으려면) Preview Type 옵션으로 동작을 지정할 수 있습니다:

VS Code 설정 화면에서 'quarto preview type'을 검색한 모습. 사용자 설정에 Quarto > Render: Preview Type 드롭다운이 있으며, 기본값인 internal이 선택되어 있습니다. 다른 옵션으로 external과 none이 있습니다.

코드 셀

코드 셀을 편집하고 실행하는 데 도움이 되는 다양한 도구가 있습니다. 편집 도구에는 구문 강조, 코드 접기, 코드 완성, 시그니처 팁이 포함됩니다:

VS Code의 Quarto 문서에 Python 코드 셀이 있습니다. Python 셀에서 코드 완성 도우미가 활성화되어 있습니다.

Python, R, Julia 셀에 대해 현재 셀, 이전 셀, 선택한 줄을 실행하는 명령을 사용할 수 있습니다. 셀 출력은 Jupyter 인터랙티브 콘솔에서 나란히 표시됩니다: R과 Python 셀은 해당 콘솔에서 실행되며 출력은 패널에 표시됩니다:

VS Code에 두 개의 패널이 열려 있고, 오른쪽에 소스 코드, 왼쪽에 해당 코드의 인터랙티브 출력이 표시됩니다.

셀 실행에 사용할 수 있는 모든 명령과 키보드 단축키는 다음과 같습니다:

Quarto Command	Keyboard Shortcut
Run Current Cell	`⇧⌘ Enter`
Run Selected Line(s)	`⌘ Enter`
Run Next Cell	`⌥⌘ N`
Run Previous Cell	`⌥⌘ P`
Run All Cells	`⌥⌘ R`
Run Cells Above	`⇧⌥⌘ P`
Run Cells Below	`⇧⌥⌘ N`

Ctrl+Shift+I 단축키로 새 코드 셀을 빠르게 삽입할 수 있습니다.

입력 언어용 확장(예: 자동 완성, 코드 실행)의 향상 기능은 최신 버전의 확장을 설치해 활성화할 수 있습니다:

실행 디렉터리

임베디드 언어 확장은 실행 작업 디렉터리를 서로 다르게 처리합니다:

Python Extension은 코드가 실행되는 소스 파일의 디렉터리에서 실행합니다. 이 동작은 jupyter.notebookFileRoot 옵션으로 변경할 수 있습니다.
R Extension은 R Interactive 터미널에서 실행 중인 R 세션의 작업 디렉터리에서 코드를 실행합니다. setwd()로 이 디렉터리를 수동으로 변경할 수 있습니다.
Julia Extension은 Julia REPL 터미널에서 실행 중인 Julia 세션의 작업 디렉터리에서 코드를 실행합니다. cd()로 이 디렉터리를 수동으로 변경할 수 있습니다.

상황별 지원

Quarto: Show Assist Panel 명령을 실행하면 커서 위치에 따라 상황별 도움말이 표시되는 사이드바 패널이 나타납니다:

코드 편집 시 도움말/문서가 표시됩니다.
LaTeX 수식을 편집할 때 수식의 실시간 미리보기가 표시됩니다.
커서가 마크다운 이미지에 위치하면 미리보기 썸네일이 표시됩니다.

예를 들어 아래에서는 커서가 plot() 함수에 있을 때 matplotlib plot() 함수에 대한 도움말이 자동으로 표시됩니다:

VS Code 편집기 스크린샷. 세 개의 세로 섹션이 있으며, 왼쪽에는 파일 탐색기와 quarto 도움말이 있습니다. 두 번째 패널은 Python 코드가 있는 quarto 파일의 소스 코드입니다. 세 번째 패널은 Python이 실행 중인 인터랙티브 패널로, 코드 셀 출력이 표시됩니다.

라이브 미리보기

LaTeX 수식이나 Mermaid/Graphviz 다이어그램을 편집할 때 코드 위의 Preview 버튼(또는 Ctrl+Shift+L 단축키)을 클릭하면 편집 중에 자동으로 업데이트되는 라이브 미리보기를 열 수 있습니다.

아래는 현재 편집 중인 LaTeX 수식의 미리보기가 Quarto 보조 패널에 표시된 모습입니다:

VS Code에서 Quarto 문서를 열어 둔 상태로, 문서 왼쪽 패널의 "Quarto Equation" 섹션에 LaTeX 수식이 표시됩니다.

다음은 편집 중에 자동으로 업데이트되는 Graphviz 다이어그램 미리보기입니다:

VS Code에서 Quarto 문서를 편집하는 모습으로, 현재 편집 중인 다이어그램의 라이브 미리보기가 오른쪽 패널에 표시됩니다

YAML 인텔리전스

프로젝트 파일, YAML 프론트매터, 실행 가능한 셀 옵션에서 YAML 코드 완성을 사용할 수 있습니다:

YAML을 편집 중인 Quarto 문서. 커서 옆에 코드 완성 도우미가 열려 있고, 커서 앞의 글자('co')로 시작하는 YAML 옵션이 표시됩니다.

YAML에 오류가 있으면 문서를 저장할 때 강조 표시됩니다:

잘못된 옵션이 빨간색으로 밑줄 처리된 Quarto 문서의 YAML 메타데이터.

코드 스니펫

코드 스니펫은 반복되는 코드 패턴(예: 코드 블록, 콜아웃, div 등)을 더 쉽게 입력할 수 있도록 하는 템플릿입니다. Quarto 문서에서 Insert Snippet 명령을 실행하면 마크다운 스니펫을 삽입할 수 있습니다:

Quarto 문서에서 'Select a snippet' 드롭다운이 열린 상태이며, 첫 번째 항목(굵게 - 굵은 텍스트 삽입)이 선택되어 있습니다.

IntelliSense

VS Code는 IntelliSense를 사용해 입력 중인 함수에 대한 스니펫이나 가능한 값 제안을 제공합니다. 스니펫 제안은 기본적으로 비활성화되어 있지만 값 제안은 활성화되어 있습니다. 입력 중 또는 텍스트 스니펫을 선택하고 ctrl+space를 눌렀을 때 IntelliSense에서 스니펫 제안을 활성화하려면 editor.snippetSuggestions 설정을 none이 아닌 값(예: inline)으로 설정해야 합니다.

F1을 누르고 Preferences: Open Settings (UI) 또는 File > Preferences > Settings를 검색합니다.
@lang:quarto editor.snippetSuggestions를 검색합니다. Editor: Snippet Suggestions가 표시됩니다.
값을 none이 아닌 값으로 변경합니다.