Docusaurus 프로젝트 생성과 구조 살펴보기(1) - Blog 디렉토리

2024년 9월 1일 · 약 8분

Curious Developer

Docusaurus를 활용해서 블로그를 개설을 했습니다. Docusaurus에 대해서 공식 홈페이지에 나온 내용을 간단히 지난 포스팅에서 정리했는데요, 이번 포스팅에서는 Docusaurus 프로젝트를 생성하는 방법과 구조에 대해서 간단히 정리하려고 합니다.

노트

2024-09-01 - Docusaurus 프로젝트 생성과 구조 살펴보기(1) - Blog 디렉토리
2024-09-02 - Docusaurus 프로젝트 생성과 구조 살펴보기(2) - docusaurus.config.ts
2024-09-03 - Docusaurus 프로젝트 Amplify와 Github로 자동 배포하기 - docusaurus.config.ts

어떤 프로젝트를 진행하든 저는 항상 처음에 폴더 구조를 잡는 것에 대해 어려움을 겪어서 따로 정리를 하기로 했습니다. 또한 어떤 파일들을 만들고 수정해야 사이트를 운영할 수 있는 지도 정리해보겠습니다.

Docusaurus 설치

팁

2024.09.01일 기준, 최신 Docusaurus 버전은 V3.5.2이며, Node.js 18.0 버전이 필요합니다.

Node.js가 설치되어 있지 않다면, Node.js 공식 홈페이지에 방문해서 설치를 진행합니다. 그리고 다음 명령어를 실행하여 프로젝트를 생성해줍니다.

# default
npx create-docusaurus@latest my-website classic

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

명령어를 실행하면 Docusaurus가 설치됩니다. 아주 간단하게 설치가 완료되었습니다.

프로젝트 구조

my-website
├── README.md
├── babel.config.js
├── blog
│   ├── 2019-05-28-first-blog-post.md
│   ├── 2019-05-29-long-blog-post.md
│   ├── 2021-08-01-mdx-blog-post.mdx
│   ├── 2021-08-26-welcome
│   ├── authors.yml
│   └── tags.yml
├── docusaurus.config.ts
├── node_modules
├── docs
│   ├── intro.md
├── package-lock.json
├── package.json
├── sidebars.ts
├── src
│   ├── components
│   ├── css
│   └── pages
├── static
│   └── img
└── tsconfig.json

처음 프로젝트를 위 명령어로 생성하게 되면 위와 같은 프로젝트 구조로 생성됩니다. 중요한 디렉토리/폴더만 몇 가지 간략하게 정리해보겠습니다.

blog

이름과 같은 역할을 합니다. 작성한 포스트를 이 디렉토리에 넣어주면 됩니다. 디렉토리 안에 포스트를 작성하는 유형이 세 가지가 있습니다. 하나의 파일로 관리하는 방법(.md 파일, .mdx 파일)과 디렉토리 별(마크다운 파일 + 이미지 디렉토리)로 관리하는 방식이 전부 구현되어 있습니다. 하지만 저는 그 중에 .mdx 파일로 작성하고 이미지는 별도로 S3 업로드를 통해서 링크를 가지고 오는 방법 으로 구현하기로 했습니다.

노트

md 파일: 순수 마크다운 파일로, 간단한 텍스트 서식 지정에 사용됩니다.
mdx 파일: 마크다운에 JSX를 결합한 파일로, React 컴포넌트를 포함할 수 있어 더욱 동적인 문서를 작성할 수 있습니다.

그리고 안에 설정 파일이 두 가지가 있습니다. 바로 authors.yml과 tags.yml 입니다.

authors.yml

말 그대로 블로그 내의 저자들을 미리 정의해두는 파일입니다. 여러 명을 등록해 둘 수도 있습니다. 간단한 작성자 정보를 미리 등록하여 마크다운 문서에서 가져다가 저자를 등록할 수 있습니다.

yangshun:
  name: Yangshun Tay
  title: Front End Engineer @ Facebook
  url: https://github.com/yangshun
  image_url: https://github.com/yangshun.png
  page: true
  socials:
    x: yangshunz
    github: yangshun

이 파일에 미리 저자를 등록해 놓으면 포스트에서 작성자를 확인할 수 있습니다. authors.yml 파일에서 지정한 author를 포스트 상단(metadata)에서 지정하면 위 빨간 사각형으로 그려놓은 영역처럼 저자 정보가 나오게 됩니다.

tags.yml

이 파일은 포스트의 tag들을 미리 정의해두는 파일입니다.

docusaurus:
  label: Docusaurus
  permalink: /docusaurus
  description: Docusaurus tag description

이런 식으로 작성하면 됩니다. 이렇게 정리한 tag들은 작성된 포스트 하단에서 확인할 수 있는데, 이 tag는 작성한 포스트들을 카테고리화 할 수 있도록 해줍니다. tags 하단에 이렇게 확인할 수 있게 되어 있는데, 위에 작성한 permalink로 접속하면 해당 태그가 등록된 포스트 목록들을 확인할 수 있습니다.

포스트에 metadata 등록

---
slug: first-post
title: first-post
authors: [yangshun]
tags: [docusaurus]
---

포스트 상단(markdown 파일)에 이렇게 기본적으로 네 가지를 등록하도록 되어 있습니다.

slug는 포스트의 URL을 지정합니다. 블로그 주소 마지막에 /{slug}를 입력하면 그 URL이 해당 포스트의 URL이 됩니다.
title은 포스트의 제목을 지정합니다. 포스트 상단에 노출됩니다.
authors는 위에 설명한 것처럼 저자들을 지정합니다. 포스트 상단에 노출됩니다.
tags는 위에 설명한 것처럼 태그들을 등록합니다. 하단에 노출되며, 포스트들을 카테고리화할 수 있습니다.

이 내용들만 잘 숙지하고 있으면 블로그 포스트 등록은 문제 없습니다. 물론 마크다운 문법에 대한 공부가 필요하지만, 크게 어렵지 않습니다. 저 또한 기본적인 부분들만 알고 있고, 틈틈히 찾아서 작성하고 있습니다.

마치며

사실 이 포스팅 하나로 Docusaurus의 간단하게 프로젝트 구조들에 대해서 정리해보려고 했지만, 생각보다 포스팅이 엄청 길어지게 되었습니다. 그래서 부득이하게 나눠서 정리하려고 합니다. docs 디렉토리의 경우에는 pass하고 다음 포스팅에서는 전체 프로젝트의 설정 파일인 docusaurus.config.ts에 대해서 정리해보겠습니다.

출처

Docusaurus 공식 홈페이지

Docusaurus 설치​

프로젝트 구조​

blog​

authors.yml​

tags.yml​

포스트에 metadata 등록​

마치며​

출처​