Hugo - GitHub에 호스팅하기

원본 문서

GitHub는 GitHub 페이지 서비스를 통해 GitHub 저장소에서 직접 개인, 조직 또는 프로젝트 페이지를 위한 무료이며 빠른 SSL을 통한 정적 호스팅을 제공합니다.

전제

1. Git 2.8 혹은 그 이상의 버전이 설치되어 있어야 합니다.
2. GitHub 계정이 있어야 합니다. GitHub에 무료로 회원가입하십시오.
3. 게시가 준비된 Hugo 웹사이트가 있거나 빠른 시작을 완료해야 합니다.

GitHub 페이지 유형

GitHub 페이지에는 두 가지 유형이 있습니다.

1. 사용자/조직 페이지 (https://<사용자명|조직명>.github.io)
2. 프로젝트 페이지 (https://<사용자명|조직명>.github.io/<프로젝트명>)

사용할 사이트 유형을 결정하려면 GitHub 페이지 문서를 참조하십시오. 아래 방법 중 사용할 방법을 결정합니다.

사용자/조직 페이지 사이트를 만들려면 아래 GitHub 사용자 및 조직 페이지 섹션에서 단일 방법을 따르십시오.

프로젝트 페이지 사이트를 만들려면 아래 GitHub 프로젝트 페이지 섹션에서 방법을 선택하십시오.

GitHub 사용자 및 조직 페이지

GitHub Pages 문서에서 언급하듯이 프로젝트 페이지 외에도 사용자/조직 페이지를 호스팅할 수 있습니다. 다음은 GitHub 페이지 웹사이트와 사용자 및 조직의 주요 차이점입니다.

1. 생성된 콘텐츠를 호스팅하려면 <사용자명>.github.io를 사용해야 합니다.
2. master 분기의 콘텐츠는 GitHub 페이지 사이트를 게시하는 데 사용됩니다.

Hugo 파일과 생성된 콘텐츠가 두 개의 다른 저장소에 공개되므로 설정이 훨씬 간단합니다.

단계별 지침

1. GitHub에 <프로젝트명> (예: blog) 저장소를 만듭니다. 이 저장소에는 Hugo의 콘텐츠 및 기타 소스 파일이 포함됩니다.
2. GitHub에 <사용자명>.github.io 저장소를 만듭니다. Hugo 웹사이트의 완전히 렌더링된 버전이 포함될 저장소입니다.
3. git clone <프로젝트-URL> && cd <프로젝트명>
4. 기존 Hugo 프로젝트를 새로운 로컬 <프로젝트명> 저장소에 붙여넣습니다. 웹사이트가 로컬에서 작동하는지 확인하고 (hugo server 혹은 hugo server -t <테마명>) 브라우저로 http://localhost:1313을 엽니다.
5. 결과에 만족하면 다음을 진행합니다.
   • Ctrl+C를 눌러 서버를 종료하십시오.
   • 계속 진행하기 전에 rm -rf public을 실행하여 public 디렉터리를 완전히 제거하십시오.
6. git submodule add -b master git@github.com:<사용자명>/<사용자명>.github.io.git public. 이는 Git 하위 모듈을 만듭니다. 이제 hugo 명령을 실행하여 사이트를 public으로 빌드하면 만들어진 public 디렉터리는 다른 원격 출처(예: 호스팅된 GitHub 저장소)를 갖게 됩니다.

스크립트 작성

거의 끝났습니다. 다음 단계를 자동화하려면 deploy.sh 스크립트를 작성하십시오. chmod +x deploy.sh로 실행 가능하게 만들 수도 있습니다.

다음은 deploy.sh 스크립트의 내용입니다.

#!/bin/sh

# 명령이 실패하면 배포가 중지됩니다.
set -e

printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

# 프로젝트를 빌드합니다.
hugo # 테마를 사용 중이라면 `hugo -t <테마명>`으로 대체하십시오.

# public 폴더로 이동합니다.
cd public

# Git에 변경 사항을 추가합니다.
git add .

# 변경 사항을 커밋합니다.
msg="rebuilding site $(date)"
if [ -n "$*" ]; then
    msg="$*"
fi
git commit -m "$msg"

# 소스를 푸시하고 저장소를 빌드합니다.
git push origin master

그런 다음 ./deploy.sh "임의 커밋 메시지"를 실행하여 <사용자명>.github.io에 변경 사항을 보낼 수 있습니다. <프로젝트명> 저장소에 변경 사항을 커밋할 수도 있습니다.

GitHub 프로젝트 페이지

기본 GitHub 페이지 URL(예: <사용자명>.github.io/<프로젝트명>)을 사용하는 경우 사이트 구성의 baseURL 키값이 GitHub 페이지 저장소의 전체 URL을 반영하는지 그리고 사용자 지정 도메인이 아닌지 확인하십시오.

master 분기의 /docs 폴더에서 프로젝트 페이지 배포

GitHub 페이지 문서에 설명된 대로 master 분기의 docs/ 폴더에서 배포할 수 있습니다. Hugo에서 이 기능을 효과적으로 사용하려면 사이트의 config.toml 및 config.yaml에서 Hugo publish 디렉터리를 각각 변경해야 합니다.

publishDir = "docs"

publishDir: docs

hugo를 실행한 뒤, master 분기를 원격 저장소로 푸시하고 문서의 웹사이트 소스로 docs/ 폴더를 선택하십시오. GitHub 프로젝트에서 다음을 수행하십시오.

1. 설정(Settings) → GitHub 페이지(GitHub Pages)로 이동하십시오.
2. 소스(Source)에서 “master 분기 /docs 폴더(master branch /docs folder)“를 선택하십시오. 이 옵션을 사용하지 않으면 프로젝트 루트에 docs/ 폴더가 없을 수 있습니다.

docs/ 옵션은 가장 간단한 방법이지만 사이트 구성에서 게시 디렉터리를 설정해야 합니다. 현재 GitHub 페이지를 master의 다른 디렉터리에서 게시하도록 구성할 수 없으며 모든 사용자가 버전 제어의 소스 파일과 동시에 출력 사이트를 선호하는 것은 아닙니다.

gh-pages 분기에서 프로젝트 페이지 배포

GitHub 페이지에 master 분기를 게시된 사이트로 취급하거나 별도의 gh-pages 분기를 가리키도록 지시할 수도 있습니다. 후자의 접근법은 조금 더 복잡하지만 몇 가지 장점이 있습니다.

1. 소스와 생성된 웹사이트를 서로 다른 분기에 유지하므로 두 버전에 대한 버전 관리 기록을 유지합니다.
2. 앞의 docs/ 옵션과 달리 기본 public 폴더를 사용합니다.

gh-pages 분기 준비

이 단계는 한 번만 수행하면 됩니다. upstream을 원격 이름으로 교체하십시오. 예: origin.

public 폴더 추가

먼저 프로젝트 루트의 .gitignore 파일에 public 폴더를 추가하여 디렉터리가 master 분기에서 무시되도록 하십시오.

echo "public" >> .gitignore

gh-pages 분기 초기화

이제 gh-pages 분기를 빈 고아 분기로 초기화할 수 있습니다.

git checkout --orphan gh-pages
git reset --hard
git commit --allow-empty -m "Initializing gh-pages branch"
git push upstream gh-pages
git checkout master

빌드 및 배포

이제 Git의 작업 트리 기능을 사용하여 gh-pages 분기를 공용 폴더로 체크아웃하십시오. 기본적으로 작업 트리를 사용하면 동일한 로컬 저장소의 여러 분기를 다른 디렉터리에서 체크아웃할 수 있습니다.

rm -rf public
git worktree add -B gh-pages public upstream/gh-pages

hugo 명령을 사용하여 사이트를 재생성하고 gh-pages 분기에서 생성된 파일을 커밋하십시오.

hugo
cd public && git add --all && git commit -m "Publishing to gh-pages" && cd ..

로컬 gh-pages 분기의 변경 사항이 올바르게 보이면 원격 저장소로 푸시하십시오.

git push upstream gh-pages

gh-pages를 게시 분기로 설정

gh-pages 분기를 게시 분기로 사용하려면 GitHub UI 내에서 저장소를 설정해야 합니다. GitHub가 이 분기를 생성한 것을 인식하면 자동으로 발생합니다. GitHub 프로젝트 내에서 분기를 수동으로 설정할 수도 있습니다.

1. 설정(Settings) → GitHub 페이지(GitHub Pages)로 이동하십시오.
2. 소스(Source)에서 “gh-pages 분기(gh-pages branch)“를 선택하고 저장하십시오. 이 옵션을 사용하지 않으면 아직 분기를 생성하지 않았거나 로컬 시스템에서 GitHub의 호스팅된 저장소로 분기를 푸시하지 않은 것입니다.

잠시 기다리면 GitHub 페이지 사이트에 업데이트된 내용이 표시됩니다.

스크립트 작성

이러한 단계를 자동화하기 위해 다음 내용과 같이 스크립트를 작성할 수 있습니다.

#!/bin/sh

if [ "`git status -s`" ]
then
    echo "The working directory is dirty. Please commit any pending changes."
    exit 1;
fi

echo "Deleting old publication"
rm -rf public
mkdir public
git worktree prune
rm -rf .git/worktrees/public/

echo "Checking out gh-pages branch into public"
git worktree add -B gh-pages public upstream/gh-pages

echo "Removing existing files"
rm -rf public/*

echo "Generating site"
hugo

echo "Updating gh-pages branch"
cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)"

#echo "Pushing to github"
#git push --all

작업 디렉터리에 보류 중인 변경 사항이 있으면 중단되며 기존의 모든 출력 파일이 제거됩니다. 스크립트를 취향에 맞게 조정하십시오. 예를 들어, 푸시하기 전에 gh-pages 분기를 볼 필요가 없는 경우 원격 저장소에 대한 최종 푸시를 포함하십시오.

master 분기에서 프로젝트 페이지 배포

master를 게시 분기로 사용하려면 렌더링된 웹사이트가 GitHub 저장소의 루트에 있어야 합니다. public 디렉터리를 루트로 하여 GitHub 저장소를 생성한다는 점을 제외하고 단계는 gh-pages 분기의 단계와 유사해야 합니다. 이것은 gh-pages 분기와 동일한 저장소 내에서 소스와 출력을 별도의 버전 관리 분기로 유지하는 것과 동일한 이점을 제공하지 않습니다.

또한 GitHub UI 내에서 master를 게시 가능한 분기로 설정해야 합니다.

1. 설정(Settings) → GitHub 페이지(GitHub Pages)로 이동하십시오.
2. 소스(Source)에서 “master 분기(master branch)“를 선택하고 저장하십시오.

사용자 지정 도메인 사용

GitHub 페이지 사이트에 사용자 지정 도메인을 사용하려면 static/CNAME 파일을 작성하십시오. 사용자 지정 도메인 이름은 CNAME 내부에서 유일한 내용이어야 합니다. 내부 사이트는 정적이므로 GitHub 페이지의 요구 사항인 게시된 사이트의 루트에 CNAME 파일이 포함됩니다.

자세한 내용은 사용자 지정 도메인의 공식 문서를 참조하십시오.