블로그를 이사하려고 합니다.(feat. 도큐사우르스)

8/20/2024 · 13 min read

회사에서 작은 사내 스터디를 시작하게 되었다. 같이 참여한 동료들은 개발팀 5명으로 1일 1커밋과 주 1회 블로그 업로드를 규칙으로 정했다. 하지만 내가 운영 중이던 블로그는 많은 수정이 필요한상태다.

이전부터 기록을 제대로 해보고 싶은 생각이 있어서 다양한 플랫폼을 이용해봤지만 딱 마음에 드는 게 없었고, 현실에 타협해서 구축은 나중으로 미루고 있었지만 이번 기회에 블로그 이사를 진행해보자는 다짐을 하였다.

블로그 플랫폼을 정해보자

지금까지 다양한 플랫폼들을 이용해서 블로그를 작성했었지만 정말 마음에 든다 싶은 플랫폼을 찾는 건 쉽지가 않았다. 혹시나 내 글이 블로그 플랫폼을 선택하는 사람에게 도움이 될까 싶어서 장단점을 적어보면 이렇다.

벨로그(Velog)
심플하고 직관적이다. 마크다운 지원이 큰 장점이다. 하지만 카테고리 기능이 없고 커스텀 불가능
Medium
디자인이 깔끔하다. 커스터마이징이 불가하다는 단점이 있고, 코드 지원이 빈약하다
브런치(Brunch)
글쓰기를 좋아하는 사람이라면 써볼만 할것같다 하지만 광고를 붙이기가 어렵고 컨셉 자체가 기술블로그와는 맞지 않는다
WordPress
GUI로 커스텀이 쉽고 플러그인 방식으로 추가 커스텀도 가능하지만, 유료로 안 쓰면 좀 힘듦. 이걸로 옮겼다가 금방 포기
티스토리(Tistory)
너무 잘 써왔지만 스킨 적용하고 커스텀하는 과정에서 마음에 드는 게 없음

그럼 뭘쓰지?

나는 Github Page 기능을 이용하기로 결정했다. 깃헙 페이지는 정적 사이트를 호스팅하기 위한 무료 서비스로, 깃헙 레포지토리에 저장된 HTML, CSS, JavaScript 파일을 웹 페이지로 서비스할 수 있다.

무료환경: 깃헙 페이지는 무료로 제공되기 때문에 비용 부담이 없다.
쉬운 배포: 코드 변경 사항을 깃헙 레포지토리에 푸시하는 것만으로 쉽게 배포할 수 있다.(근데 귀찮음)
연동성: 다른 깃헙 서비스와의 연동이 쉬워 CI/CD 파이프라인 구축이 용이하다.
커스터마이징: 정적 사이트 생성기와 함께 사용하여 자유롭게 커스터마이징할 수 있다.

뭐가 있을까?

Jekyll (Ruby)
- 장점: 설정이 간단하고 GitHub Pages와의 연동이 쉬움.
- 단점: 속도가 느리고, 대규모 사이트에 적합하지 않음.
Gatsby (JavaScript/React)
- 장점: 성능이 뛰어나고, 많은 플러그인과 테마 지원.
- 단점: 설정이 복잡하고, 초기 설정에 시간이 많이 걸림.
Hexo (JavaScript)
- 장점: 빠르고, 마크다운 지원이 훌륭함.
- 단점: 플러그인 및 테마의 다양성이 제한적임.
Hugo (Go)
- 장점: 매우 빠른 빌드 속도와 쉬운 설정.
- 단점: 테마와 플러그인이 상대적으로 적음.
Next.js (JavaScript/React)
- 장점: React 기반으로, SEO 최적화와 서버 사이드 렌더링 지원.
- 단점: 복잡한 설정과 상대적으로 느린 빌드 속도.
VitePress (JavaScript/Vue)
- 장점: Vue 기반으로, 빠른 빌드 속도와 쉬운 설정.
- 단점: 기능이 제한적이고, 커뮤니티와 생태계가 상대적으로 작음.

나는 페이스북에서 제공하는 Docusaurus 를 사용해서 블로그를 구축해보려고 한다. Docusaurus는 JS 기반으로 React의 모든 기능을 활용할 수있다. 그럼 내가 왜 이 프레임워크를 선택했는지 짧게 말해보자!

페이스북이 만들었다
페이스북이 만든 도구라면 일단 믿고 써야지! 최근에도 계속 업데이트 되고있다는 점도 맘에 들었다.
초고속 페이지 로딩
Docusaurus는 페이지 로딩이 정말 빠르다. 사용자가 클릭하는 순간 페이지가 눈 깜짝할 사이에 열린다. 노션으로 블로그를 작성할때 느꼈던 느리다는 느낌을 안받고 싶었다.
SEO 최적화
Docusaurus는 SEO 친화적이다. 모든 접근 가능한 경로에 대한 HTML 파일을 만들어주므로 검색 엔진에 잘 노출된다. 플랫폼을 사용하는것만큼은 아니겠지만 SEO 최적화를 지원하는것 너무 큰 장점이다!
MDX 지원
마크다운 문서 내에 JSX와 리액트를 사용할 수 있다는 점이 정말 매력적이다. 마크다운의 편리함과 React의 동적인 기능을 동시에 누릴 수 있다.
문서 버전 관리
프로젝트 릴리스와 문서를 동기화할 수 있어 언제나 최신 상태를 유지할 수 있다. 내 프로젝트와 블로그가 같은 페이스로 업데이트된다.
국제화(i18n)
여러 언어로 사이트를 번역할수있는 기능이 기본적으로 탑재되어있다.
강력한 검색 기능
전체 사이트를 검색할 수 있는 기능을 제공한다.

블로그 기본 구축

Blog or Docs

Docusaurus 는 docs 와 blog 모드가 각각 존재하며, docs 는 기술 문서를 위한 포맷이다. 개발 블로그는 blog mode 만 있어도 충분했기 때문에 blog only 로 설정하여 docs 페이지를 제거해버릴까 고민했다. 하지만 이럴 경우 메인 랜딩 페이지가 없어지기 때문에 뭔가 아쉬웠다.

alt text

고민 끝에 랜딩 페이지를 유지하기 위해 blog only 는 포기하고 docs 만 다른 형태로 바꿔주기로 했다.

그럼 기본적으로 설치하면 좋을 부분만 기록해보자.

프로젝트 세팅

npx create-docusaurus@latest my-website classic --typescript

꿀팁

Docusaurus는 폴더 기준으로 데이터 관리가 가능하다.

alt text

현재 작성하고 있는 글도 위의 그림과 같이 데이터를 관리한다.

Docusaurus.config.ts

처음 배포전에 세팅해두면 좋을 라이브러리들을 알아보자.

Package Manager

다양한 패키지매니저가 존재하고 Docusaurus에서도 이에 맞춰서 npm, yarn, pnpm 등을 지원한다. 일단 첫번째 시도는 pnpm을 사용해봤지만 githubaction을 설정할때 정말 많은 에러가 발생했다. 또한 토스에서 패키지 매니저 관련하여 작성한 글을 보고 yarn을 도입해보자고 생각하였다.

참고 : 토스

yarn start

Mermaid

Mermaid 는 다이어그램을 코드로 간단하고 빠르게 그리는데 적합하여 평소에 자주 쓰는 도구다. Docusaurus 에서는 플러그인으로 지원하니 포함시켜주도록 하자.

yarn add @docusaurus/theme-mermaid

const config: Config = {
    markdown: {
        mermaid: true,
    },
    themes: ['@docusaurus/theme-mermaid'],
};

alt text

자세한 내용은 공식 문서 참고.

Code Block Highlight

java 가 기본지원이 아니기 때문에 prism 설정을 통해 java 추가. 겸사겸사 bash 도 추가해주었다. 만약 본인이 자주 쓰는 언어가 하이라이팅되지 않는다면 적당히 추가해주면 되겠다.

const config: Config = {
    themeConfig: {
        prism: {
            theme: prismThemes.github,
            darkTheme: prismThemes.dracula,
            additionalLanguages: ['java', 'bash'],
        },
    },
};

배포

docusaurus에서 기본적으로 권장하는 방식은 아래와 같다.

alt text

위의 이미지와 같은 방식을 포함한 다양한 방법으로 배포가 가능하지만 docusaurus에서 추천하는 방식은 배포되는동안 블로그 접근이 중단된다. 그리고 나는 github.io를 살리고 싶어서 github pages를 사용하기로 했다. 블로그 글을 작성후 push 하면 자동으로 배포되도록 CI/CD를 구성했다. 일단 /.github/workflows/ 하위에 yaml을 하나 작성하자.

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  build:
    name: Build Docusaurus
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: yarn

      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Build website
        run: yarn run build

      - name: Upload Build Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    name: Deploy to GitHub Pages
    needs: build

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write # to deploy to Pages
      id-token: write # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

alt text

Settings > Pages 에서 Source 를 GitHub Actions 으로 설정 이후에는 main 브랜치에 커밋이 push 될 때마다 자동으로 배포 작업이 진행된다.

추가 진행 예정

다국어 지원 추가
댓글 기능 추가
검색엔진 추가 -> 기본
SEO 추가
기존 블로그 데이터 마이그레이션
옵시디언과 연동
태그별로 분리
메인페이지 변경
포트폴리오 페이지 삽입
Resume 페이지 삽입

블로그 플랫폼을 정해보자​

그럼 뭘쓰지?​

뭐가 있을까?​

블로그 기본 구축​

Blog or Docs​

프로젝트 세팅​

꿀팁​

Docusaurus.config.ts​

Package Manager​

Mermaid​

Code Block Highlight​

배포​

추가 진행 예정​

블로그 플랫폼을 정해보자

그럼 뭘쓰지?

뭐가 있을까?

블로그 기본 구축

Blog or Docs

프로젝트 세팅

꿀팁

Docusaurus.config.ts

Package Manager

Mermaid

Code Block Highlight

배포

추가 진행 예정