본래 네이버 블로그를 사용하는 관계로 네이버 블로그에도 올린 글입니다만, 염치 없게도 올려봅니다.

마크다운으로 쓴 파일을 올릴 곳이 필요할 것 같아 고민하던 중 관리면에서 일반적인 블로그보단 git 을 이용하는 편이 더 좋을 것 같아 github 페이지 (github.io) 에 gitbook 을 올리려고 설정을 해보았습니다.

github 페이지와 gitbook 모두 처음 사용해 보는 데다가 아직 본격적으로 쓰진 않았지만, 설정 해보고 나니 꽤 사용하기 좋을 것 같아서 다른 분들도 한번 써보시라는 의미로 글을 씁니다.

github 페이지에 대하여

일단 github 페이지를 본 적이 없는 분들을 위해 간단히 소개하자면, github 에서 제공하는 무료 정적 호스팅 서비스입니다. 즉 저장소(repository) 에 html 파일등을 올려놓기만 하면 github 에서 웹상에 올려준다는 겁니다.

다만 제약이 있는데, 개인 만을 위한 비공개 페이지를 만들거나 할 순 없습니다. (private 레포를 이용해도 내용이 공개됩니다) 그리고 git 을 이용하다 보니 git 에 익숙하지 않은 분들에겐 좀 불편할 수 있습니다만, 이 글을 보시는 분들은 적어도 저보단 git 을 잘 다루실테니 문제는 없을실 겁니다.

github 페이지를 본격적으로 만들기 전에 알아두셔야 할게(혹은 알아두시면 좋은게) 몇가지 있습니다.

먼저 github 페이지의 종류는 두가지가 있습니다.

  • 사용자 페이지: <username>.github.io 레포 이용하기
  • 프로젝트 페이지: 원하는 레포에서 gh-pages 브랜치 이용 (이용할 브랜치는 설정을 통해 변경 가능)

둘의 차이점은 사용자 페이지에선 master 브랜치를 이용하고, 프로젝트 페이지의 경우는 gh-pages 브랜치를 이용한다는 것 이외에는 없습니다. 다만 사용자 페이지(github.io 레포)에선 master 브랜치만 사용 가능합니다. (브랜치를 못 만든다는 뜻이 아니라, 호스팅용으로 사용할 브랜치를 변경할 수 없다는 뜻입니다)

사용자 페이지 설정 화면

이처럼 github.io 레포에서는 호스팅 소스 브랜치 변경이 불가능(master 브랜치로 고정)합니다.

프로젝트 페이지 설정 화면

반면 프로젝트 페이지를 만들땐 꽤 자유롭습니다. 브랜치 선택도 가능하고, 심지어 master 브랜치 내의 docs 폴더만 지정하는 것도 가능합니다.

github 페이지의 URL

github 페이지의 메인 URL 은 다음과 같습니다.

  • 사용자 페이지: https://<username>.github.io/
  • 프로젝트 페이지: https://<username>.github.io/<해당 레포명>

만약 test 레포의 프로젝트 페이지를 생성하면, 해당 프로젝트 페이지의 메인 URL는 https://<username>.github.io/test 가 됩니다.

사용자 페이지와 프로젝트 페이지를 동시에 이용할 수도 있습니다. 즉, 사용자 페이지가 이미 있는 상태로 study 레포의 프로젝트 페이지를 만들 경우 https://<username>.github.io/ 로 접속할 경우 사용자 페이지로 연결되고, https://<username>.github.io/study/ 로 접속할 경우 study 레포의 프로젝트 페이지로 연결됩니다.

이때 만약 사용자 페이지인 github.io 레포에 study 디렉토리가 존재하고, study 레포의 프로젝트 페이지도 존재할 경우, 즉 겹칠 경우에는 어떻게 될지 글을 쓰다가 갑자기 궁금해져서 실험을 해봤습니다.

실험용 디렉토리 구조:

github.io:
  docs/
    a.html
  study/
    b.html
  index.html

study gh-pages:
  index.html

위와 같이 설정해 두고, github.io/study/ 로 접속해 봤습니다.

결과적으로 github.io/study 로 접속할 경우 study 레포의 프로젝트 페이지로 연결됩니다. 즉 해당 레포명을 가진 레포의 프로젝트 페이지가 존재할 경우, 사용자 페이지 내의 디렉토리보다 프로젝트 페이지가 우선됩니다. (github.io 레포에서 만든 study 디렉토리에만 있는 파일인 github.io/study/b.html 파일을 요청하더라도 404가 뜹니다)
서론이 좀 길었네요. 본격적으로 진행해 보도록 하겠습니다.

Repository 생성하기

okms00909/okms00909.github.io

제 아이디는 okms00909 이니, 레포명은 okms00909.github.io 로 하였습니다. 다만 전 해당 레포에 이미 설정을 해 두었기 때문에, temp 라는 임시 레포를 하나 만들어서 진행하겠습니다.

이 글을 보고 따라하시는 분들은 자신의 <username>.github.io 레포에서 진행하시면 됩니다. (생성하고 나서의 모습이 <username>/<username>.github.io 여야 합니다! 앞의 username 과 레포명에 들어간 username 이 다르면 사용자 페이지로 작동하지 않습니다)

전 사용자 페이지로 진행하지만 프로젝트 페이지로 진행하실 분들은 방법은 같되, 제가 master 브랜치에서 하는 작업을 해당 레포의 gh-pages 브랜치(혹은 자신이 프로젝트 페이지로 설정할 곳) 에서 진행하시면 됩니다.

gitbook 설정하기

(master) $ npm install -g gitbook-cli

먼저 gitbook 을 빌드하는데 필요한 gitbook-cli 모듈을 전역 모듈로 설치해줍시다. (앞으로 브랜치를 바꿀 일이 좀 있기 때문에 브랜치를 표기하도록 하겠습니다. 입력하실 때는 $ 뒷부분만 입력해 주시면 됩니다)

설치가 끝나면, 해당 프로젝트 디렉토리에서 gitbook init 명령어를 실행합니다.

(master) $ gitbook init

실행하고 나면 프로젝트 디렉토리에 README.md 와 SUMMARY.md 파일이 생겨있을 겁니다.

// README.md
# Introduction


// SUMMARY.md
# Summary

* [Introduction](README.md)

현재 상황에서 바로 gitbook build 명령어를 이용해 깃북을 빌드하고 올려도 상관은 없지만, 그럴 경우 자신이 만든 프로젝트 디렉토리 구조와 깃북으로 빌드한 파일들이 뒤섞여서 관리하기 불편해질 수 있습니다.

따라서 마크다운 작성용 브랜치와 깃북으로 빌드한 파일이 올라갈 브랜치를 나누도록 하겠습니다.

(master) $ git add .
(master) $ git commit -m "init gitbook"

(master) $ git branch docs

앞서 gitbook init 으로 만들어진 파일들을 커밋하고, docs 브랜치를 생성했습니다.

이 docs 브랜치가 앞으로 우리가 마크다운 파일들을 작성할때 사용할 브랜치이고, 기존의 master 브랜치는 앞으로 깃북을 빌드하고, 빌드된 html 파일들을 호스팅 하는데 쓰도록 할겁니다.

다만 이는 사용자 페이지 기준이며, 프로젝트 페이지를 생성하실 때에는 기존의 브랜치 (master 등) 에 마크다운 파일들을 작성하시고, gh-pages 브랜치를 새로 생성하셔서 gh-pages 브랜치에서 깃북을 빌드하셔야 합니다.

checkout 하기 전에, 한번 빌드해보도록 하겠습니다. (따라하지 않으셔도 됩니다)

(master) $ gitbook build

빌드하고 나면 _book 디렉토리가 생겨있을 겁니다.

_book/
  gitbook/
  index.html
  search_index.json
README.md
SUMMARY.md

저 _book 디렉토리 내의 파일들이 호스팅 하는데 필요한 파일들이기 때문에, 밖으로 꺼내야 합니다.

(master) $ cp -R _book/* .
gitbook/
index.html
search_index.json
README.md
SUMMARY.md

이 상태로 push 한 뒤, 해당 페이지의 URL('github 페이지의 URL' 에서 다뤘습니다)로 접속하면다음과 같은 화면이 나옵니다.

push 하고 github 페이지에 적용되는데 시간이 좀 걸릴 수 있다는 점 참고 바랍니다.

빌드된 화면

이제 빌드가 어떤식으로 되는지 알아봤으니, docs 브랜치로 이동해서 마크다운 파일을 수정 및 추가해 봅시다.

파일 추가하기

먼저 아까 만들어놓은 docs 브랜치로 이동합니다.

(master) $ git checkout docs

현재 docs 브랜치의 디렉토리 구조는 다음과 같습니다.

README.md
SUMMARY.md

파일을 추가해 보겠습니다.

docs/
  asdf/
    index.md
    a.md
    b.md
  qwer/
    index.md
    a.md
  ghjk.md
  zxcv.md
REAMDE.md
SUMMARY.md

docs 디렉토리를 만들고 (브랜치 이름과 헷갈리시지 않도록 주의 바랍니다) 그 안에 마크다운으로 파일 몇개를 작성해 보았습니다. 예시를 위해 좀 많이 만들었는데, 원하시는 대로 만드시면 됩니다.

이제 SUMMARY.md 파일을 다음과 같이 변경 합니다.

# Summary

- [Introduction](README.md)

- [ASDF](docs/asdf/index.md)
  - [a](docs/asdf/a.md)
  - [b](docs/asdf/b.md)

- [QWER](docs/qwer/index.md)
  - [a](docs/qwer/a.md)

- [ZXCV](docs/zxcv.md)

- [GHJK](docs/ghjk.md)

gitbook 은 summary 파일을 읽고 목록에 있는 파일들을 빌드하기 때문에 추가하고 싶은 파일이 있으면 summary에 반드시 추가해야 합니다.

이제 커밋 후 master 브랜치로 이동해서 빌드하고 push 해 봅시다.

(docs) $ git add .
(docs) $ git commit -m "add files"

(docs) $ git checkout master

(master) $ git merge docs
(master) $ gitbook build
(master) $ cp -R _book/* .
(master) $ rm -r _book/

(master) $ git add .
(master) $ git commit -m "Update"
(master) $ git push origin master

이 과정을 마치고 난 후 github 페이지의 모습은 다음과 같습니다.

image.png

다만 이 과정은 좀 귀찮으니, 편하게 바꿔봅시다.

편하게 gitbook 빌드하기

이제 기존의 작업 -브랜치 변경하고, 빌드하고, 파일 꺼내고, 커밋하고, 푸시하고, 브랜치 다시 변경하는- 을 좀 더 편하게 할 수 있도록 스크립트를 만들어 봅시다.

일단 docs 브랜치로 checkout 합시다.

(master) $ git checkout docs

그 후, publish_gitbook.sh 파일을 추가합니다. 내용은 다음과 같습니다.

git checkout master
git merge docs

gitbook build

cp -R _book/* .
rm -r _book/

git add .
git commit -m "Update"
git push origin master

git checkout docs

앞서 '마크다운 파일 추가하기' 에서 gitbook 빌드할때 입력했던 명령어들입니다. 달라진 점은 docs 브랜치에서 바로 실행할 수 있도록 처음에 master 브랜치로 checkout 했다가 끝나면 docs 브랜치로 돌아오도록 하였습니다.

그 후 다음 명령어들을 실행합니다.

(docs) $ git add .
(docs) $ git commit -m "add script"
(docs) $ git checkout master

(master) $ git merge docs
(master) $ git checkout docs

추가한 publish_gitbook 스크립트를 커밋하고, master 브랜치에서 merge 하여 master 브랜치에도 스크립트를 추가한 후(실행 중 파일이 사라져서 멈추는 일이 없도록) 다시 docs 브랜치로 checkout 했습니다.

한번 테스트를 위해 실행해보도록 하겠습니다.

(docs) $ .\publish_gitbook.sh

문제 없이 실행이 완료되면 이제 설정 끝입니다.
이제 앞으로는 docs 브랜치에서 마크다운을 작성하고, 명령어 한줄로 github 페이지에 gitbook 을 빌드해 올릴 수 있습니다.

그럼 이만 마치겠습니다. 부족한 글 봐주셔서 감사합니다.

이 글은 다음 글들을 참고하여 작성하였습니다:

http://dogfeet.github.io/articles/2012/github-pages.html
https://beomi.github.io/2017/11/20/Deploy-Gitbook-to-Github-Pages/