GitBook을 아시나요? +GitHub연동

개발자 분들이라면 git에 관련된 키워드는 익숙하실 수밖에 없는데요.

문서화 또한 익숙하시겠죠?

많은 개발자분들은 개발하며 겪은 에러나, 최신 기술 트렌드등 기타 다양한 것들을 공유하고 있습니다.

이렇게 정보들을 공유하기 위해 다양한 플랫폼을 이용하고 있는데요, 대표적으로 벨로그, 티스토리, 직접 제작한 웹사이트 등이 있습니다.

저 또한 벨로그와 티스토리를 사용해 봤고 현재는 티스토리를 사용하고 있습니다.

그러다가 GitBook이라는 것을 발견하고 사용해보면서 소개해드리고자 글을 적게 되었습니다.

 

저처럼 다양한 정보들을 좀 더 체계적으로 문서화하고 싶고 마크다운 언어도 사용하고 싶고(티스토리는 마크다운 언어가 잘 안 되어있어요ㅠㅠ) GitHub 잔디도 심고 싶으시다면 바로 이 글을 참고해주시면 되겠습니다! 

 

 

 

다시 본론으로 돌아가서 GitBook에 대해 소개해드리도록 하겠습니다.

GitBook은 공식문서에서는 이렇게 소개하고 있습니다.

GitBook은 모든 것을 문서화할 수 있는 최신 문서 플랫폼입니다.

GitBook공식문서

Introduction to GitBook - GitBook Documentation

 

 

바로 사용방법을 알려드리도록 하겠습니다.

 

 

0. GitHub에 GitBook용 레포를 만든다.

- 본인 GitHub에 빈 레포지토리를 하나 만들어주세요.

- GitBook에 먼저 글을 작성하고 연동도 가능합니다. 다만 레포가 있어야 연동을 할 수 있으니 먼저 만드는 것을 추천드립니다.

 

 

 

1. 홈페이지에 접속한다.

https://www.gitbook.com/

GitBook - Where technical teams document.

 

 

 

접속하면 아래와 같은 화면이 나옵니다.

이곳에서 로그인을 해주세요! GitHub 계정으로 로그인이 가능합니다 :)

 

 

 

 

1.1 GitBook에 사용될 이름만들기

- 여기서 적어주는 name은 나중에 도메인 주소가 됩니다 (물론 바꾸실수도있어요)

예) {name}.gitbook.io/{워크스페이스이름}

 

 

 

 

- 다 작성했으면 Continue를 눌러줍니다.

 

 

 

1.2 초대메일 보내기

- 다른 구성원들을 초대할 수 있는 기능이에요! 

저는 혼자 사용할거라 Close를 눌러줬습니다.

 

 

2. 워크스페이스 만들기.

 

다만들고 들어오면 이런 화면이 나옵니다.

여기서 워크스페이스를 만들 수 있어요.

좌측 슬라이더 아래쪽에 + 표시를 누르셔도 되고

NewSpace버튼을 누르셔도 됩니다.

 

 

 

아래쪽의 플러스 버튼을 클릭하면 

New Space, New Collection을 생성할 수 있습니다.

여기서 저는 New Space를 눌러주도록 하겠습니다.

 

 

 

 

3. 생성된 워크스페이스 살펴보기

워크스페이스를 생성하면 이런 모습인데요.

개발자라면 익숙하실 마크다운 문법의 형태로 텍스트를 작성할 수 있습니다.

 

 

이것저것 눌러보시면 금방 적응할 정도로 쉬운 UI로 구성되어 있습니다.

다양한 기능들이 있지만 제가 중점적으로 알려드리고 싶은 것은 GitHub과의 연동이기 때문에 그 부분을 중점으로 다뤄보도록 하겠습니다.

 

 

 

4. GitHub 연동하기

- Sync with GitHub / GitLab 버튼을 눌러줍니다.

 

 

 

- 또는 더보기 버튼을 눌러 진입 후

- Synchronize with Git을 눌러줍니다.

 

 

 

4.1 GitHub을 선택하고 Configure클릭

 

 

 

 

4.2 Connect with GitHub를 클릭해 본인 계정과 연동해줍니다.

 

 

 

 

4.3 계정과 잘 연동되었다면 Select account를 누르면 본인 계정이 나옵니다.

 

 

 

4.4 미리 만들어둔 GitBook용 레포지토리를 선택해줍니다.

 

 

 

 

4.5 브랜치도 선택해줍니다. 저는 gitbook이라는 브랜치를 따로 만들었습니다. 

- main을 바로 사용하셔도 됩니다!

 

 

 

 

4.6 원하는 방법으로 연동 선택하기.

GitHub to GitBook

- 만약 깃헙에 작성했던 글이 있다면 그걸 깃북으로 옮겨줍니다.

 

GitBook to GitHub

- 깃북으로 먼저 문서를 작성하고 있었다면 그걸 깃헙 레포로 옮겨줍니다.

 

 

 

이 과정을 마치고 나면 깃헙과 연동은 끝입니다. 짝짝짝~

 

 

 

 

5. Publish

- 상단의 Publish 버튼을 눌러주면 이제 웹상에서 작성한 문서를 저장소에 보내거나, 저장소에 있는 문서를 웹에 보여주게 됩니다.

 

 

 

 

 

- Public을 눌러줍니다.

 

 

 

 

- Public을 누르고나면 이제 공유할 수 있는 깃북 주소가 나오게됩니다.

 

 

 

 

6. GitHub에서 살펴보기

- 깃북에서 문서를 작성하고 깃헙과 연동하는 경우 저처럼 자동으로 readme파일과 폴더구조를 형성해줍니다.

- 여기서 중점적으로 봐야 할 것은 summary.md 파일입니다.

 

 

이 파일 안에 목차를 적어줘야 워크스페이스에서 폴더로 정돈된 목차를 구성할 수 있습니다.

https://docs.gitbook.com/getting-started/git-sync/content-configuration#summary

Content Configuration - GitBook Documentation

‌# Summary​

## 제목을 사용하여 이와 같은 페이지 그룹을 만드세요.

* [첫 페이지 제목](page1/README.md)    
    * [일부 하위 페이지](page1/page1-1.md)    
    * [일부 하위 페이지](part1/page1-2.md)

* [두 번째 페이지 제목](page2/README.md)    
    * [일부 하위 페이지](page2/page2-1.md)    
    * [일부 하위 페이지](part2/page2-2.md)    

## 두 번째 페이지 그룹

* [또 다른 페이지](another-page.md)

공식문서를 참고하시면 됩니다.

 

 

 

6.1 깃헙에서 문서를 작성할 경우

- 동일하게 폴더를 생성하고 md파일을 만들어 문서를 작성합니다.

- 각 폴더마다 분류하고 싶다면 폴더마다 readme.md 파일을 만들어야 합니다.

- 그리고 동일하게 summary.md 에서 목차를 구성해주면 됩니다.

- 마지막 push ~

 

주의할 점으로는 깃헙에서 푸시할 경우 깃북에서 자동으로 폴더구조를 만들지 않으니 readme, summary 파일에서 네이밍 실수나 오타가 있다면 잘 나오지 않을 수 있습니다! 

 

 

 

 

7. 완성

- 이제 모든 것이 연동되었습니다.

- 깃북에서 글을 쓰고 merge또는 pr 하셔도 되고

- 깃헙에서 push 하셔도 됩니다.

 

아직 깃북을 만든 지 얼마 되지 않아 글이 별로 없는 상태지만

벨로그나 티스토리보다 더 정돈된 것 같아 보기 좋은 것 같습니다 ㅎㅎ

기업에서 문서정리로도 많이 쓰인다고 하는데 정말 그 용도로 딱인 것 같네요.

별거 없는 연동 방법이지만 저처럼 사용하실 분들을 위해 적어봤습니다

 

모두 재미난 기록 즐기세요 ~.~