Quarto 원고 배포
개요
이 페이지는 원고 작성 튜토리얼의 연속입니다. 템플릿 리포지토리를 클론하고 변경을 적용했으며 Quarto가 생성한 미리보기에 만족한다고 가정합니다.
Quarto 원고 배포란 로컬 컴퓨터에서 보고 있던 미리보기를 웹에서 누구나 볼 수 있도록 공개하는 과정입니다.
템플릿 원고에는 리포지토리의 GitHub Pages 사이트에 원고를 배포하는 데 필요한 기본 구조가 포함되어 있습니다. 원고 웹사이트를 배포하는 것은 변경 사항을 리포지토리에 푸시하는 것만큼 간단합니다.
Quarto 원고는 Quarto 웹사이트의 특수한 형태이므로, Quarto 웹사이트를 배포하는 방법으로 그대로 배포할 수 있습니다. GitHub Pages가 맞지 않다면 배포 문서에서 다른 옵션을 알아보세요.
이 페이지에서는 GitHub Actions의 읽기/쓰기 권한을 허용하도록 GitHub 리포지토리 설정을 하나 변경한 뒤, 배포 과정을 안내합니다.
GitHub Actions 권한 부여
템플릿 원고에는 .github/workflows/publish.yml에 GitHub Action이 구성되어 있습니다. 이 액션은 main 브랜치에 푸시가 있을 때 트리거되어 원고를 렌더링하고 원고 웹사이트 소스를 gh-pages 브랜치에 올립니다.
액션이 gh-pages 브랜치에 쓰기 권한을 갖도록 하려면 리포지토리 설정을 하나 변경해야 합니다. 리포지토리에서 Settings > Actions > General > Workflow Permissions로 이동한 뒤 “Read and Write Permissions”를 체크하세요.
.github/workflows/publish.yml의 GitHub Action은 Python이나 R 같은 계산 환경을 설정하지 않으므로 코드를 실행할 수 없습니다.
Jupyter Notebook(.ipynb)은 출력이 포함되어 있어 별도의 처리가 필요하지 않습니다. 하지만 원고에 Quarto 파일(.qmd)이 포함되어 있다면, _freeze 디렉터리에 저장된 계산 출력을 업데이트하기 위해 먼저 로컬에서 렌더링해야 합니다.
GitHub Action에서 코드도 실행하고 싶다면 GitHub에 배포하기 문서의 코드 실행 섹션을 참고하세요.
푸시로 배포하기
이 원고를 GitHub Pages에 배포하는 것은 변경 사항을 커밋하고 푸시하는 것만큼 간단하지만, 먼저 전체 렌더링을 권장합니다. 원고 디렉터리에서 터미널에 다음을 실행하세요.
Terminal
quarto renderRStudio의 Render 버튼은 quarto render가 아니라 quarto preview를 실행합니다. 터미널에서 quarto render를 직접 실행해야 합니다.
quarto preview는 필요한 출력만 생성하지만, quarto render는 모든 출력(모든 논문 포맷과 원고 웹사이트)을 생성합니다. GitHub Action에서도 이 명령이 실행되므로, 로컬에서 먼저 확인하는 것이 GitHub에서 문제를 피하는 좋은 방법입니다.
렌더링이 문제없이 완료되면 변경 사항을 스테이징하세요.
렌더링 과정에서 Quarto가 만드는 일반적인 파일 중 버전 관리에 포함할 필요가 없는 항목을 무시하도록 .gitignore에 몇 줄을 추가했습니다. 따라서 스테이징할 파일은 노트북과, 경우에 따라 _freeze 디렉터리의 파일이어야 합니다.
GitHub에 푸시하고 싶지 않은 파일을 프로젝트에 추가했다면, 커밋에 스테이징하지 않았는지 다시 확인하세요.
변경 사항을 커밋하고 GitHub에 푸시하세요.
푸시하면 GitHub에서 액션이 트리거되는 것을 볼 수 있습니다. “Quarto Publish”는 사이트를 렌더링해 gh-pages 브랜치로 푸시하는 액션이고, “pages-build-deployment”는 gh-pages 브랜치를 GitHub Pages URL로 배포하는 GitHub의 액션입니다.
두 액션이 모두 완료되면 리포지토리의 GitHub Page로 이동하세요.
GitHub의 리포지토리 Settings > Pages에서 GitHub Pages 웹사이트 주소를 확인할 수 있습니다.
이제 원고가 배포되었습니다!
다음은?
이제 Quarto 원고의 전체 워크플로(콘텐츠 작성, 원고 미리보기, GitHub Pages에 배포)를 모두 수행했습니다. 더 자세히 알아보고 싶다면 다음 단계에서 권장 사항을 확인하세요.