버전: 2.3.1

블로그

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

정보

초기 설정

여러분의 사이트에 블로그를 설정하고 싶다면 먼저 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.

프런트 매터는 블로그 게시물에 더 많은 메타데이터(예: 작성자 정보)를 추가할 때 유용하지만 도큐사우루스는 프런트 매터 없이 필요한 모든 메타데이터를 유추할 수 있습니다. 사용할 수 있는 필드는 API 문서를 참고하세요.

블로그 게시물 목록

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

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

---
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',
        },
      },
    ],
  ],
};

블로그 게시물 작성일

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

지원 형식 예시

패턴	예
단일 파일	`2021-05-28-my-blog-post-title.md`
MDX 파일	`2021-05-28-my-blog-post-title.mdx`
단일 폴더 + `index.md`	`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`
중첩된 폴더 + `index.md`	`2021/05/28/my-blog-post-title/index.md`
경로 중간에 부분적으로 중첩된 날짜 기준 폴더	`category/2021/05-28-my-blog-post-title.md`

날짜는 경로에서 제거되고 URL 슬러그 시작 부분에 추가됩니다.

팁

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

이런 형태의 명명 규칙은 선택 사항이며 프런트매터에서 날짜를 지정할 수 있습니다. 프런트 매터는 날짜/시간 표기법이 지원되는 YAML 구문을 따르므로 더 세분화된 게시 날짜가 필요한 경우 프런트 매터를 사용할 수 있습니다. 예를 들어 같은 날 게시된 게시물이 여러 개인 경우 시간에 따라 정렬할 수 있습니다.

earlier-post.md
---
date: 2021-09-13T10:00
---

later-post.md
---
date: 2021-09-13T18:00
---

블로그 게시물 작성자

프런트매터에서 authors 필드를 사용해 블로그 게시물 작성자를 설정합니다. 작성자는 name 또는 image_url 중 하나의 정보가 필요합니다. 도큐사우루스는 url, email, title 같은 정보를 사용하고 있지만 다른 정보도 추가할 수 있습니다.

작성자 직접 설정

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

Single author
Multiple 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
  email: [email protected]
---

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
    email: [email protected]
  - name: Sébastien Lorber
    title: Docusaurus maintainer
    url: https://sebastienlorber.com
    image_url: https://github.com/slorber.png
---

팁

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

정보

프런트매터에서 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
  email: [email protected]

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

팁

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

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

Single author
Multiple authors

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

my-blog-post.md
---
authors: [jmarcey, slorber]
---

정보

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

프런트매터나 저자 정보맵에 선언된 저자 정보에는 이름 또는 아바타 또는 두가지 모두 선언되어야 합니다. 모든 게시물의 저자 정보에 이름이 없다면 도큐사우루스에서는 해당 아바타를 간략하게 표시합니다. 어떤 식으로 표시되는지 테스트 게시물에서 확인할 수 있습니다.

피드 생성

RSS 피드는 작성자가 피드에 표시될 수 있게 작성자 이메일을 설정해야 합니다.

예상 읽기 시간

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

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값을 반환합니다.

팁

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

Per-post disabling
Passing options
Using custom algorithms

페이지의 예상 읽기 시간 기능을 비활성화합니다.

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

사용법:

---
hide_reading_time: true
---

This page will no longer display the reading time stats!

기본 읽기 시간 함수에 옵션값을 전달합니다.

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          readingTime: ({content, defaultReadingTime}) =>
            defaultReadingTime({content, options: {wordsPerMinute: 100}}),
        },
      },
    ],
  ],
};

사용자 지정 읽기 시간 기능을 사용합니다.

docusaurus.config.js
const myReadingTime = require('./myReadingTime');

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          readingTime: ({content}) => myReadingTime(content),
        },
      },
    ],
  ],
};

피드

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

type FeedType = 'rss' | 'atom' | 'json';

type BlogOptions = {
  feedOptions?: {
    type?: FeedType | 'all' | FeedType[] | null;
    title?: string;
    description?: string;
    copyright: string;
    language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
    /** BlogFeedItems 구성에 대한 제어 허용 */
    createFeedItems?: (params: {
      blogPosts: BlogPost[];
      siteConfig: DocusaurusConfig;
      outDir: string;
      defaultCreateFeedItems: (params: {
        blogPosts: BlogPost[];
        siteConfig: DocusaurusConfig;
        outDir: string;
      }) => Promise<BlogFeedItem[]>;
    }) => Promise<BlogFeedItem[]>;
  };
};

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

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          feedOptions: {
            type: 'all',
            copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
            createFeedItems: async (params) => {
              const {blogPosts, defaultCreateFeedItems, ...rest} = params;
              return defaultCreateFeedItems({
                // 피드에 최근 블로그 게시물 10개만 유지
                blogPosts: blogPosts.filter((item, index) => index < 10),
                ...rest,
              });
            },
          },
        },
      },
    ],
  ],
};

피드는 다음에서 확인할 수 있습니다.

RSS
Atom
JSON

https://example.com/blog/rss.xml

https://example.com/blog/atom.xml

https://example.com/blog/feed.json

블로그 기능 확장하기

블로그 전용 모드

도큐사우루스 2에서는 별도의 랜딩 페이지 없이 블로그 게시물 목록을 인덱스 페이지로 사용할 수 있습니다. routeBasePath를 '/'로 설정해 하위 경로 example.com/blog/ 대신 루트 경로 example.com/를 사용해 블로그를 제공합니다.

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: false, // 옵션: 문서 플러그인 사용 여부
        blog: {
          routeBasePath: '/', // 사이트 루트에서 블로그 제공
          /* 다른 블로그 옵션 */
        },
      },
    ],
  ],
};

주의

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

팁

문서 용도로만 사용하려는 사용자를 위한 "문서 전용 모드"도 있습니다. routeBasePath에 대한 자세한 지침이나 설명은 문서 전용 모드 항목을 참고하세요.

여러 개의 블로그 운영하기

클래식 테마는 웹사이트에서 하나의 블로그만 관리한다고 가정하고 있습니다. 그래서 하나의 블로그 플러그인 인스턴스만 포함하고 있습니다. 물론 하나의 웹사이트에서 여러 개의 블로그를 운영하는 것도 가능합니다. 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',
      },
    ],
  ],
};

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

블로그

초기 설정​

새로운 글 추가하기​

블로그 게시물 목록​

블로그 사이드바​

블로그 게시물 작성일​

블로그 게시물 작성자​

작성자 직접 설정​

작성자 미리 설정​

예상 읽기 시간​

피드​

블로그 기능 확장하기​

블로그 전용 모드​

여러 개의 블로그 운영하기​