Quarto Pub

개요

Quarto Pub는 Quarto로 만든 정적 콘텐츠를 위한 무료 배포 서비스입니다. Quarto Pub은 블로그, 강의/프로젝트 웹사이트, 책, 프레젠테이션, 개인 취미 사이트에 적합합니다.

Quarto Pub에 배포된 모든 문서와 사이트는 공개적으로 표시됩니다. 공개해도 되는 콘텐츠만 배포하세요.

Quarto Pub에 콘텐츠를 배포하는 방법은 두 가지가 있습니다(아래에서 자세히 설명).

  1. 로컬에서 렌더링한 콘텐츠를 quarto publish 명령으로 배포합니다(처음 시작할 때 권장).

  2. GitHub을 사용한다면 GitHub Action으로 코드 변경 시마다 프로젝트를 자동 렌더링하고 결과를 배포할 수 있습니다.

처음 배포하기 전에 무료 Quarto Pub 계정을 만들어 두세요.

Note

Quarto Pub 사이트는 공개되며, 크기는 100MB를 넘을 수 없고 월 10GB 대역폭의 소프트 제한이 있습니다. 사용자 인증, 더 큰 사이트 호스팅, 사용자 정의 도메인이 필요하다면 Netlify 같은 전문 웹 배포 서비스를 고려하세요.

배포 명령

quarto publish 명령은 로컬에서 렌더링한 콘텐츠를 배포하는 가장 쉬운 방법입니다. 프로젝트가 있는 디렉터리에서 Quarto Pub용 quarto publish 명령을 실행하세요.

Terminal
quarto publish quarto-pub

Quarto Pub에 이전에 배포한 적이 없다면 배포 명령이 인증을 요청합니다. 배포를 진행한다고 확인하면 콘텐츠가 렌더링되고 배포되며, 브라우저가 열려 사이트를 확인할 수 있습니다.

_publish.yml

_publish.yml 파일은 배포 대상을 지정하는 데 사용됩니다. 이 파일은 quarto publish 명령을 실행할 때마다 자동으로 생성(또는 업데이트)되며, 프로젝트 또는 문서 디렉터리에 위치합니다.

배포된 콘텐츠의 서비스, id, URL은 _publish.yml에 지정됩니다. 예:

- source: project
  quarto-pub:
    - id: "5f3abafe-68f9-4c1d-835b-9d668b892001"
      url: "https://njones.quarto.pub/blog"

이미 배포하려는 Quarto Pub 사이트가 있다면 위 예시와 같은 _publish.yml 파일을 수동으로 만들고, 사이트에 맞는 id와 url 값을 넣어야 합니다.

계정 정보는 _publish.yml에 저장되지 않으므로 버전 관리에 포함하거나 여러 배포자가 공유해도 안전합니다.

옵션

다음 명령줄 옵션으로 quarto publish의 동작을 사용자 지정할 수 있습니다.

옵션 동작
--no-prompt 배포 확인 프롬프트를 표시하지 않습니다.
--no-browser 배포 후 브라우저를 열지 않습니다.
--no-render 배포 전에 다시 렌더링하지 않습니다.

웹사이트나 책이 아닌 문서를 배포하려면 문서 경로를 지정하세요.

Terminal
quarto publish quarto-pub document.qmd

사이트 관리

배포된 사이트의 “슬러그”(URL 경로)를 변경하거나 사이트를 완전히 삭제하려면 https://quartopub.com의 사이트 관리 인터페이스에서 배포된 모든 사이트 목록을 확인할 수 있습니다.

사이트를 클릭하면 슬러그 변경, 계정의 기본 사이트 설정, 사이트 삭제가 가능한 관리 페이지로 이동합니다.

사용자 기본 사이트

Quarto Pub 서브도메인 안의 경로(예: https://username.quarto.pub/mysite/)에 문서와 사이트를 배포하는 것 외에도, 기본 서브도메인(예: https://username.quarto.pub)에 접속했을 때 보이는 기본 사이트를 지정할 수 있습니다. 블로그나 개인 홈 페이지를 배포하기에 적합합니다.

사이트를 기본 사이트로 지정하려면 https://quartopub.com의 관리자 페이지에서 해당 사이트로 이동한 뒤 Default Site 옵션을 선택하고 변경 사항을 Save로 저장하세요.

여러 계정

Quarto Pub 계정이 여러 개라면 CLI(quarto publish)에서 사용하는 계정과 브라우저(인증 및 사이트 관리)에서 사용하는 계정의 관계를 이해하는 것이 중요합니다.

quarto publish를 사용할 때 다음과 같은 경우에 웹 브라우저가 열립니다.

  1. Quarto CLI가 계정에 접근하도록 승인해야 할 때
  2. 배포 후 배포된 사이트의 관리자 페이지를 열 때

CLI에서 Quarto Pub 계정으로 배포하기 전에 기본 웹 브라우저에서 해당 계정에 로그인되어 있는지 확인하세요. 그래야 CLI가 브라우저를 열 때 올바른 Quarto Pub 계정과 연결됩니다.

액세스 토큰

quarto publish로 Quarto Pub에 배포할 때는 계정 배포 권한을 위해 액세스 토큰이 사용됩니다. 배포 작업에 사용할 토큰이 없으면 Quarto CLI가 브라우저를 자동으로 열어 인증을 진행합니다.

$ quarto publish quarto-pub
? Authorize (Y/n) › 
❯ In order to publish to Quarto Pub you need to
  authorize your account. Please be sure you are
  logged into the correct Quarto Pub account in 
  your default web browser, then press Enter or 
  'Y' to authorize.

인증 과정은 기본 웹 브라우저를 열어 Quarto CLI의 배포 권한을 확인합니다. Quarto CLI가 액세스 토큰을 생성해 로컬에 저장합니다. 저장된 계정은 quarto publish accounts 명령으로 조회하고 제거할 수 있습니다.

$ quarto publish accounts
 ? Manage Publishing Accounts
 ❯ ✔ Quarto Pub: jj@rstudio.com
   ✔ Netlify: jj@rstudio.com
 ❯ Use the arrow keys and spacebar to specify 
   accounts you would like to remove. Press 
   Enter to confirm the list of accounts you
   wish to remain available.

https://quartopub.com의 관리자 인터페이스에서 액세스 토큰을 확인(및 철회)할 수도 있습니다.

이 인터페이스에서 Quarto CLI로 생성한 토큰을 확인할 수 있습니다. 더 이상 사용하지 않는 토큰은 철회할 수 있습니다. New Token 버튼을 눌러 비대화형 배포(예: CI 서비스)용 추가 토큰을 만들 수 있습니다.

액세스 토큰이 있으면 QUARTO_PUB_AUTH_TOKEN 환경 변수를 정의해 quarto publish에 사용할 수 있습니다. 예:

Terminal
# token created at https://quartopub.com/profile/
export QUARTO_PUB_AUTH_TOKEN="qpa_k4yWKEmlu5wkvx173Ls"

# publish to quarto-pub site specified within _publish.yml
quarto publish quarto-pub

quarto publish의 비대화형 사용에 대한 자세한 내용은 CI로 배포 문서를 참고하세요.

GitHub Action

quarto publish quarto-pub 명령으로 로컬에서 렌더링한 콘텐츠를 배포하는 것이 가장 간단하고 직관적인 방법입니다. 또 다른 방법은 GitHub Actions를 사용해 사이트를 렌더링하고 배포하는 것입니다(커밋으로 실행 및/또는 렌더링이 자동으로 트리거되길 원한다면 이 방법을 선호할 수 있습니다).

렌더링과 배포에는 여러 접근 방식이 있습니다. 아래에서는 GitHub Actions로 배포하는 방법을 안내합니다. 다양한 접근 방식의 개념적 배경은 CI 렌더링에서 확인하세요.

배포 기록

GitHub Action으로 배포하기 전에 배포 명령(바로 위에서 설명)으로 최소 한 번 배포를 완료해야 합니다. 이 배포 과정에서 GitHub Action이 사용할 배포 대상을 기록하는 _publish.yml 파일이 생성됩니다. 예:

- source: project
  quarto-pub:
    - id: "5f3abafe-68f9-4c1d-835b-9d668b892001"
      url: "https://njones.quarto.pub/blog"

위 예시와 같은 _publish.yml 파일을 수동으로 만들고 사이트에 맞는 id와 url 값을 넣어도 됩니다.

배포 대상을 나타내는 _publish.yml 파일이 준비되기 전에는 다음 단계로 진행하지 마세요.

계산 동결

R, Python, Julia 코드가 로컬에서만 실행되도록 하려면 _quarto.yml에 다음을 추가해 Quarto의 freeze 기능을 사용하도록 프로젝트를 구성하세요.

_quarto.yml
execute:
  freeze: auto

이제 사이트를 완전히 다시 렌더링하세요.

Terminal
quarto render

프로젝트에 실행 가능한 코드가 있으면 최상위에 _freeze 디렉터리가 생성됩니다. 이 디렉터리는 계산 결과를 저장하며 버전 관리에 포함해야 합니다. 실행 가능한 코드가 있는 .qmd 파일을 변경하면 다음 렌더링에서 자동으로 다시 실행되고, 업데이트된 계산 결과가 _freeze에 저장됩니다.

대안으로 GitHub Action에서 코드를 실행하는 방법도 있습니다. 지금은 로컬에서 코드를 실행하고 freeze로 계산 결과를 저장하는 방식으로 단순화합니다. 이후에 GitHub Action에서 코드 실행하는 방법을 설명합니다.

배포 액션

다음 YAML 파일을 만들어 .github/workflows/publish.yml에 저장해 publish.yml GitHub Action을 프로젝트에 추가하세요.

.github/workflows/publish.yml
on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4 

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Render and Publish 
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: quarto-pub
          QUARTO_PUB_AUTH_TOKEN: ${{ secrets.QUARTO_PUB_AUTH_TOKEN }}

Quarto Pub 자격 증명

마지막 단계는 배포에 필요한 자격 증명을 GitHub Action에 설정하는 것입니다. 이를 위해 Quarto Pub 개인 액세스 토큰을 만들고 GitHub Action이 이를 읽을 수 있도록 구성해야 합니다.

  1. 액세스 토큰이 없다면 Quarto Pub 계정 프로필 페이지로 이동해 New Token을 눌러 토큰을 만드세요. 기억하기 쉬운 이름을 지정하고 토큰을 클립보드에 복사합니다.

  2. Quarto Pub 액세스 토큰을 저장소의 액션 Secrets(저장소 Settings에서 접근)로 추가합니다. 오른쪽 상단에 New repository secret 버튼이 있습니다.

    버튼을 클릭하고 1단계의 개인 액세스 토큰을 QUARTO_PUB_AUTH_TOKEN 이름의 secret으로 추가하세요.

출력 무시

_site 또는 _book 디렉터리는 버전 관리에 포함할 필요가 없습니다(이전에 포함해 봤다면 매우 지저분한 diff가 생긴다는 것을 알 것입니다!). 진행하기 전에 프로젝트의 출력 디렉터리를 .gitignore에 추가하세요. 예:

.gitignore
/.quarto/
/_site/

이미 이 파일들을 버전 관리에 포함했다면 명시적으로 제거해야 할 수도 있습니다.

Terminal
git rm -r _site

커밋으로 배포

배포 액션과 Quarto Pub 자격 증명을 지정하고, _freeze 디렉터리를 포함한 업데이트된 저장소를 GitHub에 푸시하면, 이 커밋과 이후 커밋에서 액션이 실행되어 Quarto Pub에 자동으로 렌더링 및 배포됩니다.

코드 실행

원한다면 GitHub Action에서 렌더링의 일부로 R, Python, Julia 코드를 실행하도록 구성할 수도 있습니다. 직관적으로 최선처럼 보일 수 있지만, GitHub Actions 같은 CI 서비스에서 코드를 실행할 때는 다음 요구 사항을 고려해야 합니다.

  • CI 환경에서 모든 의존성(R, Python, Julia 및 필요한 패키지의 정확한 버전)을 재현해야 합니다.

  • 코드가 특별한 권한(예: 데이터베이스 또는 네트워크 접근)을 요구한다면 해당 권한도 CI 서버에 있어야 합니다.

  • 프로젝트에는 더 이상 쉽게 실행할 수 없는 문서(예: 오래된 패키지 버전을 사용하는 몇 년 전 블로그 글)가 있을 수 있습니다. 이런 문서는 CI에서 실행되지 않도록 개별적으로 freeze를 활성화해야 할 수 있습니다.

사전 준비

GitHub Action에서 코드가 실행되도록 보장하는 가장 좋은 방법은 프로젝트에서 venv나 renv 같은 가상 환경을 사용하는 것입니다(아래에서 각각의 예시 액션을 제공합니다). 이러한 도구 사용이 익숙하지 않다면 Quarto에서 가상 환경을 사용하는 문서를 참고하세요.

GitHub Action에서 코드를 실행하기로 결정했다면 _quarto.yml에서 위에서 설명한 freeze: auto를 제거할 수 있습니다. 일부 문서나 디렉터리에서 선택적으로 freeze를 사용하는 것은 여전히 가능합니다(디렉터리의 경우 해당 디렉터리에 _metadata.yml 파일을 만들고 freeze 구성을 지정하면 됩니다. 이는 Quarto가 블로그 프로젝트의 posts 폴더에서 기본으로 하는 방식입니다).

예시: venv와 Jupyter

다음은 requirements.txt에서 Python, Jupyter, 패키지 의존성을 설치한 뒤 코드를 실행하고 Quarto Pub에 출력물을 렌더링하는 GitHub Action의 완전한 예시입니다.

.github/workflows/publish.yml
on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4 

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        
      - name: Install Python and Dependencies
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'
          cache: 'pip'
      - run: pip install jupyter
      - run: pip install -r requirements.txt
      
      - name: Render and Publish 
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: quarto-pub
          QUARTO_PUB_AUTH_TOKEN: ${{ secrets.QUARTO_PUB_AUTH_TOKEN }}

예시: renv와 Knitr

다음은 renv.lock에서 R과 패키지 의존성을 설치한 뒤 코드를 실행하고 Quarto Pub에 출력물을 렌더링하는 GitHub Action의 완전한 예시입니다.

.github/workflows/publish.yml
on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4 

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        
      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.2.0'
      
      - name: Install R Dependencies 
        uses: r-lib/actions/setup-renv@v2
        with:
          cache-version: 1
      
      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: quarto-pub
          QUARTO_PUB_AUTH_TOKEN: ${{ secrets.QUARTO_PUB_AUTH_TOKEN }}

추가 옵션

더 큰 GitHub 저장소에서 Quarto 프로젝트가 최상위 디렉터리에 있지 않을 수도 있습니다. 이 경우 publish 액션 호출에 path 입력을 추가하세요. 예:

- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: quarto-pub
    path: subdirectory-to-use
    QUARTO_PUB_AUTH_TOKEN: ${{ secrets.QUARTO_PUB_AUTH_TOKEN }}

기본적으로 quarto publish는 배포 전에 프로젝트를 다시 렌더링합니다. 그러나 렌더링된 출력을 버전 관리에 저장한다면 GitHub Action이 다시 렌더링할 필요가 없습니다. 이 경우 publish 액션에 render: false 옵션을 추가하세요.

- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: quarto-pub
    render: false
    QUARTO_PUB_AUTH_TOKEN: ${{ secrets.QUARTO_PUB_AUTH_TOKEN }}