원고 사용하기

개요

원고는 계산 노트북이 논문의 소스이자 출판 기록의 일부가 되는 학술 논문을 작성할 수 있게 해주는 Quarto 프로젝트 유형입니다.

Quarto 원고가 처음이라면 원고 튜토리얼부터 시작하세요.

이 페이지에서는 다음을 배울 수 있습니다.

• 원고 프로젝트 만들기
• _quarto.yml 옵션으로 원고 출력 제어하기
• 학술지 템플릿 추가하기

원고 프로젝트 만들기

프로젝트를 원고로 지정하려면 _quarto.yml 설정 파일에 type: manuscript를 지정합니다.

_quarto.yml

project: 
  type: manuscript

그 다음 index.ipynb라는 Jupyter Notebook 또는 index.qmd라는 Quarto 문서에서 논문 콘텐츠를 작성합니다.

설정 파일의 manuscript 키로 다양한 원고 옵션을 제어할 수 있습니다. 예를 들어 article 키로 논문 소스를 index.* 이외의 파일로 지정할 수 있습니다.

_quarto.yml

manuscript:
  article: earthquakes.qmd

템플릿 콘텐츠로 시작하고 싶다면 다음 명령으로 새 원고 프로젝트를 만들 수 있습니다.

Terminal

quarto create project manuscript

노트북 포함시키기

프로젝트 디렉터리에 포함된 모든 노트북 파일(.qmd 또는 .ipynb)은 원고의 일부가 됩니다. 이 노트북들은 HTML 노트북 뷰로 렌더링되며, 원고 웹페이지의 “Notebooks” 아래에 링크됩니다.

노트북 링크

“Notebooks” 아래의 링크 텍스트는 노트북 YAML 메타데이터에 지정된 title이거나, 없으면 노트북의 첫 번째 마크다운 제목입니다. 둘 다 없으면 링크 텍스트는 노트북 파일 이름입니다.

notebooks로 텍스트를 직접 지정할 수도 있습니다. notebook으로 노트북 경로를 지정하고, title로 링크 텍스트를 설정합니다.

_quarto.yml

manuscript:
  notebooks:
    - notebook: notebooks/data-screening.ipynb
      title: Data Processing

외부 노트북

다른 곳에 호스팅된 노트북 링크를 제공하려면 url 옵션을 추가하세요.

_quarto.yml

manuscript:
  notebooks:
    - notebook: index.ipynb
      title: Binder Jupyter Lab Demo
      url: http://mybinder.org/v2/gh/binder-examples/jupyterlab/master?urlpath=lab/tree/index.ipynb

Quarto가 노트북 소스에서 HTML 노트북 뷰를 생성하게 하되, 다운로드용으로 특정 버전을 제공하고 싶다면 download-url 옵션을 추가하세요.

_quarto.yml

manuscript:
  notebooks:
    - notebook: notebooks/data-screening.ipynb
      title: Data Processing
      download-url: notebooks/data-screening-raw.ipynb

코드 링크

code-links를 사용하면 원고 웹페이지의 “Code Links” 아래에 표시될 링크를 추가할 수 있습니다. 예를 들어 다음은 Python 스크립트 링크를 추가합니다.

_quarto.yml

manuscript:
  code-links:
    - text: Data Import Code
      icon: file-code
      href: data-import.py

code-links 항목에는 다음 옵션을 제공할 수 있습니다.

옵션	설명
text	링크에 표시할 텍스트입니다.
href	링크의 URL입니다.
icon	링크에 사용할 bootstrap 아이콘입니다.
rel	이 링크의 a 태그에 사용할 rel입니다.
target	이 링크의 a 태그에 사용할 target입니다.

GitHub 및 Binder 링크

code-links 항목으로 전달할 수 있는 특별한 값이 두 가지 있습니다.

repo

원고의 GitHub 리포지토리를 가리키는 “GitHub Repo” 링크를 “Code Links” 아래에 추가합니다.

_quarto.yml

manuscript:
  code-links: repo

Quarto는 원고 프로젝트의 Git 설정에서 링크 URL을 추론합니다. code-links: repo가 작동하려면 원고 프로젝트가 Git 리포지토리여야 하며, 원격 origin이 GitHub로 설정되어 있어야 합니다.

binder

원고가 Binder 사용으로 구성된 경우 “Code Links” 아래에 “Launch Binder” 링크를 추가합니다.

_quarto.yml

manuscript:
  code-links: binder

다른 리소스 포함

Quarto는 원고 웹사이트에서 노트북을 HTML로 렌더링하는 데 필요한 리소스를 포함하려고 시도합니다. 하지만 resources로 리소스를 명시적으로 포함할 수도 있습니다. 예를 들어 data/earthquakes.csv에 넣은 데이터 파일을 포함하려면 다음과 같이 지정합니다.

_quarto.yml

manuscript:
  resources:
    - data/earthquakes.csv

이렇게 하면 독자가 {manuscript-url}/data/earthquakes.csv에서 데이터를 접근할 수 있습니다.

MECA 번들

원고 프로젝트가 생성할 수 있는 포맷 중 하나는 Manuscript Exchange Common Approach(MECA) 번들입니다. 이 번들은 계산 노트북을 포함한 원고와 리소스를 전송하기 위한 표준화된 방식입니다.

논문의 출력 포맷에 jats가 포함되면 MECA 번들이 생성됩니다.

_quarto.yml

format:
  html: default
  jats: default

또는 manuscript 옵션에서 meca-bundle을 true로 명시할 수 있습니다.

_quarto.yml

manuscript:
  meca-bundle: true

기본적으로 MECA 번들은 논문 파일 이름을 따라 index-meca.zip처럼 생성되지만, meca-bundle로 파일 이름을 지정할 수도 있습니다.

_quarto.yml

manuscript:
  meca-bundle: "bundle.zip"

원고 URL

HTML 이외 포맷의 노트북 링크는 원고 웹사이트 URL을 기준으로 구성됩니다. 원고를 GitHub Pages에 배포하면 Quarto가 URL을 감지해 설정합니다. 다른 호스트에 배포했거나 자동 감지가 동작하지 않는 경우 manuscript-url로 URL을 직접 설정할 수 있습니다.

_quarto.yml

manuscript:
  manuscript-url: www.posit.co

Binder 사용

Binder는 독자가 클라우드 컴퓨팅 환경에서 원고 노트북과 상호작용할 수 있도록, 컴퓨팅 환경을 복원하는 링크를 제공합니다.

Quarto는 원고에서 Binder를 사용할 수 있도록 구성하는 데 도움을 줍니다. 자세한 내용은 Binder 사용을 참고하세요.

페이지 커스터마이즈

원고 사이트의 논문 페이지와 노트북 뷰는 HTML 페이지이며, html 포맷 옵션으로 커스터마이즈할 수 있습니다. 전체 옵션 목록은 HTML 옵션에서 확인할 수 있습니다.

테마

예를 들어 기존 테마 이름을 제공해 theme 옵션으로 페이지의 시각적 스타일을 바꿀 수 있습니다.

_quarto.yml

format:
  html: 
    theme: solar

HTML 테마 문서에서 자세히 알아보세요.

댓글

Quarto는 원고 사이트에 댓글을 달 수 있도록 세 가지 도구와 연동합니다. 댓글을 활성화하려면 html 포맷의 comments 옵션을 사용하세요. 예를 들어 Hypothes.is 댓글을 활성화하려면 hypothesis: true만 추가하면 됩니다.

_quarto.yml

format:
  html: 
    comments:
      hypothesis: true

다른 두 도구는 Utterances와 Giscus입니다. 설정 방법은 HTML 기본: 댓글을 참고하세요.

학술지 템플릿 추가

Quarto 확장: 학술지 논문 페이지에서 사용 가능한 학술지 포맷 목록을 확인할 수 있습니다. 학술지 포맷(예: acs)을 사용하려면 두 가지 단계를 수행해야 합니다.

1. 적절한 학술지 포맷을 설치합니다. 대부분 기존 프로젝트에 설치하므로 quarto install extension 명령을 사용합니다. 예:

   Terminal

   quarto install extension quarto-journals/acs

   확장 식별자 quarto-journals/acs는 확장의 GitHub 사용자/리포지토리입니다. 일반적으로 확장 문서에 이 식별자와 정확한 설치 명령이 안내되어 있습니다.

2. 설정 파일에 format을 추가합니다.

   _quarto.yml

   format:
     html: default
     docx: default
     jats: default
     acs-pdf: default

   포맷은 확장 이름(acs) 뒤에 기존 Quarto 포맷(-pdf)이 붙는 형태입니다.