GitHub Pages

개요

GitHub Pages는 GitHub 저장소에서 관리되는 소스 코드를 기반으로 콘텐츠를 배포할 수 있는 웹사이트 호스팅 서비스입니다.

Quarto 웹사이트와 문서를 GitHub Pages에 배포하는 방법은 세 가지입니다.

  1. 로컬에서 사이트를 docs 디렉터리에 렌더링하고, 렌더링된 사이트를 GitHub에 체크인한 뒤 GitHub 저장소를 docs 디렉터리에서 배포하도록 설정합니다.

  2. 로컬에서 렌더링한 콘텐츠를 quarto publish 명령으로 배포합니다.

  3. GitHub Action으로 파일(단일 Quarto 문서 또는 Quarto 프로젝트)을 자동 렌더링하고, 저장소에 소스 코드 변경을 푸시할 때마다 결과를 배포합니다.

각 방법을 아래에서 다루기 전에 중요한 전제 조건이 있습니다. 로컬 머신에 GitHub와 동기화된 Git 저장소가 있어야 합니다. 배포된 웹사이트 URL은 사용자 이름과 저장소 이름을 조합해 결정됩니다(예: https://username.github.io/reponame/).

GitHub Pages 사이트에 사용자 정의 도메인을 설정할 수도 있지만, 그 전에 기본 도메인으로 먼저 사이트를 배포해 보세요.

docs로 렌더링

GitHub Pages로 배포하는 가장 간단한 방법은 docs 디렉터리에 렌더링한 뒤 해당 디렉터리를 저장소에 체크인하는 것입니다. 렌더링 출력물을 버전 관리에 포함하고 싶지 않다면 아래 배포 명령 논의를 참고하세요.

시작하려면 프로젝트 구성을 docs를 output-dir로 사용하도록 변경하세요. 예:

_quarto.yml
project:
  type: website
  output-dir: docs

그 다음 저장소 루트에 .nojekyll 파일을 추가해 GitHub Pages가 Jekyll(기본 사이트 생성 도구)로 추가 처리를 하지 않도록 합니다.

Mac/Linux 
Terminal
touch .nojekyll
Windows 
Terminal
copy NUL .nojekyll

이제 사이트를 렌더링하고 GitHub에 푸시하세요.

Terminal
quarto render
git add docs
git commit -m "Publish site to docs/"
git push

마지막으로 GitHub 저장소가 main 브랜치의 docs 디렉터리에서 배포하도록 설정하세요.

이 설정을 변경하면 GitHub가 웹사이트 배포를 시작합니다. 이후 main에 커밋하고 푸시할 때마다 사이트가 업데이트됩니다.

배포 명령

quarto publish 명령은 로컬에서 렌더링한 문서와 웹사이트를 쉽게 배포하는 방법입니다. quarto publish를 사용하기 전에(로컬 또는 GitHub Action에서) 아래 설명된 소스 브랜치와 출력 무시를 구성해야 합니다.

소스 브랜치

배포 전에 저장소의 Source 브랜치가 gh-pages이며 사이트 디렉터리가 저장소 루트(/)로 설정되어 있는지 확인하세요. 저장소 Settings : Pages에서 이 옵션을 변경할 수 있습니다. 예를 들어 gh-pages 브랜치가 이미 있는 경우:

gh-pages 브랜치가 없다면 다음과 같이 생성합니다. 먼저 git status로 현재 작업 브랜치의 모든 변경이 커밋되었는지 확인하세요. 그 다음:

Terminal
git checkout --orphan gh-pages
git reset --hard # make sure all changes are committed before running this!
git commit --allow-empty -m "Initialising gh-pages branch"
git push origin gh-pages

마지막 git push가 앞의 그림처럼 Settings : Pages를 올바르게 설정했는지 확인하세요. 이후 git checkout main 등으로 원래 브랜치로 돌아갑니다.

Ignoring Output

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

.gitignore
/.quarto/
/_site/

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

Terminal
git rm -r _site

배포

소스 브랜치를 구성하고 .gitignore를 업데이트한 뒤 프로젝트/저장소 디렉터리로 이동하고 gh-pages 브랜치가 아닌지 확인한 다음, GitHub Pages용 quarto publish 명령을 실행하세요.

Terminal
quarto publish gh-pages

배포 명령은 배포 확인을 받은 뒤 콘텐츠를 렌더링하고, 출력을 특수한 gh-pages 브랜치에 복사한 다음 GitHub에 푸시합니다. 배포가 완료되면 브라우저가 열려 사이트를 보여줍니다.

비공개 사이트

비공개(비밀번호 보호) 사이트에 배포하는 경우, quarto publish가 사이트가 준비될 때까지 기다렸다가 브라우저를 여는 로직이 제대로 동작하지 않습니다. 이때는 --no-browser 옵션으로 이를 건너뛰세요.

Terminal
quarto publish gh-pages --no-browser

문서

웹사이트나 책이 아닌 문서를 배포하려면 문서 경로를 지정하세요(한 GitHub 저장소에서 하나의 문서만 배포할 수 있습니다).

Terminal
quarto publish gh-pages document.qmd

옵션

Here are all of the available command line options for quarto publish gh-pages:

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

GitHub Action

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

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

Freezing Computations

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

_quarto.yml
execute:
  freeze: auto

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

Terminal
quarto render

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

Note that an alternative approach is to execute the code as part of the GitHub Action. For now we’ll keep things simpler by executing code locally and storing the computations by using freeze. Then, further below, we’ll cover Executing Code within a GitHub Action.

배포 액션

배포 액션을 구성하기 전에 로컬에서 quarto publish gh-pages를 한 번 실행해야 합니다. 이렇게 하면 이후 GitHub Action 실행에 필요한 _publish.yml 구성이 생성됩니다. 프로젝트에서 다음을 실행하세요.

quarto publish gh-pages

로컬 배포를 완료했다면 다음 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
    permissions:
      contents: write
    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: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

이 액션은 main 브랜치에 푸시할 때마다 실행되며, 저장소의 Actions 탭에서 수동으로도 실행할 수 있습니다. 액션은 콘텐츠를 렌더링해 GitHub Pages에 배포하므로, GitHub Actions가 저장소에 쓰기 권한을 갖도록 설정해야 합니다. 이는 저장소 Settings의 Actions 섹션에서 Workflow permissions의 Read and write permissions를 체크하면 됩니다.

이 설정을 마쳤다면 _freeze 디렉터리를 포함한 새 파일을 모두 저장소에 체크인하고 GitHub에 푸시하세요. 저장소에 GitHub Pages 사이트가 생성되며, 이후 변경을 푸시할 때마다 자동으로 다시 빌드됩니다. 사이트 URL과 배포 상태는 저장소 Settings의 Pages 섹션에서 확인할 수 있습니다.

코드 실행

원한다면 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, 패키지 의존성을 설치한 뒤 코드를 실행하고 GitHub Pages에 출력물을 렌더링하는 GitHub Action의 완전한 예시입니다.

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

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    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: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

예시: renv와 Knitr

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

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

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    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: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

추가 옵션

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

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

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

- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: gh-pages
    render: false
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

다른 고급 옵션은 Quarto publish 액션의 전체 정의를 참고하세요.

사용자 정의 도메인

사용자 정의 도메인을 사용하면 GitHub Pages 기본 도메인 username.github.io 대신 자신의 도메인을 사용할 수 있습니다. 사용자 정의 도메인을 사용하려면 다음 두 단계를 수행해야 합니다.

  1. GitHub 저장소 설정에 도메인 추가
  2. DNS 제공업체에서 레코드 구성

1. GitHub 저장소 설정에 도메인 추가

프로젝트 루트 디렉터리(즉, _quarto.yml과 같은 위치)에 사용자 정의 도메인이 들어 있는 CNAME 파일을 추가하세요.

website/
├── _site/
├── _quarto.yml
├── CNAME
├── about.qmd
└── index.qmd
CNAME
blog.example.com

Quarto는 CNAME 파일을 사이트 리소스로 인식하고, 렌더링할 때 사이트 출력 디렉터리로 복사합니다.

CNAME이 GitHub Pages에서 사용되도록 사이트를 다시 렌더링하고 배포하세요.

Note

GitHub Pages 문서는 Settings에서 도메인을 추가하는 방법을 설명합니다. 하지만 이렇게 하면 렌더링된 사이트 위치에 CNAME 파일이 생성되어, Quarto로 사이트를 렌더링할 때마다 덮어써집니다.

2. DNS 제공업체에서 레코드 구성

DNS 제공업체에 설정해야 하는 레코드는 루트 도메인(예: example.com)인지 서브도메인(예: www.example.com, blog.example.com)인지에 따라 다릅니다.

루트 도메인은 ALIAS, ANAME, A 레코드가 필요하고, 서브도메인은 CNAME 레코드가 필요합니다. 적절한 값은 GitHub Pages 문서의 DNS 레코드 요약 표에서 확인하세요. 루트 도메인의 경우 DNS 제공업체가 기본으로 추가한 주소를 덮어써야 할 수도 있으니 레코드 값을 꼼꼼히 확인하세요.

사용자 사이트

여러 저장소에 연결된 사이트 외에도, 루트 사용자 도메인(예: https://username.github.io)에서 제공되는 사용자 사이트를 만들 수 있습니다. 블로그나 개인 홈 페이지를 배포하기에 적합합니다. 사용자 사이트를 만들려면:

  1. username.github.io(여기서 “username”은 GitHub 사용자 이름)라는 이름의 Git 저장소를 만들고 로컬 머신과 동기화합니다.

  2. 소스 브랜치에서 설명한 대로 사용자 사이트의 Source 브랜치를 gh-pages로 설정합니다.