코테 준비를 위한 코테북 제작기 ( Feat. Vuepress)

코테랑 Vuepress랑 무슨 연관관계가있어?

코테랑 Vuepress는 아무 연관관계도 없다. 코테를 준비하며 푼 문제들과 풀이를 공유하고 유형별로 정리하여 다른 사람들이 준비할 때 도움이 되었으면 하는 바램으로 코테북을 제작을 하게 되었다.

블로그

레포​와 Vupress로 제작된 블로그에 한번 구경오셔서 저의 코드도 지적해주시고 코테를 준비하면서 좋다고 생각되는 문제들도 공유해주시면 감사하겠습니다!🙇🏻‍♂️

Vuepress와의 만남

Vuepress의 첫 만남은 TIL을 제작하기 위해 준비를 할 때였다. 블로그 형식으로 TIL을 제작하고 싶어 찾아보다가 진유림님의 TIL을 만나게 되었다.

이거다! 생각된 나는 무지성 fork를 하였다. 나의 TIL 제작을 위해 코드를 하나하나 까보며 적용을 하기 위해 시도를 하였다. 도저히 블로그의 형태가 어떻게 그려지는지 도통 이해를 할 수 없었고,

결국 정신적 고통만 안겨주고

포기할 수 밖에 없었다. (결국 TIL은 Jekyll로 제작하였습니다..)

두번째 만남은 CS공부를 위해 깃 레포를 탐방할 때 였다. 📚Tech-Stack이라는 아주 멋진 레포를 접하게 되었다. 그런데 어디서 많이 본 것만 같은 기분이 드는 것이다.

먼가 어디서 많이 본 구조인데 라는 생각을 하다가 TIL을 만들 때 봤다는 기억이 떠올랐다.
역시나 그때도 Vuepress라는 존재를 모르던 시절이기 때문에

(내 구글링 실력이 너무 허접한건가.. 왜 몰랐을까..)

fork해서 성공적으로 블로그를 띄운거구나 라고 생각을 했다. 그러면서 동시에 나의 CodingTest repo에 문제들을 유형별로 정리하고 공유할 수 있게 만들 수 있으면 좋겠다고 생각이 들었고 그래서 다시한번 fork를 하여 도전하였다.

두번째 도전.. 하지만 조금 다르다.

나의 두번째 fork후 블로그 제작을 위한 코드 분석이 시작되었다. 다만, 과거에 비해 다른점은 총알이 두개라는 것이다.(진유림님의 TIL과 Tech-Stack) 두 레포를 모두 로컬환경에서 다운로드받아서 Atom으로 열어서 비교 분석을 시작하였다.

대충 그 당시 내 분석결과는 이러했다.

/docs라는 폴더의 내부에 있는 폴더에 내용들이 올라가는구나.vuepress의 config.js의 코드로 sidebar 내용을 채워주는 거구나.

그런데 아직 나의 궁금증은 풀리지가 않았다. 어떻게 이 코드들로 page를 구성할 수 있을까? 숨겨진 기능이 있는가? 이것을 찾아보며 github page라는 것을 알게되어 공부하게 되었는데, html로 구성된 정적 웹페이지를 호스팅하는 역할만 수행할 뿐.. 저런 코드들을 실행하며 동적으로 웹페이지를 구성하지는 않는다는 것을 알았다.

대충의 분석만으로 감을 잡기가 쉽지 않았고, 계속해서 구글링을 하다가 우연히 글을 하나 발견하였다.

드디어? 궁금증이 해결되기 시작한다.

Tutorial :: Vuepress로 기술문서 빠르게 만들어보자!
이 글을 접할 때 나는 계속된 분석과 실패로 인해 번아웃이 된 상황이었고 아직 군인신분인 나에게 곧 다가오는 혹한기훈련이라는

끔찍한 시련

이 남아있었기 때문에 더 이상의 진행은 정신적으로 너무 힘들었다.

글을 훑어보니 Vuepress라는 블로그를 만들어주는 그런게 있구나라는 생각과 먼가 할 수 있을것 같다는 확신이 들기 시작했다. 일단 미뤄두고 혹한기 끝내고 혼내줘야겠다는 생각으로 읽기목록에 잠시 넣어두었다.

Vuepress 설치

참고하기 좋은 링크

• Vuepress 홈페이지
• VuePress로 블로그 제작 1 시작하기
• vuePress 사용법
• Tutorial :: Vuepress로 기술문서 빠르게 만들어보자!

Github에 Vuepress 설치

글쓴이는 순조롭게 Vuepress를 생성해내는데, 나는 계속해서 에러로 멈출 수 밖에 없었다. 단순히 따라하기만으로는 너무 버거운 시작이다. 지금 생각해보면 별거 아니고 쉬운 문제였지만, 나는 엄청 많이 삽질을 하였다.(14시간동안의 대장정을 하였다.) 여러 블로그에 게시된 글을 참고하여 해보고 안되면 다시 다 초기화해서 시작하고, 해보고 안되면 다시 다 초기화하는 반복작업을 시작하였다.(태초마을을 한 10번 갔다온 것 같다.)

결론만 말하면 git에 대한 나의 역량 부족이 주 원인이었다. 만약 Vuepress를 활용해 깃 블로그를 제작할 일이 있다면, 내가 겪은 에러들을 공유할테니 꼭 도움이 되었으면 한다.

설치방법

1. 깃허브 클론하기

$ git clone 'repo address'

$ cd 'repo address'

우선 repo를 클론해서 가져오고 그 파일위치로 이동한다.

 

2. npm으로 vuepress 다운받기

//현재 위치 : ~/클론받은 레포
$ npm init -y
$ npm install -D vuepress

npm init -y를 하여 package.json파일을 받아오고,
npm install -D vuepress를 하여 file을 모두 받아온다.

npm이 설치가 되어있지 않다면, npm을 먼저 설치해주어야한다.
npm은 노드 패키지 매니저로 js의 패키지 관리자라고 생각하면 된다.

 

3. README.md 파일 작성

//현재위치 : ~/클론받은 레포 
mkdir docs
cd docs

//현재 위치 :  : ~/클론받은 레포/docs
vi README.md
//README.md 작성(작성을 하는 방법을 모르시면 vi와 마크다운 문법을 참고하세요.)

'/클론받은레포'의 디렉토리에서 'docs'라는 이름의 directory를 추가하여준다.
그리고 docs라는 파일에 들어가서, README.md라는 이름으로 파일을 만들고 작성해준다.

꼭 vi에디터로 작성할 필요는 없습니다. 다른 에디터를 사용하여도 무방합니다.

 

4. deploy.sh 작성

//현재 위치 : ~/클론받은 레포/docs
cd ..

//현재 위치 : ~/클론받은 레포
vi deploy.sh

다음으로 deploy.sh를 생성하여줍니다. 이것을 돌려서 웹페이지를 정적으로 구성해주고 생성해주게 됩니다.

# deploy.sh
set -e

npm run docs:build

cd docs/.vuepress/dist

git init
git add -A
git commit -m 'deploy'

#git push -f https://github.com/깃헙이름/레포이름.git master:gh-pages
git push -f https://github.com/kim-jin-seop/CodingTest.git master:gh-pages

cd -

위는 나의 deploy.sh이며 이를 그대로 사용하고, 아래의 push하는 부분만 본인의 깃허브 이름과 레포 이름으로 변경해주면 된다.

 

5. package.json 확인

    ...
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
    ...

package.json의 scripts에 위와 추가해주면 된다.

위 과정이 끝났다면, 사실.. vuepress를 활용해 블로그를 띄우는 것은 문제가 없다.

로컬에 Vuepress 올려보기

로컬의 환경에서 한번 Vuepress를 올려 잘 작성이 되었는지 알아보자.
npm run docs:dev 이 명령어를 입력해보고 localhost:8080에 접속하여 vuepress가 잘 뜨는지 확인해보자. 만약 잘 안뜬다면.. 위 과정에 오타가 없는지 혹은 잊어버린 부분이 없는지 잘 확인해보는 것을 추천한다.

이 때까지는 나도 에러가 안났지만.. 이제 깃헙으로 올리는 과정에서 수많은 시행착오를 겪게되었다.

깃헙에 Vuepress 올려보기

vuepress로 글을 올리고 카테고리를 만들 때마다 config.js파일을 수정하여 nav를 추가해주어야하는 번거로움이 있다. 하지만 그렇게 하지 않고 자동으로 docs 레파지토리를 읽어서 실행시킬 수 있게 만들어주도록 만들어 줄 수도 있다.

나는 이 글에 있는 코드를 활용해 주었다.
docs 디렉토리에 .vuepress가 있을 것이다.(없으면 만들면 된다.) 그 위치로 이동하여 config.js를 생성하고 아래 코드를 추가해주면 된다.

// //현재 위치 : ~/클론받은 레포/docs/.vuepress/config.js
module.exports = {
  title: "title",
  description: "desc",
  themeConfig: {
    sidebar: getSidebarArr()
  },
  //레파지토리의 이름을 아래에 넣어주면된다.
  base: "/CodingTest/"
};

function getSidebarArr() {
  var fs = require("fs");
  var docsPath = __dirname + "/../";
  var sidebarArr = [];
  var HomeFilelist = [];
  var filelist = fs.readdirSync(docsPath);
  filelist.forEach(function(file) {
    if (file === ".vuepress") return;
    var stat = fs.lstatSync(docsPath + "/" + file);
    if (stat.isDirectory()) {
      // directory
      // title is file, children is readdirSync
      var docsFolderPath = docsPath + "/" + file;
      var list = fs.readdirSync(docsFolderPath);
      sidebarArr.push(makeSidebarObject(file, list));
    } else {
      // NOT directory
      // title is '/' children is file
      HomeFilelist.push(file);
    }
  });
  sidebarArr.unshift(makeSidebarObject("", HomeFilelist));
  return sidebarArr;
}
function makeSidebarObject(folder, mdfileList) {
  var path = folder ? "/" + folder + "/" : "/";
  mdfileList = aheadOfReadme(mdfileList);
  var tmpMdfileList = [];
  // remove .md, add Path
  mdfileList.forEach(function(mdfile) {
    if (mdfile.substr(-3) === ".md") {
      mdfile = mdfile.slice(0, -3) === "README" ? "" : mdfile.slice(0, -3);
      tmpMdfileList.push(path + mdfile);
    }
  });
  mdfileList = tmpMdfileList;
  // remove folder prefix number
  if (folder) {
    var dotIdx = folder.indexOf(".");
    var title = Number(folder.substr(0, dotIdx))
      ? folder.substr(dotIdx + 1)
      : folder;
  } else {
    title = "HOME";
  }
  return {
    title: title,
    children: mdfileList
  };
}
function aheadOfReadme(arr) {
  // ['1.test.md','README.md'] => ['README.md','1.test.md']
  var readmeIdx = arr.indexOf("README.md");
  if (readmeIdx > 0) {
    arr.unshift(arr.splice(readmeIdx, 1)[0]);
  }
  return arr;
}

여기서 중요한 부분은 위 부분에 base : 뒤에 레파지토리 이름을 꼭 넣어주어야한다는 것이다.

이제 마지막으로 아까 만든 deploy.sh를 실행시켜 웹페이지를 띄어주기만 하면 된다.
deploy.sh를 만든 위치로 가서 sh deploy.sh를 실행시켜보자. 에러가 안나고 정상적으로 동작할 수도 있는데 나는 무수히 많은 에러를 경험하였다.

내가 겪은 에러들

1. gh-pages 브렌치가 없음!

깃허브에 대한 지식이 매우 부족한 나는 깃허브 페이지에 대해 모르고 있었으며 브랜치에 대한 개념이 전혀 없었다.

Vuepress로 깃허브에 블로그를 띄어주기 위해서는 새로운 브런치를 하나 gh-pages라는 브랜치를 하나 새로 생성하여 처리해주어야한다.

git checkout –orphan gh-pages //브랜치 추가
git rm -rf //의미없는 제거
echo “My Page” > index.html    

git init
git add -A
git commit -m 'deploy'
git push -f https://github.com/kim-jin-seop/CodingTest.git master:gh-pages
#git push -f https://github.com/깃허브 이름/레포 이름.git master:gh-pages

이렇게 하여 새로운 브랜치를 만들었다면 1차적인 준비가 끝난다.

만약 에러가 난다면 자신이 가지고 있는 브렌치의 이름이 master가 아니라 main인지 확인해보고 수정해주면 된다.

 

2. Git Token 
나는 깃허브를 사용할 때 따로 터미널을 이용하지 않고 github Desktop을 사용한다. 그래서 토큰에 대한 설정이 따로 없었다. 그래서 계속 deploy.sh를 실행할 때 토큰이 없다는 오류가 발생한 것이다.

2020년 7월부터 깃허브가 토큰을 활용한 인증방식만 사용한다고 선언을 하였고, 나는 그 사실을 몰랐다. 토큰을 생성하여 추가해주기만 하면 된다.

GitHub 토큰 인증 로그인: Personal Access Token 생성 및 사용 방법
이 링크에 상세하게 작성되어있으니 토큰을 생성하여 가지고 있다가, 처음 깃허브에 푸시를 실행할 때 입력해주면 된다.

 

3. SSH key 생성
공개키가 없어서 진행이 안되는 오류도 발생하였다.
공개키를 생성하는 것은 아래 링크를 보며 제작하였다.

Git 서버 - SSH 공개키 만들기

 

Github pages 설정
위 과정을 정상적으로 마쳤다면, 이제 홈페이지를 호스팅해볼 수 있다.

1. vuepress가 들어있는 레포지토리에 들어간다.
2. settings/pages에 들어가서 Brunch를 gh-pages로 설정 후 save해준다.

포스팅을 마치며

위 과정을 끝마치면 'https://<github 계정이름>.github.io/<레포지토리 이름>/'으로 호스팅된 나의 Vuepress를 만들 수 있다. 위 방법대로 실행을 하면 docs 디렉토리에서 글을 입력하고 나중에 deploy.sh를 실행하면 docs:build라는 스크립트가 실행되며 정적인 웹페이지를 생성해주고 그 생성된 것을 gh-pages라는 브렌치로 푸쉬하게 된다.

그리고 깃허브 페이지가 gh-pages 브렌치에 푸쉬된 정적인 웹페이지를 띄어주어 호스팅을 하게 되는 것이다.

나의 깃허브 세팅이 Vuepress를 제작하는데 굉장히 큰 걸림돌이 되었던 것 같다. 깃허브를 좀 더 공부할 필요가 있다고 느끼게 해주는 삽질이었고, 이번 삽질로 그래도 대충 전체적인 Vuepress의 흐름과 원리 그리고 브렌치 개념을 잘 이해할 수 있는 만족스러운 도전이었다고 생각한다.

(역시 개발은 맨땅에 해딩할 때가 제일 재밌다.)

다음에는 github action을 활용해 deploy.sh를 실행하지 않고도 master에 푸시나 pr이 될 때마다 정적 웹페이지를 자동으로 구성하는 것을 만들어보고 소개하는 글로 찾아오겠다.

긴 글 읽어주셔서 감사합니다. 혹시 잘못된 내용이 있다면 댓글 남겨주시면 감사하겠습니다!