책 만들기

개요

Quarto 책은 여러 문서(챕터)를 하나의 원고로 묶은 것입니다. 책은 다양한 포맷으로 만들 수 있습니다.

  • HTML
  • PDF
  • MS Word
  • EPUB
  • AsciiDoc

HTML 책은 실제로 Quarto 웹사이트의 특수한 형태이며, 전체 텍스트 검색을 포함해 웹사이트와 동일한 기능을 지원합니다. 가장 중요한 차이는 HTML 책이 챕터 번호를 사용하므로 서로 다른 챕터 사이의 상호 참조를 지원한다는 점입니다.

Quarto로 만든 책의 예시는 다음과 같습니다.

책 소스
R for Data Science Code
Python for Data Analysis Code
Visualization Curriculum Code

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

빠른 시작

선택한 도구의 빠른 시작을 따라 간단한 책을 먼저 만들어 보세요. 기본 사항을 익힌 뒤, 더 고급 기능을 알아보려면 계속 읽어보세요.

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

그 다음 Book Project를 선택합니다.

프로젝트를 만들 상위 디렉터리를 선택하라는 안내가 나타납니다. 이어서 책 프로젝트의 디렉터리 이름을 입력합니다.

새 책 프로젝트가 생성되어 Positron에서 열립니다. Preview 버튼(Preview iconPreview icon)을 눌러 책을 미리 볼 수 있습니다.

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

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

그 다음 Book Project를 선택합니다.

프로젝트를 만들 상위 디렉터리를 선택하라는 안내가 나타납니다. 이어서 책 프로젝트의 디렉터리 이름을 입력합니다.

새 책 프로젝트가 생성되어 VS Code에서 열립니다. Preview 버튼(Preview iconPreview icon)을 눌러 책을 미리 볼 수 있습니다.

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

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

그 다음 디렉터리 이름과 기타 관련 옵션을 입력합니다.

Render 버튼을 클릭해 책을 미리 봅니다.

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

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

Terminal
quarto create project book mybook

그러면 mybook 하위 디렉터리에 간단한 책의 스캐폴딩이 생성됩니다. quarto preview 명령으로 책을 렌더링하고 미리 볼 수 있습니다.

Terminal
quarto preview mybook

책 미리보기는 새 웹 브라우저에서 열립니다. index.qmd(또는 intro.qmd 같은 다른 파일)을 편집하고 저장하면 미리보기가 자동으로 갱신됩니다.

워크플로

위에서 index.qmd, intro.qmd, summary.qmd 파일에 챕터가 들어 있는 간단한 책을 만들고 편집하는 방법을 소개했습니다. 여기서는 책 워크플로의 추가적인 측면을 더 자세히 설명합니다.

구성 파일

책 프로젝트 디렉터리에는 Quarto 프로젝트 파일인 _quarto.yml이 포함됩니다. 이 파일에는 책의 초기 설정이 들어 있습니다. 예:

project:
  type: book

book:
  title: "mybook"
  author: "Jane Doe"
  date: "8/18/2021"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
  epub:
    cover-image: cover.png

프로젝트 작업 방법과 책에 커스텀 pre/post render 스크립트를 추가하는 방법 등은 프로젝트 기초 문서를 참고하세요.

책 미리보기

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로 사이트를 전체 렌더링하세요.

AsciiDoc 책은 HTML 포맷으로 미리보기를 권장합니다. 자세한 내용은 AsciiDoc Books에서 확인하세요.

배포

책을 배포할 준비가 되면 render 명령으로 모든 출력 포맷을 렌더링합니다.

Terminal
quarto render

quarto render에 인수를 주지 않으면 모든 포맷이 렌더링됩니다. --to 인수로 개별 포맷만 렌더링할 수도 있습니다.

Terminal
quarto render           # 모든 포맷 렌더링
quarto render --to pdf  # PDF 포맷만 렌더링

책 출력물은 책 프로젝트의 _book 하위 디렉터리에 작성됩니다.

Terminal
mybook/
  _book/
    index.html # 및 기타 책 파일
    mybook.pdf
    mybook.epub

웹사이트 배포 문서에서 GitHub Pages, Netlify 등으로 책을 배포하는 방법을 확인할 수 있습니다. 해당 문서에서는 output-dir이 _site로 표현될 수 있지만, 책을 배포할 때는 _site 대신 _book을 사용해야 합니다.

AsciiDoc Books

AsciiDoc 책을 만들 때는 작업 중에 Quarto의 내장 HTML 포맷으로 미리보는 것을 권장합니다. 이렇게 하면 Quarto 미리보기 기능을 활용해 반복적인 워크플로를 사용할 수 있습니다. AsciiDoc 출력물을 만들 준비가 되면 AsciiDoctor 도구를 사용해 책을 PDF 또는 HTML로 컴파일하여 최종 렌더링 결과를 확인할 수 있습니다.

Asciidoctor-pdf로 PDF 미리보기

AsciiDoc 도구 체인으로 PDF 미리보기를 만드는 것은 책의 AsciiDoc 출력이 올바르게 렌더링되는지 확인하는 유용한 방법입니다. 다음 절차를 따르세요.

  1. 먼저 Asciidoctor PDF를 설치합니다. 설치 방법: https://docs.asciidoctor.org/pdf-converter/latest/install/

  2. 프로젝트 루트의 터미널에서 다음 명령으로 AsciiDoc 책을 PDF로 컴파일합니다.

    $  asciidoctor-pdf _book/book-asciidoc/<title>.adoc

  3. PDF는 _book/book-asciidoc/<title>.pdf에 생성됩니다.

Asciidoctor로 HTML 미리보기

AsciiDoc 도구 체인으로 HTML 미리보기를 만드는 것도 책의 AsciiDoc 출력이 올바르게 렌더링되는지 확인하는 유용한 방법입니다. 다음 절차를 따르세요.

  1. 먼저 Asciidoctor를 설치합니다. 설치 방법: https://docs.asciidoctor.org/asciidoctor/latest/install/

  2. 프로젝트 루트의 터미널에서 다음 명령으로 AsciiDoc 책을 HTML로 컴파일합니다.

    $  asciidoctor _book/book-asciidoc/<title>.adoc

  3. 책 전체가 포함된 단일 HTML 파일이 _book/book-asciidoc/<title>.html에 생성됩니다. 이 HTML 파일은 _book/book-asciidoc/ 폴더 안의 파일과 이미지를 참조하므로, 해당 폴더 없이 HTML만 이동하면 제대로 표시되지 않습니다.

더 알아보기

기본 책 템플릿을 실행할 수 있게 되면, 다음 문서에서 책을 개선하는 다양한 방법을 살펴보세요.

  • 책 구조: 책을 구성하는 다양한 방법(번호가 있는/없는 챕터 및 섹션, 여러 파트 구성, 부록 추가 등)을 다룹니다.

  • 책 상호 참조: 책에서 섹션, 그림, 표, 수식 등으로의 상호 참조를 만드는 방법을 설명합니다.

  • 책 출력: 다양한 출력 포맷에서 책의 스타일과 모양을 사용자 정의하는 방법과 독자를 위한 내비게이션 및 도구 제공 방법을 다룹니다.

  • 책 옵션: 사용 가능한 책 옵션에 대한 종합 참조입니다.

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

  • 웹사이트 배포: GitHub Pages, Netlify, RStudio Connect 등을 포함해 책을 웹사이트로 배포하는 다양한 옵션을 나열합니다.