📕 가독성 업, Hi docusaurus (feat.tistory, github, velog)

 

 

배경

나는 총 3개의 블로그를 운영중이다.

• tistory
  에러 로그 및 잡다한 지식
• velog
  Node.js 및 AWS 내용
• github + jekyll 
  Database 기본기 공부내용

위와 같이 다루는 콘텐츠별로 블로그를 분리하여 관리하는데

최근 Kotlin 과 Go 등 언어와 프레임워크만 다룰 블로그를 개설하고자 다른 도구가 없나 찾아봤다.

구분	커스터마이징 자유도	마크다운 편의성	IDE & VCS 연동 편의성
tistory	높음	낮음	낮음
velog	낮음	높음	낮음
github.io	보통	높음	높음
gitbook	?	높음	높음
✅ docusaurus	높음	높음	높음

 

 

 

디자인과 포맷은 gitbook 이 맘에 들지만 아쉽게도 3년 전부터 더이상 관리되지 않는 상태다.

마지막 커밋이 2018년 12월 28일인 gitbook

 

한줄기 빛인 Facebook 에서 만든 오픈소스인 docusaurus 라는 툴을 발견했다.

오늘도 관리되고 있는 핫한 도구

내가 꼽는 docusaurus 의 장점은 다음과 같다.

• React + Typescript + SASS/SCSS 등 최신 스택 기반
• 자유로운 커스터마이징 
• git 과 IDE 연동에 용이
• 마크다운 & HTML 모두 지원

새로운 블로그를 docusaurus 를 통해 구축하기로 결정하고 환경 설정을 시작했다.

공식문서도 잘되있고 국내 블로그 중에도 참고할만한 블로그가 있어 아래 링크를 남겨둔다.

 

---

 

⚙️ docusaurus 설정 방법

다음 순서대로 설정했다.

 

1. 패키지 초기화 설치

# package manager: yarn
$ yarn create docusaurus --typescript --package-manager yarn

node.js 18.x 버전에 yarn 패키지 매니저를 사용했다.

2. docusaurus.config.js 설정

{
  title: "웹사이트 제목",
  tagline: "웹사이트 설명",
  url: "웹사이트 URL (route path 제외)", // ex) https://milkcoke.github.io
  baseUrl: "웹사이트 baseUrl", // ex) "/docusaurus"
  organizationName: "github username",
  projectName: "github-repo name", 
  i18n: {
    defaultLocale: "ko", // 한국어 패치
    locales: ["ko"],
  },
  // ..
}

 

3. Header 설정

url + baseUrl + /사이트명이 아닌

'/' root URL 에서 바로 메인 페이지가 띄워지도록 다음과 같이 설정

// presets.blog
{
  routeBasePath: "/",
}

 

4. Footer 설정

페이지 하단 Footer 영역에 쓸데 없는 것들을 지우자

footer.links 삭제

{
//..
      footer: {
        style: 'dark',
        //footer.links 삭제
        links: [
          {
            title: 'More',
            items: [
              {
                label: 'Blog',
                to: '/blog',
              },
              {
                label: 'GitHub',
                href: 'https://github.com/milkcoke/docusaurus',
              },
            ],
          },
        ],
        // 여기까지 삭제
        // copyright 만 남기기
        copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
      },
      //..
  }

 

 

5. 기본 색상 변경

docusaurus.config.js

      
// themeConfig
  colorMode: {
    defaultMode: "dark", // 다크모드 적용
    respectPrefersColorScheme: true // 커스텀 색상 우선적용
  },

 

 

6. 댓글 추가

src/components/Comment.tsx

// src/components/Comment.tsx
import React, { useEffect, useRef } from "react";
import { useColorMode } from "@docusaurus/theme-common";

export default function Comment() {
    const containerRef = useRef(null);
    const utterancesRef = useRef(null);

    const { colorMode } = useColorMode();
    const utterancesTheme = colorMode === "dark" ? "github-dark" : "github-light";

    useEffect(() => {
        const createUtterancesEl = () => {
            const script = document.createElement("script");
            script.src = "https://utteranc.es/client.js";
            script.setAttribute("repo", "milkcoke/docusaurus"); // github 계정 이름 / repository 이름
            script.setAttribute("issue-term", "title");
            script.setAttribute("label", "comment");
            script.setAttribute("theme", utterancesTheme);
            script.crossOrigin = "anonymous";
            script.async = true;
            script.onload = () => {
                utterancesRef.current = document.querySelector(".utterances-frame");
            };

            containerRef.current.appendChild(script);
        };
        createUtterancesEl();
    }, []);

    useEffect(() => {
        if (!utterancesRef.current) return;
        const message = {
            type: "set-theme",
            theme: utterancesTheme,
        };

        utterancesRef.current.contentWindow.postMessage(
            message,
            "https://utteranc.es"
        );
    }, [utterancesTheme]);

    return <div ref={containerRef} />;
}

 

src/theme/BlogPostItem.tsx

import React from "react";
import BlogPostItem from "@theme-original/BlogPostItem";
import Comment from "../components/Comment";

export default function BlogPostItemWrapper(props) {
    return (
        <>
            <BlogPostItem {...props} />
            <Comment />
        </>
    );
}

 

7. 검색 기능 추가 (feat. algolia)

 

 

 

8. github action + github pages (CI/CD)

IDE 에서 수정한 것을 `main` 브랜치에 push 했을 때

자동으로 React가 빌드되고 정적 파일들이 `gh-pages` 브랜치에 배포되도록 한다.

 

 

 

 

 

(최종) 페이지 호스팅 확인

편안-하구만

 

 

 

✍️ Tips.

간혹 'gh-pages' 브랜치에 index.html 등 정적 파일이 업데이트 되었음에도 사이트에는 업데이트가 일어나지 않는 경우가있다. 이 때는 자체적인 브라우저 캐싱 때문일 수 있으니 `Ctrl + F5` 버튼을 눌러 캐시된 데이터를 다시 다운로드 받아보면 된다.

---

🔗 Reference

Installation | Docusaurus

Docusaurus로 문서 관리하기 - 2

GitHub - peaceiris/actions-gh-pages: GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Stat