Hugo로 생성한 정적 웹사이트를 GitHub Pages로 호스팅하기

Hugo 프레임워크에 DocDock 테마를 추가하여 정적 웹사이트를 만들고 이를 GitHub 저장소에 올려서 GitHub Pages로 호스팅하는 과정을 정리하였습니다.

1. 제품 소개

Hugo

• 정적 웹사이트를 생성하는 도구.
• Go 언어로 개발됨.

DocDock

• 기술 문서 작성을 위한 Hugo용 테마.
• Learn 테마를 기반으로 함.

GitHub Pages

• 정적 웹사이트 호스팅 서비스를 무료로 제공.
• GitHub 저장소와 직접 연결.
• 개인, 조직, 프로젝트 유형에 따른 페이지 제공.
• 사이트 저장 용량은 최대 1GB.

2. Hugo와 DocDock 설치

다음과 같은 환경에서 설치를 진행하고 이 문서를 작성하였습니다.

• 프로세서: Intel Core i5 (x64 기반)
• 운영체제: Windows 10 (64 비트)

1) Hugo 설치

1. Hugo Releases 페이지에서 다음 파일을 다운로드하고 압축을 풉니다. 이 글을 작성하는 시점의 최신 출시는 0.56.0 버전입니다.

   hugo_x.x.x_Windows-64bit.zip

2. 압축을 푼 폴더를 환경 변수 PATH에 추가합니다.

2) 새 사이트 생성

1. 사이트를 생성하고자 하는 폴더에서 명령 프롬프트 창을 엽니다.

2. 다음과 같이 명령을 실행하여 새 Hugo 사이트를 생성합니다.

   C:\Temp>hugo new site quickstart
   Congratulations! Your new Hugo site is created in C:\Temp\quickstart.
   
   Just a few more steps and you're ready to go:
   
   1. Download a theme into the same-named folder.
      Choose a theme from https://themes.gohugo.io/ or
      create your own with the "hugo new theme <THEMENAME>" command.
   2. Perhaps you want to add some content. You can add single files
      with "hugo new <SECTIONNAME>\<FILENAME>.<FORMAT>".
   3. Start the built-in live server via "hugo server".
   
   Visit https://gohugo.io/ for quickstart guide and full documentation.
   

   위 명령은 quickstart 폴더에 새 사이트를 만듭니다. 이후부터 본문에서 언급하는 폴더들과 명령창에서 실행하는 명령들의 기준 위치는 quickstart 폴더입니다.

3) 테마 DocDock 추가

1. 테마 DocDock을 themes/dockdock 폴더에 추가합니다.

   > git submodule add https://github.com/vjeantet/hugo-theme-docdock.git themes/docdock
   

2. 사이트에 대한 속성을 quickstart\config.toml 파일에서 설정합니다. 사이트 생성 직후의 파일 내용은 아래와 같습니다.

   baseURL = "http://example.org/"
   languageCode = "en-us"
   title = "My New Hugo Site"
   

   위의 내용을 다음 내용으로 교체합니다.

   baseURL = "/"
   relativeURLs = true
   uglyURLs = true
   languageCode = "en-us"
   title = "My New Hugo Site"
   theme = "docdock"
   
   [outputs]
   home = ["HTML", "RSS", "JSON"]
   

URL과 관련된 baseURL, relativeURLs, 그리고 uglyURLs 항목이 제대로 설정되지 않으면 브라우져에서 배치용 컨텐츠인 index.html 파일을 직접 열거나 GitHub Pages에서 호스팅하여 문서를 열 때 테마가 적용되지 않은 상태로 내용이 표시될 수 있습니다. DocDock이 예제로 제공하는 themes\docdock\exampleSite\config.toml 파일에서 더 많은 속성들을 찾아 볼 수 있습니다.

3. 컨텐츠 생성

컨텐츠는 content 폴더 아래에서 Markdown 문법을 사용하여 작성합니다. 폴더의 계층 구조는 웹사이트 좌측 메뉴바의 계층 구조로 나타납니다. 또한 각 폴더의 _index.md 파일에서 작성한 내용은 해당 폴더의 주 화면에 표시됩니다.

1) 컨텐츠 파일 작성

실습을 위하여 content 폴더 아래에 다음 파일들을 만들고 제시한 내용들을 저장합니다.

• _header.md

  화면 좌측 상단에 표시할 문구를 작성합니다.

    QuickStart
  

• _index.md

  홈 화면에서 표시할 문서를 작성합니다.

    ---
    Title: "Home"
    ---
    # Home
  

• ble/_index.md

  ble 폴더의 주 화면에서 표시할 문서를 작성합니다.

    ---
    Title: "Bluetooth Low Energy"
    ---
  

• ble/ble01-intro.md

  ble 폴더의 하위 메뉴로 표시할 문서를 작성합니다.

    ---
    Title: "BLE01 - Introduction"
    ---
  

• ble/ble02-physical-layer.md

  ble 폴더의 하위 메뉴로 표시할 문서를 작성합니다.

    ---
    Title: "BLE02 - Physical layer"
    ---
  

• ml/_index.md

  ml 폴더의 주 화면에서 표시할 문서를 작성합니다.

    ---
    Title: "Machine Learning"
    ---
  

• ml/ml01-intro.md

  ml 폴더의 하위 메뉴로 표시할 문서를 작성합니다.

    ---
    Title: "ML01 - Introduction"
    ---
  

• ml/ml02-linear-regression.md

  ml 폴더의 하위 메뉴로 표시할 문서를 작성합니다.

    ---
    Title: "ML02 - Linear regression"
    ---
  

2) 개발 서버로 웹사이트 검증

1. Hugo 개발 서버를 실행합니다.

   > hugo server
   

2. 브라우져로 아래 주소에 연결합니다.

   http://localhost:1313

3. 화면 왼쪽 사이드바에 메뉴가 나타나고 각각의 메뉴 항목을 클릭하여 위에서 작성한 모든 컨텐츠를 볼 수 있는지 확인합니다.

4. 컨텐츠 배치

content 폴더 아래에서 작성한 컨텐츠를 GitHub Pages 서비스를 통해서 호스팅하려면 먼저 배치용 컨텐츠로 변환해야 합니다. 변환 결과는 public 폴더 아래에 저장되고 public 폴더 아래의 내용을 GitHub 저장소에 올리면 바로 웹으로 서비스됩니다. GitHub 계정의 사용자 이름이 yourname 이라고 하면 GitHub 저장소 주소와 여기에 연결된 웹사이트 주소는 다음과 같습니다.

• GitHub 저장소 주소:

  https://github.com/yourname/yourname.github.io.git
  

• GitHub Pages 웹사이트 주소:

  https://yourname.github.io
  

1) GitHub 저장소를 서브모듈로 추가

GitHub의 웹사이트 저장소를 서브모듈로 public 폴더 아래에 추가합니다.

> git submodule add https://github.com/yourname/yourname.github.io.git public

2) 컨텐츠를 배치용으로 변환

아래와 같이 명령을 실행하여 배치용 컨텐츠로 변환합니다.

> hugo

위 명령이 끝나면 public 폴더에서 배치용 컨텐츠를 찾을 수 있습니다.

3) 배치용 컨텐츠를 GitHub에 올리기

1. public 폴더의 변경 사항을 GitHub 저장소에 올립니다.

   > cd public
   > git add --all
   > git commit -m "Initial commit."
   > git push
   

2. 브라우져를 열고 다음 주소에 연결합니다

   https://yourname.github.io
   

3. 화면 왼쪽 사이드바에 메뉴가 나타나고 각각의 메뉴 항목을 클릭하여 위에서 작성한 모든 컨텐츠를 볼 수 있는지 확인합니다.

참고 자료

• Hugo Quick Start
• Hugo Themes - docDock
• How To Install and Use Hugo, a Static Site Generator, on Ubuntu 14.04
• Hugo docDock Theme - GitHub repository - vjeantet
• HUGO DOCDOCK THEME - GitHub Pages
• What is GitHub Pages?
• Host on GitHub

Written with StackEdit.