웹사이트 만들기

개요

Quarto 웹사이트는 문서 묶음을 배포하기 위한 편리한 방법입니다. 웹사이트로 배포된 문서는 내비게이션 요소, 렌더링 옵션, 시각적 스타일을 공유합니다.

웹사이트 내비게이션은 전역 내비게이션 바, 링크가 있는 사이드바, 또는 여러 수준의 콘텐츠가 있는 사이트의 경우 둘의 조합으로 제공할 수 있습니다. 웹사이트 전체 텍스트 검색을 활성화할 수도 있습니다.

Quarto 웹사이트는 GitHub Pages, Netlify, Posit Connect 등 다양한 대상에 배포할 수 있으며, 다른 정적 호스팅 서비스나 인트라넷 웹 서버에도 배포할 수 있습니다. 자세한 내용은 웹사이트 배포 문서를 참고하세요.

빠른 시작

사용하는 도구의 빠른 시작을 따라 간단한 웹사이트를 만들어 보세요. 기본을 익힌 뒤에는 웹사이트 내비게이션과 더 고급 기능을 다룬 문서를 참고하세요.

Positron에서 새 웹사이트 프로젝트를 만들려면 명령 팔레트에서 Quarto: Create Project 명령을 실행합니다:

그 다음 Website Project를 선택합니다:

프로젝트를 생성할 상위 디렉터리를 선택하라는 안내가 나오며, 이어서 웹사이트 프로젝트의 디렉터리 이름을 입력합니다:

새 웹사이트 프로젝트가 생성되어 Positron에서 열립니다. Preview 버튼(Preview iconPreview icon)을 눌러 웹사이트를 미리봅니다:

미리보기는 소스 파일 오른쪽에 표시됩니다. index.qmd를 다시 렌더링하거나 about.qmd 같은 다른 파일을 렌더링하면 미리보기가 자동으로 업데이트됩니다.

VS Code에서 새 웹사이트 프로젝트를 만들려면 명령 팔레트에서 Quarto: Create Project 명령을 실행합니다:

그 다음 Website Project를 선택합니다:

프로젝트를 생성할 상위 디렉터리를 선택하라는 안내가 나오며, 이어서 웹사이트 프로젝트의 디렉터리 이름을 입력합니다:

새 웹사이트 프로젝트가 생성되어 VS Code에서 열립니다. Preview 버튼(Preview iconPreview icon)을 눌러 웹사이트를 미리봅니다:

미리보기는 소스 파일 오른쪽에 표시됩니다. index.qmd를 다시 렌더링하거나 about.qmd 같은 다른 파일을 렌더링하면 미리보기가 자동으로 업데이트됩니다.

RStudio에서 새 웹사이트 프로젝트를 만들려면 New Project 명령을 사용하고 Quarto Website를 선택합니다:

그 다음 웹사이트의 디렉터리 이름과 기타 관련 옵션을 제공합니다:

Rstudio의 'New Project Wizard' 메뉴 중 'Create Quarto Website' 섹션. 왼쪽에는 Quarto 로고가 있고, 오른쪽에는 'Directory name', 'Create project as subdirectory of:' 필드가 있습니다. 아래에는 'Engine' 옵션이 있으며 값은 'None'입니다. 그 아래에는 'Create a git repository', 'Use visual markdown editor' 옵션이 있습니다. 오른쪽 하단에는 'Create Project'와 'Cancel' 버튼이 나란히 있고, 왼쪽 하단에는 'Open in new session' 옵션이 있습니다.

Render 버튼을 눌러 웹사이트를 미리봅니다:

미리보기는 소스 파일 오른쪽에 표시됩니다. index.qmd를 다시 렌더링하거나 about.qmd 같은 다른 파일을 렌더링하면 미리보기가 자동으로 업데이트됩니다.

터미널에서 새 웹사이트 프로젝트를 만들려면 quarto create project 명령을 사용하고, 안내에 따라 프로젝트 유형을 선택하고 이름을 입력합니다(디렉터리 이름으로 사용됨):

Terminal
quarto create project website mysite

이 명령은 mysite 하위 디렉터리에 간단한 웹사이트의 기본 구조를 생성합니다. quarto preview 명령을 사용해 웹사이트를 렌더링하고 미리봅니다:

Terminal
quarto preview mysite

웹사이트 미리보기는 새 웹 브라우저 창에서 열립니다. index.qmd(또는 about.qmd 같은 다른 파일)를 편집하고 저장하면 미리보기가 자동으로 업데이트됩니다.

워크플로

위에서는 간단한 웹사이트를 만들고 편집하는 방법을 보여주었습니다. 이 섹션에서는 웹사이트 워크플로를 더 깊이 다룹니다.

설정 파일

모든 웹사이트에는 _quarto.yml 설정 파일이 있으며, 웹사이트 옵션과 사이트 내 HTML 문서의 기본값을 제공합니다. 예를 들어 위에서 만든 간단한 사이트의 기본 설정 파일은 다음과 같습니다:

_quarto.yml
project:
  type: website

website:
  title: "today"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

웹사이트 설정에 대한 자세한 내용은 웹사이트 내비게이션과 웹사이트 도구 문서를 참고하세요. HTML 형식 옵션을 사용자 정의하는 방법은 HTML 문서 문서에서 확인할 수 있습니다.

웹사이트 미리보기

VS Code 또는 RStudio를 사용하는 경우, Preview 버튼(VS Code) 또는 Render 버튼(RStudio)이 문서를 자동으로 렌더링하고 quarto preview를 내장 창에서 실행합니다. 필요하다면 터미널에서도 동일하게 수행할 수 있습니다:

Terminal
# 현재 디렉터리의 웹사이트 미리보기
quarto preview

웹사이트를 미리볼 때(VS Code/RStudio 통합 도구 또는 터미널) 설정 파일(예: _quarto.yml)과 사이트 리소스(예: 테마 또는 CSS 파일)의 변경은 미리보기가 자동으로 새로고침됩니다.

미리보기 서버의 동작(포트, 브라우저 열기 여부 등)은 명령줄 옵션 또는 _quarto.yml 설정 파일로 사용자 정의할 수 있습니다. 자세한 내용은 quarto preview help 또는 프로젝트 파일 참조를 참고하세요.

Important

사이트를 미리보는 동안 페이지는 렌더링되고 업데이트됩니다. 하지만 전역 옵션(예: _quarto.yml 또는 포함된 파일)을 변경했다면 전체 사이트를 다시 렌더링해야 변경사항이 모두 반영됩니다. 따라서 일부 페이지를 미리보기 서버로 확인했더라도 배포 전에 항상 사이트 전체를 quarto render로 렌더링해야 합니다.

웹사이트 렌더링

웹사이트를 렌더링(미리보기 없이)하려면 quarto render 명령을 사용합니다. 기본적으로 _site 디렉터리에 렌더링됩니다:

Terminal
# 현재 디렉터리의 웹사이트 렌더링
quarto render

프로젝트 작업(렌더링할 파일 목록 지정, 사전/사후 렌더 스크립트 추가 등)에 대한 자세한 내용은 프로젝트 기본 문서를 참고하세요.

렌더링 대상

기본적으로 프로젝트 디렉터리 안의 모든 유효한 Quarto 입력 파일(.qmd, .ipynb, .md, .Rmd)이 렌더링됩니다. 단, 다음에 해당하는 파일은 제외됩니다.

  1. 파일 또는 디렉터리 접두사가 .인 경우(숨김 파일)

  2. 파일 또는 디렉터리 접두사가 _인 경우(보통 최상위 파일이 아닌 경우, 예: 다른 파일에 포함되는 파일)

  3. README.md 또는 README.qmd 파일(대개 실제 렌더링 대상이 아니라 버전 관리 웹 UI에서 소스 코드를 볼 때의 안내용 콘텐츠)

프로젝트의 모든 대상 문서를 렌더링하고 싶지 않거나 렌더링 순서를 더 정확히 제어하고 싶다면 프로젝트 메타데이터에 project: render: [files] 항목을 추가할 수 있습니다. 예:

project:
  render:
    - section1.qmd
    - section2.qmd

render 목록을 정의할 때 와일드카드를 사용할 수 있습니다. 예:

project:
  render:
    - section*.qmd

render 목록에서 파일이나 디렉터리를 제외하려면 ! 접두사를 사용할 수 있습니다. 이 경우 렌더링하고 싶은 항목을 먼저 모두 지정해야 합니다. 예:

project:
  render:
    - "*.qmd"
    - "!ignored.qmd"
    - "!ignored-dir/"
Note

출력 파일 이름이 . 또는 _로 시작해야 하는 경우(예: Hugo 사용자의 _index.md)에는 Quarto 입력 파일 이름에서 접두사를 빼고(예: index.qmd), YAML에 output-file 매개변수를 명시적으로 추가해야 합니다. 예:

---
output-file: _index.md
---

링크

사이트 내 페이지 간 링크를 만들 때 .html 파일이 아니라 소스 파일을 링크 대상으로 지정할 수 있습니다. 문서의 특정 섹션으로 연결하려면 소스 파일 뒤에 해시 식별자(#)를 추가하면 됩니다. 예:

[about](about.qmd)
[about](about.qmd#section)

.html 파일을 직접 대상으로 하는 대신 이 링크 스타일을 사용하면, 나중에 사이트를 책으로 전환했을 때 파일 기반 링크가 단일 파일을 생성하는 형식(예: PDF 또는 MS Word)의 섹션 링크로 자동 해결됩니다.

웹사이트 테마

웹사이트의 모양은 HTML 테마로 제어합니다. 이 옵션은 웹사이트 설정 파일의 format 아래에 설정합니다:

_quarto.yml
format:
  html:
    theme: cosmo
    css: styles.css

사용 가능한 옵션에 대한 자세한 내용은 HTML 테마 문서를 참고하세요.

더 알아보기

기본 웹사이트를 만든 후 사이트를 개선하는 다양한 방법은 다음 문서에서 확인할 수 있습니다:

  • 웹사이트 내비게이션에서는 상단 내비게이션 바, 사이드바, 또는 둘을 함께 사용하는 하이브리드 디자인 등 다양한 내비게이션 방법을 설명합니다. 이 문서에는 전체 텍스트 검색과 사이트 전체 푸터 추가도 포함됩니다.

  • 웹사이트 도구에서는 사이트에 소셜 메타데이터(예: Twitter Cards)와 Google Analytics를 추가하는 방법, 사용자가 다크/라이트 색상 스킴을 전환할 수 있게 하는 방법을 다룹니다.

  • 웹사이트 옵션은 사용 가능한 웹사이트 옵션에 대한 포괄적인 레퍼런스를 제공합니다.

  • 코드 실행은 문서 수가 많거나 계산 비용이 큰 사이트의 렌더링을 최적화하는 팁을 제공합니다.

  • 웹사이트 배포는 GitHub Pages, Netlify, Posit Connect 등 다양한 웹사이트 배포 옵션을 열거합니다.