Positron

개요

Positron에는 Quarto CLI와 VS Code Quarto 확장이 모두 포함되어 있어, 즉시 Quarto 작업을 시작할 수 있습니다.

Quarto VS Code 확장은 Positron에서 Quarto 지원을 제공하며 다음을 포함합니다:

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

Quarto 확장은 Positron의 네이티브 R 및 Python 기능과 직접 통합됩니다. 예를 들어 아래에서는 Quarto 확장이 활성 Python Console에서 Python 셀을 실행하고 포함된 이미지의 미리보기를 표시합니다.

세 개의 세로 섹션이 있는 Positron 편집기 스크린샷. 왼쪽에는 파일 탐색기와 quarto assist 패널이 있고, 두 번째 섹션에는 Python 코드가 있는 quarto 파일 소스 코드와 활성 Python Console이 있습니다. 세 번째에는 활성 콘솔의 출력으로 채워진 Environment와 Plots가 표시됩니다.

Quarto 확장은 Positron에 번들로 포함된 다른 확장(예: Jupyter 확장)과, 별도로 설치할 수 있는 Julia 확장과도 잘 동작합니다.

Positron 편집기

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

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

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

렌더링 및 미리보기

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

두 개의 창이 나란히 배치되어 있습니다. 왼쪽 창은 Positron에서 열린 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 같은 표준 형식 포함):

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

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

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

렌더 명령

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

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

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

저장 시 렌더링

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

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

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

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

editor:
  render-on-save: true

편집기 도구 모음의 체크박스를 사용해 이 설정을 활성화할 수도 있습니다:

편집기 도구 모음에 Render on Save 옵션이 선택된 상태.

외부 미리보기

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

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

코드 셀

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

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

Python, R, Julia 셀에 대해 현재 셀, 이전 셀, 선택한 줄을 실행하는 명령을 사용할 수 있습니다.

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

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

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 단축키로 새 코드 셀을 빠르게 삽입할 수 있습니다.

Positron에는 R과 Python 코드 셀을 위한 향상 기능(예: 자동 완성, 코드 실행)이 포함되어 있습니다. Julia에 대한 향상 기능을 얻으려면 Julia Extension을 설치하세요.

실행 디렉터리

Positron에서 코드 셀의 실행 디렉터리는 코드 셀 언어에 따라 달라집니다:

R 및 Python 셀은 Positron의 해당 콘솔에서 실행됩니다. 콘솔의 기본 실행 디렉터리는 워크스페이스로 열린 폴더입니다.
Julia 셀은 Julia Extension이 필요하며, Julia REPL 터미널에서 실행 중인 Julia 세션의 작업 디렉터리에서 코드를 실행합니다. cd()로 이 디렉터리를 수동으로 변경할 수 있습니다.

상황별 지원

Positron은 Quarto 문서의 Python 및 R 코드 셀에 대한 코드 지원을 제공합니다. 지원 항목은 다음과 같습니다:

함수와 인자의 코드 완성
작성 중이거나 함수에 마우스를 올렸을 때 표시되는 도움말 툴팁
커서가 함수에 있을 때 F1을 눌러 전용 Help 패널에서 도움말 열기

예를 들어 아래는 Help 패널에 np.arange 함수 도움말이 표시된 모습입니다.

두 개의 세로 섹션이 있는 Positron 편집기 스크린샷. 왼쪽 섹션에는 Python 코드가 있는 quarto 파일 소스 코드와 활성 Python Console이 있고, 오른쪽에는 `np.arange` 도움말이 표시된 Help 패널이 있습니다.

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

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

예를 들어 아래에서는 커서가 마크다운 이미지 경로에 있을 때 이미지 미리보기가 자동으로 표시됩니다:

라이브 미리보기

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

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

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

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

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

YAML 인텔리전스

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

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

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

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

코드 스니펫

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

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

IntelliSense

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

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