깃허브로 깃북 사용해보기 [git-book 사용하는 법]

메가테라에서 진행하는 프론트 엔드 생존 코스를 등록하며 깃 북으로 개념을 정리할 일이 생겨서 깃 북을 이리저리 써보았는데 깃 허브와 연동이 되어서 장점도 있지만 구조를 파악하느라 꽤나 애먹었다. 그래서 한 번 정리해보려고 한다.

Git-book 이란?

말 그대로 하나의 책이라고 생각하면 편하다. 책 처럼 작성해서 볼 수 있고 인덱스도 있어서 목차간 이동도 편리하고 깃 북 앱을 설치하여 에디터를 이용하거나 직접 마크다운 형식의 문서를 작성하여 깃북을 사용해볼 수 도 있다.

 

1. Space와 Page 차이에 대해 알기 

깃북을 하면서 가장 먼저 알면 좋은 것은 바로 space와 page 이다. 아래 사진에 보이는 New Space 를 클릭하면 새로운 페이지를 작성할 수 있는데 이것을 작성해서 원래 작성하던 스페이스에서 링크를 걸어줄 수 있다.

하지만 이것은  space는 하나의 독립적인 작업 단위 한 권을 의미한다고 보면 편리하다. 즉 링크를 걸어줄 수 는 있지만 이것은 한 책에서 다른 책으로 이동하는 링크를 건 것이지 책안에서 챕터를 분류해준 것이 아니다. 

챕터를 나누고 싶다면 동일한 space 내에서 아래와 같이 New Page를 클릭해주어야한다.

즉 Space 는 한 권 두 권의 권과 비슷하고 Page 는 1 장 2 장의 장과 비슷하다고 생각하면 편하다.

git-book을 만들때 Page를 추가해주어야하는 이유는 저렇게 해놓음으로써 내가 연동해놓은 repository 안에서 파일들이 만들어진다.

2. 직접 마크다운으로 문서를 작성해 챕터 안 하위 챕터를 만들고 싶을때

아래 사진과 같이 프론트엔드 개발환경xxx 라는 상위 파일 아래에 여러 챕터가 있는 것을 볼 수 있다.

그 안에서 또 TypeScript라는 챕터 안에서 화살표로 하위 태그가 있음을 알 수 있는데 

깃북 에디터에서는 아래처럼 플러스 버튼 하나로 간단하게 원하는 위치에서 추가해주고 삭제해 줄 수 있다.(깃북 에디터에서는 뭐든 문제가 없다.)

하지만 직접 에디터로 문서를 작성하면 꽤나 난감하다.

우선 깃 북은 각 타이틀 파일을 README.md 파일로 인식한다. (그렇게 작동 안하도록 작성해줄 수 도 있지만 그럴 경우 깃북 editor로 수정을 한번이라도 해버리면 꽤나 꼬이는 것 같다.) 따라서 위처럼 '프론트엔드 개발 환경' 이라는 이름의 대단원(챕터) 타이틀 페이지를 만들고 싶다면

1. 파일을 넣어둘 폴더를 하나 생성한다. 이 폴더는 대단원의 파일들을 가지고 있을 것이다.

2. 폴더에서 README.md 파일을 만든다. 여기서 README 파일은 폴더(챕터)의 제목과 소개 내용을 가지고 있으면 된다.

3. SUMMARY.md 에서 파일을 순서별로 정리해준다. SUMMARY.md 가 각 파일들의 순서와 구조를 파악해 준다.

아래처럼 파일들을 만든 후

깃북의 타이틀과 목차를 가지고 있어야 하므로 최상위 파일에 README 와 SUMMARY.md 가 존재하고

1 주차 챕터와 2 주차 챕터가 필요해 폴더 2개를 만든 후 각각 챕터 표지 처럼 사용할 README를 만들어주었다.

서머리는 아래처럼 순서를 정해주었다.

[목차이름](파일경로) 형식으로 넣으면 

목차이름 이 적히고 괄호속의 링크 파일이 깃북에서 열린다. 

3. SUMMARY.md  ,목차

위에서 설명했듯이 SUMMARY.md 파일은 각 페이지의 순서와 구성을 잡아준다.

목차의 제목은 위 파일에서 보는 것 처럼 설정할 수 있고 각 파일의 제목은 마크다운 형식으로 # 제목 의 형태로 넣어주면 된다.

요약

에디터를 이용하는 것이 훨씬 훨씬 편하지만 굳이 오프라인에서 작업을 한 뒤 깃허브로 올려 동기화를 하고 싶다면 아래 참고사항을 기억하면된다.

1. 각 파일들의 목차는 SUMMARY로 지정해준다. 

2. 이때 SUMMARY 파일에서 각 단원의 제목이 되는 페이지들은 반드시 README.md 로 경로를 지정해준다. 하위 단원은 폴더를 새로 생성해서 README.md 를 만든 후 지정해준다.

3. 하위 경로에서 또 하위 경로를 가고 싶다면 tab으로 구분해주면 된다.

이렇게 해두면 경로에 따라 깃북이 알아서 이동 경로를 보여준다.

마지막 팁 (꾸미기, 커스텀하기)

깃북에 약간의 커스텀을 해줄수 도 있다.

상단의 Customize 버튼을 클릭해서 원하는데로 바꾸어 주자. 나는 hover의 색깔을 바꾸어주었다.

 

마지막으로 알아두면 좋은 점

단순해보이지만 위의 규칙을 지키지 않아도 깃북이 만들어지긴 만들어진다 그러나 깃북 에디터가 만드는 방식을 최대한 비슷하게 만들었기 때문에 깃북에디터에서 수정하더라도 오프라인에서 작업한 뒤 깃허브에 올린 것과 가장 오차가 적은 방법을 파악한다고 한참 애먹었다. 깃북을 사용한다면 에디터나 오프라인 작업 둘 중 반드시 하나의 방식만으로 일관성있게 작업하길 바란다. 그렇지 않으면 계속 서로 동기화맞춰주고 직접 파일들도 수정해주어야해서 너무 피곤하다.

아래에는 참고할만한 깃 북 링크를 남긴다.

 

깃 북 참고할만한 양식

GitHub - Seouldream/frontend-survival: 프론트엔드 개념노트 깃북

 

GitHub - codekyz/TIL: 🌱 Today I Learned