메인 컨텐츠로 이동
Version: 2.0.0-beta.10 🚧

블로그

블로그 기능을 사용하면 모든 기능을 갖춘 블로그를 즉시 배포할 수 있습니다.

info

전체 옵션 목록은 블로그 플러그인 API 레퍼런스 문서를 참고하세요.

초기 설정

여러분의 사이트에 블로그를 설정하고 싶다면 먼저 blog 디렉터리를 만들어주어야 합니다.

그리고 docusaurus.config.js 파일에 블로그 연결을 위한 아이템 링크를 추가해줍니다.

docusaurus.config.js
module.exports = {
themeConfig: {
// ...
navbar: {
items: [
// ...
{to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right'
],
},
},
};

새로운 글 추가하기

블로그를 게시하기 위해서는 블로그 디렉터리에 마크다운 파일을 만드세요.

예를 들어 website/blog/2019-09-05-hello-docusaurus-v2.md 라는 파일을 아래와 같은 내용으로 작성합니다.

website/blog/2019-09-05-hello-docusaurus-v2.md
---
title: Welcome Docusaurus v2
description: This is my first post on Docusaurus 2.
slug: welcome-docusaurus-v2
authors:
- name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
- name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
tags: [hello, docusaurus-v2]
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---
Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/).

<!--truncate-->

This is my first post on Docusaurus 2.

A whole bunch of exploration to follow.
note

도큐사우루스는 YYYY-MM-DD-my-blog-post-title.md 형태의 파일/폴더 이름에서 YYYY-MM-DD 형식의 날짜값을 추출합니다.

이런 형태의 명명 규칙은 선택 사항이며 프런트매터에서 날짜를 지정할 수 있습니다.

지원 형식 예시
  • 2021-05-28-my-blog-post-title.md
  • 2021-05-28-my-blog-post-title.mdx
  • 2021-05-28-my-blog-post-title/index.md
  • 2021-05-28/my-blog-post-title.md
  • 2021/05/28/my-blog-post-title.md
  • 2021/05-28-my-blog-post-title.md
  • 2021/05/28/my-blog-post-title/index.md
  • ...
tip

폴더를 사용하면 마크다운 파일과 블로그 게시물 이미지를 쉽게 찾을 수 있습니다.

프런트매터에서 필수로 기재해야 하는 필드는 title입니다. 하지만 블로그 게시물 작성 시에는 작성자 정보와 같은 메타데이터를 추가할 수 있는 옵션이 있습니다. 사용할 수 있는 필드는 API 문서를 참고하세요.

블로그 게시물 목록

블로그 인덱스 페이지(기본값은 /blog)은 모든 블로그 게시물이 한 곳에서 표시되는 블로그 목록 페이지입니다.

게시물 작성 시 <!--truncate--> 마커를 사용하면 게시물이 보여질 때 요약문이 먼저 표시됩니다. <!--truncate--> 위에 작성된 내용이 요약문이 됩니다. 예를 들면 아래와 같은 형식입니다.

---
title: Truncation Example
---
All these will be part of the blog post summary.

Even this.

<!--truncate-->

But anything from here on down will not be.

Not this.

Or this.

기본적으로 각 블로그 목록 페이지에는 10개 게시물이 표시되지만 플로그인 설정에서 postsPerPage 옵션으로 설정할 수 있습니다. postsPerPage: 'ALL'을 설정하면 페이지 번호 영역이 비활성화되고 모든 게시물이 첫 페이지에 표시됩니다. 검색엔진최적화를 위해 블로그 게시물 목록 페이지에 메타 설명을 추가할 수 있습니다.

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogTitle: 'Docusaurus blog!',
blogDescription: 'A Docusaurus powered blog!',
postsPerPage: 'ALL',
},
},
],
],
};

블로그 사이드바

블로그 사이드바에는 최근 블로그 게시물이 표시됩니다. 기본적으로 표시되는 항목 수는 5개이지만 플러그인 설정에서 blogSidebarCount 옵션으로 설정할 수 있습니다. blogSidebarCount: 0을 설정하면 사이드바가 비활성화되고 해당 영역도 삭제됩니다. 해당 설정 시에는 메인 영역의 너비가 늘어나게 됩니다. blogSidebarCount: 'ALL'을 설정하면 모든 게시물이 표시됩니다.

blogSidebarTitle 옵션을 설정해 사이드바 제목 텍스트를 변경할 수 있습니다. 예를 들어 blogSidebarCount: 'ALL' 설정 시에는 기본적으로 표시되는 "Recent posts" 대신 "All posts"으로 제목을 변경할 수 있습니다.

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogSidebarTitle: 'All posts',
blogSidebarCount: 'ALL',
},
},
],
],
};

블로그 게시물 작성자

프런트매터에서 authors 필드를 사용해 블로그 게시물 작성자를 설정합니다.

작성자 직접 설정

프런트매터 안에 직접 블로그 게시물 작성자를 설정할 수 있습니다.

my-blog-post.md
---
authors:
name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
---
tip

처음 시작하거나 비정기적으로 작성하는 작성자에게 가장 적합한 옵션입니다.

info

프런트매터에서 authors 필드 사용을 권장하지만 기존에 사용하던 author_* 필드도 계속 지원합니다.

my-blog-post.md
---
author: Joel Marcey
author_title: Co-creator of Docusaurus 1
author_url: https://github.com/JoelMarcey
author_image_url: https://github.com/JoelMarcey.png
---

작성자 미리 설정

정기적으로 블로그 게시물을 작성하는 작성자는 매번 블로그 게시물에 직접 작성자 정보를 입력하는 것은 지겨운 일이 될 수 있습니다.

설정 파일에 해당 작성자를 전역으로 사용하도록 선언할 수 있습니다.

website/blog/authors.yml
jmarcey:
name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png

slorber:
name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
tip

authorsMapPath 플러그인 옵션을 사용해 경로를 설정하세요. JSON 형식도 지원합니다.

블로그 게시물 프런트매터에서 설정 파일에 선언된 전역 작성자를 참조할 수 있습니다.

my-blog-post.md
---
authors: jmarcey
---
info

authors 설정은 매우 유연하며 고급 사용자에게 적합합니다.

직접 설정과 미리 설정 방식 같이 사용
미리 설정한 작성자를 사용하며 필요한 경우 직접 작성자를 설정할 수 있습니다.
my-blog-post.md
---
authors:
- jmarcey
- slorber
- name: Inline Author name
title: Inline Author Title
url: https://github.com/inlineAuthor
image_url: https://github.com/inlineAuthor
---
미리 설정한 작성자 정보 덮어쓰기

블로그 게시물마다 미리 설정한 작성자 데이터를 직접 설정할 수 있습니다.

my-blog-post.md
---
authors:
- key: jmarcey
title: Joel Marcey's new title
- key: slorber
name: Sébastien Lorber's new name
---
작성자 설정 파일 현지화

설정 파일을 현지화할 수 있습니다. 아래 경로에 현지화된 사본을 생성합니다.

website/i18n/<locale>/docusaurus-plugin-content-blog/authors.yml

예상 읽기 시간

도큐사우루스는 사용한 단어 숫자에 따라 각 블로그 게시물을 읽는데 필요한 시간을 생성합니다. 해당 기능을 사용자 지정하기 위한 옵션도 제공합니다.

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
showReadingTime: true, // When set to false, the "x min read" won't be shown
readingTime: ({content, frontMatter, defaultReadingTime}) =>
defaultReadingTime({content, options: {wordsPerMinute: 300}}),
},
},
],
],
};

readingTime 콜백은 3가지 매개변수를 받습니다. 블로그 콘텐츠 문자열, 문자열 키와 값으로 구성된 프런트매터, 기본 예상 읽기 시간 함수입니다. 숫자(분 단위 읽기 시간) 또는 undefined(해당 페이지의 예상 읽기 시간 비활성화)를 반환합니다.

기본 읽기 시간은 추가 옵션을 설정할 수 있습니다. wordsPerMinute은 숫자로 설정하고(기본값: 300), wordBound 문자열을 받아 부울린값으로 반환하는 함수입니다. wordBound에 전달된 문자열이 제외 대상 단어(기본값: 공백문자, 탭문자, 줄바꿈 문자)인 경우 true값을 반환합니다.

tip

필요에 따라 콜백 설정을 수정할 수 있습니다.

Disable reading time on one page:

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
showReadingTime: true,
readingTime: ({content, frontMatter, defaultReadingTime}) =>
frontMatter.hide_reading_time ? undefined : defaultReadingTime({content}),
},
},
],
],
};

Usage:

---
hide_reading_time: true
---

This page will no longer display the reading time stats!

피드

feedOptions 설정을 전달해 RSS/Atom 피드를 생성할 수 있습니다. RSS와 Atom 피드는 기본적으로 생성됩니다. 피드 생성을 하지 않으려면 feedOptions.type 항목 값을 null로 설정해주세요.

type BlogOptions = {
feedOptions?: {
type?: 'rss' | 'atom' | 'all' | null;
title?: string;
description?: string;
copyright: string;
language?: string; // http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes 에서 사용할 수 있는 값을 확인할 수 있습니다.
};
};

예를 들어 아래와 같이 설정할 수 있습니다.

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
feedOptions: {
type: 'all',
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
},
},
},
],
],
};

피드에 연결하는 방법은 아래와 같습니다.

RSS 피드

https://{your-domain}/blog/rss.xml

Atom 피드

https://{your-domain}/blog/atom.xml

블로그 기능 확장하기

블로그 전용 모드

도큐사우루스 2에서는 랜딩 페이지 없이 블로그 게시물 목록을 인덱스 페이지로 사용할 수 있습니다. routeBasePath 항목값을 '/'로 설정하면 루트 경로임을 나타냅니다.

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: false,
blog: {
path: './blog',
routeBasePath: '/', // 항목값을 '/'으로 설정합니다.
},
},
],
],
};
caution

기존 랜딩 페이지로 사용하던 ./src/pages/index.js 파일을 삭제해주어야 합니다. 그렇지 않으면 같은 경로에 2개 파일이 연결되어집니다.

여러 개의 블로그 운영하기

클래식 테마는 웹사이트에서 하나의 블로그만 관리한다고 가정하고 있습니다. 그래서 하나의 블로그 플러그인 인스턴스만 포함하고 있습니다. 물론 하나의 웹사이트에서 여러 개의 블로그를 운영하는 것도 가능합니다. docusaurus.config.js 옵션 중에서 plugins 항목을 설정해서 블로그 플러그인을 추가하면 또 하나의 블로그를 가질 수 있습니다.

routeBasePath 항목값은 두 번째 블로그에 접근할 수 있는 URL 경로를 설정해주어야 합니다. routeBasePath 항목값을 첫 번째 블로그와 다르게 설정한 것을 확인하세요. 그렇지 않으면 경로 충돌이 발생할 수 있습니다. 그리고 path 항목값도 두 번째 블로그 파일이 담겨있는 디렉터리를 설정해줍니다.

멀티 인스턴스 플러그인에서 설명하는 것처럼 플러그인은 유일한 id 항목값으로 설정해야 합니다.

docusaurus.config.js
module.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-content-blog',
{
/**
* 멀티 인스턴스 플러그인 적용 시 필수값으로 설정해야 합니다.
*/
id: 'second-blog',
/**
* 사이트에서 블로그 연결 시 사용할 URL 경로를 설정합니다.
* *절대* URL 끝에 슬래시를 붙이지 마세요.
*/
routeBasePath: 'my-second-blog',
/**
* 사이트 디렉터리 기준으로 상대 경로를 지정합니다.
*/
path: './my-second-blog',
},
],
],
};

예제로 만든 두 번째 블로그를 확인해볼 수 있습니다.