1. 웅덩이 파는 데 포크레인 써보기 2. Design System 흉내를 위해 Figma 힐끗 보기
4. Docusaurus config 톺아보기 (1) 5. Docusaurus config 톺아보기 (2) 6. Swizzle로 디자인 커스터마이징하기 7. Github Pages로 Docusaurus 웹사이트 호스팅하기 8. 구글 서치 콘솔 등록하고 사용자 인사이트 얻기
React 기초 훑어보기
사실 React에 대한 이해가 전혀 없어도 Docusaurus를 쓰는 데 무조건 지장이 생기는 것은 아니다. Docusaurus가 제공하는 디자인을 거의 변경하지 않으면서 그대로 사용한다면 CSS로 커스터마이징하는 것으로 충분하다. 하지만 더 아는 상태에서 도구를 사용하는 건 그렇지 않은 상태와 분명한 차이가 있다. 결과적으로 React를 미리 공부하고 시작한 덕에 내 기대보다 더 많은 디자인 커스터마이징이 가능했다. 그래서 프로그래밍 기초 체력이 어느 정도 있는 사람이라면 Docusaurus를 써보기 전에 꼭 React 기초 개념을 공부하는 것이 좋다고 추천하고 싶다.
React 공부는 노마드 코더의 무료 강의를 활용했다. 사실 강의 내용 전체를 다 듣진 못했지만 앞 부분에서 React의 컨셉을 알기 쉽게 설명해주기 때문에 앞부분만 들어도 나중에 설명할 인덱스 페이지 개발에 큰 도움이 된다. React의 기본적인 컨셉은 화면에 표시될 요소를 '모듈화'하는 데 있다. Design System에 이미 익숙한 사람이라면 금방 적응할 수 있다.
다음은 포트폴리오이자 현재 사이트의 인덱스 페이지의 코드 구조이다.
import React, {useState} from 'react'
import useDocusaurusContext from '@docusaurus/useDocusaurusContext'
import Layout from '@theme/Layout'
function SectionTitle ({title_kr, title_en}){
return (
<div className='SectionTitle'>
<h2>
<span className='title_kr color-primary'>{title_kr}</span>
<span> </span>
<span className='title_en' >{title_en}</span>
</h2>
</div>
)
}
export default function Home(){
return (
<Layout title='겨울이불의 아카이브'
description='블로그, 공부 기록 등 온갖 개인적인 관심사를 모아두는 곳입니다.'>
<main className='container'>
...
<SectionTitle title_kr='업무 경험' title_en='Work Experience' />
...
</main>
</Layout>
)
}
실제로는 함수가 더 여러개 있지만 구조를 설명하는 데 필요한 만큼만 발췌했다. React를 배우면서 내가 직접 이름을 지은 HTML Tag를 넣을 수 있다는 사실을 처음 알게 되었다. 위의 코드를 보면 SectionTitle이라고 이름 지은 Component가 함수로 정의된 것을 볼 수 있다. 함수 내용 안에는 그 Component의 형식과 디자인을 일반적인 HTML을 작성하는 것과 큰 차이 없이 작성하면 된다. 다만 컴포넌트 안에 들어갈 유동적인 부분, 예를 들면 섹션 제목과 같은 내용은 변수로 작성한다는 점이 차이점이다. 이렇게 정의된 함수를 불러와서 마치 HTML Tag처럼 사용하는 부분이 <SectionTitle title_kr='업무 경험' title_en='Work Experience' /> 이다.
이런 구조를 취하면 같은 모양이면서 내용만 달라지는 경우, 즉 같은 Component가 반복적으로 쓰이는 경우 매번 전체 HTML을 작성할 필요가 없다는 장점이 있다. 물론 내가 만든 포트폴리오 페이지는 디자인이 매우 단순해서 심플하게 Component 하나당 함수 하나가 나오지만, 실제 서비스용 프로덕트라면 Component의 구조가 훨씬 복잡해질 것이다. Design System을 설계할 때 각 Component가 매우 독립적이어야 한다는 말을 들었었는데 직접 만들고 보니 바로 이해할 수 있었다. 이렇게 모듈화된 코드를 불러오는 구조인데 Component가 서로 중첩되어 설계되어있다면 코드상에서도 당연히 구현이 어려워질 것이다.
Docusaurus에서 콘텐츠를 표시하는 방법
이제 Docusaurus 설치를 시작할 차례다. 그 전에 Docusaurus가 콘텐츠를 어떻게 다루는지를 알아볼 필요가 있다. 콘텐츠의 성질에 따라 어떤 기능을 써야 하는지가 정해지기 때문이다. Docusaurus는 문서 콘텐츠를 크게 docs, blog, page로 분류한다. 사실 (기본적으로는) 마크다운으로 내용을 작성한다는 점은 같기 때문에, 그냥 콘텐츠를 어떤 용도로 표시하느냐에 따라 기본 제공하는 UI가 달라진다고 보면 편하다.
Docs
docs는 웹페이지 형태의 사용자 가이드 제작용으로 나온 기능이다. 바로 Docusaurus 가이드 페이지가 이 기능으로 만들어져 있다. 왼편 사이드바에 큰 목차가 있고, 중앙에 내용, 오른편 사이드바에 내용 목차가 있는 구조이다. 일정한 목차를 가진 문서 콘텐츠를 상시 게시해놓기에 편리하다. Versioning도 지원하기 때문에 릴리즈 노트처럼 버전별로 콘텐츠를 게시하는 것도 가능하다.
blog
blog는 말 그대로 블로그 형태로 콘텐츠를 게시하고 싶을 때 쓰는 기능이다. 개인적인 용도로 Docusaurus를 쓴다면 docs보다는 이 쪽을 더 많이 쓸 것이다. 블로그 하나에 집중하는 라이브러리가 아니어서 그런지 레이아웃이 너무 간단하다는 게 단점이다.
page
Docusaurus는 docs와 blog가 가장 큰 뼈대이고, 그 외에 추가로 원하는 서브 페이지들을 추가할 수 있는 구조로 되어 있다. 예를 들면 첫 화면을 docs나 blog로 가지 않고 별도의 index 페이지로 만들 수 있다. Docusaurus 가이드도 첫 화면에 Docusaurus를 소개하는 내용을 담고 있다.
하나의 사이트에서 docs, blog, page를 여러개씩 가질 수도 있다. 즉, 계층화된 목차를 가진 많은 양의 문서를 게시한다면 docs를, 블로그 포스팅 용도라면 blog를, 완전히 커스터마이징한 페이지가 필요하다면 별도의 서브 페이지를 추가하는 식이다.
Docusaurus 설치하기
Docusaurus 설치 방법은 간단하다. 앞으로 온갖 데이터를 쌓아두게 될 폴더 위치를 잘 선정한 후, 터미널에서 아래 명령어를 실행하면 된다. my-website 부분이 내 폴더명이 된다.
npx create-docusaurus@latest my-website classic
위 명령어를 실헹하면 Docusaurus에서 기본 제공하는 테마와 샘플 문서가 들어있는 상태로 폴더 내용이 셋팅된다.
설치 후 보게 될 폴더 구조
my-website
├── blog
│ ├── 2019-05-28-hola.md
│ ├── 2019-05-29-hello-world.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock
Docusaurus는 (1) 사용자 가이드 같은 정적인 페이지, 혹은 (2) 블로그 운영에 최적화되어 있어서 폴더 구조도 이에 맞춰져 있다.
blog
블로그 포스트 파일을 모아놓는 곳이다. 위 폴더 구조 예시에서는 마크다운 파일만 들어있지만, 실제로는 포스트별로 필요한 이미지를 모아 관리하기 위해 폴더들을 넣어놓게 된다.
docs
정적인 페이지를 모아놓는 곳이다. 앞서 언급한 계층적인 목차를 가진 문서 콘텐츠를 게시한다면 이 곳에 파일을 모아두게 된다.
src
docs, blog는 콘텐츠 문서들, 즉 마크다운 파일을 용도에 따라 모아두는 곳이다. 반면 src 폴더는 내가 Docusaurus에서 기본적으로 제공하는 코드 외에, 내가 커스터마이징하거나 추가할 React 소스 코드를 모아두는 곳이라 이해하면 쉽다.
설치하자마자 기본값으로 들어있는 custom.css 파일에 내가 원하는 CSS를 작성하면 기존 Docusaurus 디자인에 CSS를 덮어씌울 수 있다.
앞서 언급한 서브 page는 pages 폴더 안에 넣어두면 된다. page는 마크다운으로 작성할 수도 있고, 좀 더 UI 디자인이 필요하다면 React js로 작성해서 만들 수도 있다.
static
React는 개발이 끝나면 build라는 과정을 거쳐서 실제 서버에 올라갈 코드를 생성하는데, static 폴더 안에 있는 데이터는 build에 포함된다. 그래서 page에서 사용하는 이미지나 기타 서버에 올라갈 코드에 포함 됐으면 하는 파일이 있다면 이 곳에 넣으면 된다.
검색 노출을 돕기 위해 구글, 네이버에 사이트 등록을 하려면 도메인 소유권을 인증을 요구한다. 인증 방법 중 하나가 특정 html 파일을 사이트에 올려서 구글, 네이버가 찾을 수 있도록 하는 건데 static 폴더 안에 해당 파일을 올리면 쉽게 해결할 수 있다.
docusaurus.config.js
초반에 특히 자주 보게 되는 파일로, 온갖 Docusaurus의 설정을 편집하는 곳이다. Docusaurus에서 제공하는 다양한 기능이 첫 설치 상태에서 모두 켜져 있지는 않다. 필요한 기능을 config 파일에 추가하면 켜지는 식이다. 특히 검색 노출에 도움이 되는 사이트 메타데이터 정보도 여기에 작성한다.
sidebars.js
docs의 왼편 사이드바에 목차를 어떻게 보여줄지를 설정하는 곳이다.
이제 본격적인 개발 준비는 끝
npm start를 터미널에 입력해서 localhost에 띄워보면 위와 같은 샘플 사이트를 볼 수 있다. 나는 인덱스 페이지에 개인 포트폴리오를 넣어두고, UI를 좀 더 예쁘게 다듬은 블로그를 만들 생각이었다. 뼈대를 올려야 하니 config 파일 가이드를 전체적으로 훑어보며 필요한 설정들을 넣기 시작했다.
1. 웅덩이 파는 데 포크레인 써보기 2. Design System 흉내를 위해 Figma 힐끗 보기
4. Docusaurus config 톺아보기 (1) 5. Docusaurus config 톺아보기 (2) 6. Swizzle로 디자인 커스터마이징하기 7. Github Pages로 Docusaurus 웹사이트 호스팅하기 8. 구글 서치 콘솔 등록하고 사용자 인사이트 얻기