GitHub와 Quarto Book을 연동하자
GitHub와 Quarto Book을 연동하자
GitHub와 Quarto로 작성한 Book을 연동하고 GitHub Action으로 자동 빌드 및 배포하는 과정을 정리했다.
전제 조건
- GihHub에 계정이 있고 기본적인 사용 방법을 숙지하고 있다.
- R-Studio를 사용할 수 있다.
- Quarto를 이용하여 문서(Website, Blog, Book 등)를 작성할 수 있다.
GitHub 작업
GitHub에 Repository를 생성하는 방법은 다양할 수 있으나 개인적으로 진행하는 방법은 아래와 같다. GitHub site → Repositories → New를 통해 생성한다.
개인 취향에 따라 .gitignore 파일을 추가한다.
Repository를 생성하고 나면 local 폴더에 복사(clone) 한다. 아래는 GitHub Desktop을 이용한 경우이다.
RStudio 작업
RStudio에서 새 프로젝트를 생성한다.
프로젝트 생성 시 반드시 빈 폴더를 생성한다. 파일이 있는 기존 폴더를 사용할 경우 아래와 같은 경고 문구와 함께 프로젝트는 생성되지 않는다.
임시 폴더명을 설정하고 프로젝트를 생성한다.
RStudio를 종료하고 생성된 프로젝트의 모든 파일을 GitHub와 연결된 폴더로 이동하다.
필요하다면 .Rproj 파일을 적당한 이름으로 변경한다. .Rproj 파일을 실행하여 RStudio를 연다.
Quarto Book 작성
GitHub Action을 이용하기 위해 _quarto.yml 파일을 수정한다. 자동 빌드된 후 산출물이 저장될 디렉토리를 아래와 같이 설정한다.
_quarto.yml 파일 내 title, author 정도만 간단히 수정하고 지금까지 진행된 파일을 GitHub에 올린다.
GitHub와 Quarto 연동
GitHub Desktop을 사용한다면 다음과 같이 추가된 파일이 commit 되어 있을 것이다. push 한 후 GitHub에 정상적으로 업로드 되었는지 확인하다.
이제 main 브랜치에 내용이 수정되면 자동으로 빌드 후 산출물을 /docs 폴더에 저장된다. 이 저장된 산출물을 gh-pages 브랜치로 옮겨 인터넷을 통해 볼 수 있도록 배포하는 설정을 한다.
gh-pages 브랜치 생성하기
아래 명령을 통해 gh-pages 브랜치를 생성한다.
실행이 완료된 후 GitHub에서 gh-pages 브랜치가 정상적으로 생성되었는지 확인한다.
GitHub에서 Jekyll을 사용하지 않도록 아래와 같이 .nojekyll 파일을 추가한다.
1
copy NUL .nojekyll
GitHub Action을 .github/workflows/publish.yml 경로에 아래와 같이 작성한다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
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
- uses: r-lib/actions/setup-r@v2
- uses: r-lib/actions/setup-r-dependencies@v2
with:
packages:
any::rmarkdown
any::knitr
- uses: r-lib/actions/setup-tinytex@v1
- 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: $
Action이 정상적으로 작성되었다면 Actions 메뉴를 통해 동작 여부를 확인할 수 있다.
Action이 정상 수행되면 /docs 폴더가 생성되고 산출물이 gh-pages 브랜치로 복사되어 배포가 된다. Settings 메뉴를 통해 배포된 결과물을 확인할 수 있다. Action 수행 중 상황에 따라 다양한 오류가 발생할 수 있는데123 인터넷 검색을 통해 하나씩 해결해야 한다.
publish.yml이 정상적으로 동작한다면 배포된 사이트에 접속하여 내용을 확인할 수 있다.
마지막으로 파일을 수정하여 자동 빌드 및 배포가 되는지 확인한다.
_EOF_