版本：3.5.2

部落格

部落格功能讓您可以立即部署全功能的部落格。

資訊

初始設定

若要設定您網站的部落格，請先建立一個 blog 目錄。

接著，將項目連結新增到 docusaurus.config.js 中的部落格

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

增加文章

若要在部落格中發布，請在 blog 目錄中建立一個 Markdown 檔案。

例如，在 website/blog/2019-09-05-hello-docusaurus.md 中建立一個檔案

website/blog/2019-09-05-hello-docusaurus.md
---
title: Welcome Docusaurus
description: This is my first post on Docusaurus.
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
    socials:
      x: joelmarcey
      github: JoelMarcey
  - name: Sébastien Lorber
    title: Docusaurus maintainer
    url: https://sebastienlorber.com
    image_url: https://github.com/slorber.png
    socials:
      x: sebastienlorber
      github: slorber
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.dev.org.tw/).

<!-- truncate -->

This is my first post on Docusaurus 2.

A whole bunch of exploration to follow.

frontmatter 有助於為你的部落格文章加入更多元資料，例如作者資訊；不過，Docusaurus 會在沒有 frontmatter 的情況下推論所有必要的元資料。如要查看所有可能的欄位，請參閱 API 文件。

部落格清單

部落格的索引頁（預設在 /blog）是 部落格清單頁，在其中會收集顯示所有部落格文章。

在你的部落格文章中使用  標記，以表示瀏覽所有已發布部落格文章時將顯示為摘要的內容。 以上的所有內容都會成為摘要的一部分。請注意，截斷標記以上的部分必須是獨立的可渲染 Markdown。例如

website/blog/my-post.md
---
title: Markdown blog truncation example
---

All these will be part of the blog post summary.

<!-- truncate -->

But anything from here on down will not be.

對於使用 .mdx 延伸資料名的檔案，請改用 MDX 註解 {/* truncate */}

website/blog/my-post.mdx
---
title: MDX blog truncation Example
---

All these will be part of the blog post summary.

{/* truncate */}

But anything from here on down will not be.

每個部落格清單頁預設顯示 10 篇文章，不過你可以控制外掛組態中的 postsPerPage 選項進行分頁。如果你設定 postsPerPage: 'ALL'，分頁將會停用，所有文章都將顯示在第一頁。你也可以為部落格清單頁新增後設描述，以改善 SEO

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

部落格側欄會顯示最近的部落格文章。預設顯示的項目數量為 5，不過你可以使用外掛組態中的 blogSidebarCount 選項進行自訂。透過設定 blogSidebarCount: 0，側欄將會完全停用，同時也會移除容器。這將會增加主要容器的寬度。特別的是，如果你已設定 blogSidebarCount: 'ALL'，將會顯示所有文章。

你也可以使用 blogSidebarTitle 選項變更側欄標題文字。例如，如果你已設定 blogSidebarCount: 'ALL'，可以改成顯示「所有文章」，而不是預設的「最近文章」

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

部落格文章日期

Docusaurus 會從許多模式中擷取 YYYY-MM-DD 日期，例如 YYYY-MM-DD-my-blog-post-title.md 或 YYYY/MM/DD/my-blog-post-title.md。這可以讓你輕鬆依年、依月群組部落格文章，或使用扁平結構。

支援的日期擷取模式

模式	範例
單一檔案	`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`

Docusaurus 可以使用以上任一命名模式從文章中提取日期。建議選擇一種模式並將其應用於所有文章，以避免混淆。

提示

使用資料夾將部落格文章圖片與 Markdown 檔案並置會很方便。

此命名慣例是可選的，你也可以提供日期作為前置事項。由於前置事項遵循支援 datetime 符號的 YAML 語法，如果你需要更精確的發佈日期，可以使用前置事項。例如，如果你有多篇文章在同一天發佈，你可以根據時間對它們進行排序

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

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

部落格文章作者

使用authors前置事項欄位宣告部落格文章作者。作者應至少有name或image_url。Docusaurus 使用諸如url、email和title等資訊，但也允許任何其他資訊。

內嵌作者

部落格文章作者可以在前置事項內直接宣告

單一作者
多個作者

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]
  socials:
    x: joelmarcey
    github: JoelMarcey
---

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

提示

此選項最適合入門，或休閒的不定時作者。

資訊

建議使用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]
  socials:
    x: joelmarcey
    github: JoelMarcey

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

提示

使用authorsMapPath外掛選項來組態路徑。JSON 也受支援。

在部落格文章前置事項中，你可以參照在全球組態檔中宣告的作者

單一作者
多個作者

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
---

將作者的設定檔在地化

設定檔可以在地化，只要在 localhost:3000/docs/zh-TW/docs/blog/#global-authors 產生它的在地化複本即可。

website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml

透過 front matter 或作者清單宣告的作者，需要有姓名或化身，或同時都有。如果文章的所有作者都沒有姓名，Docusaurus 會緊湊地顯示他們的化身。請參閱這篇測試文章以瞭解效果。

Feed 產生

RSS feed 需要設定作者的電子郵件，讓作者出現在 feed 中。

作者頁面

作者頁面功能是選用的，主要適用於多作者網誌。

您可以針對每位作者獨立啟用這個功能，只要在全域作者設定中新增 page: true 屬性即可。

website/blog/authors.yml
slorber:
  name: Sébastien Lorber
  page: true # Turns the feature on - route will be /authors/slorber

jmarcey:
  name: Joel Marcey
  page:
    # Turns the feature on - route will be /authors/custom-author-url
    permalink: '/custom-author-url'

現在，網誌外掛程式會產生：

屬於每個作者的專屬作者頁面（範例），列出他們撰寫的所有網誌文章。
列出所有這些作者的作者索引頁面（範例），順序按照他們在 authors.yml 中出現的順序。

關於內嵌作者

只有全域作者可以啟用這個功能。內嵌作者不受支援。

網誌文章標籤

標籤是在 front matter 中宣告，會引進另一個分類面向。

可以內嵌定義標籤，或參考在 標籤檔案（選用，通常是 blog/tags.yml）中宣告的預先定義標籤。

在下列範例中：

docusaurus 參考在 blog/tags.yml 中宣告的預先定義標籤金鑰。
Releases 是一個內嵌標籤，因為它不存在於 blog/tags.yml 中。

blog/my-post.md
---
title: 'My blog post'
tags:
  - Releases
  - docusaurus
---

Content

blog/tags.yml
docusaurus:
  label: 'Docusaurus'
  permalink: '/docusaurus'
  description: 'Blog posts related to the Docusaurus framework'

閱讀時間

Docusaurus 會根據字數，為每篇網誌文章產生閱讀時間估計。我們提供一個選項來自訂這個。

docusaurus.config.js
export default {
  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 回呼接收三個參數：部落格內容文字（以字串形式）、前言（以字串金鑰和其值形式記載）以及預設閱讀時間函式。它會回傳一個數字（以分鐘為單位的閱讀時間）或 undefined（停用此頁面的閱讀時間）。

預設閱讀時間可以接受其他選項： wordsPerMinute 作為數字（預設：300），以及 wordBound 作為字串到布林值的函式。如果傳遞給 wordBound 的字串應為一字元界線（預設為空白、製表符和換行符），則函式應回傳 true。

提示

使用回呼滿足所有自訂需求

分別停用文章
傳遞選項
使用自訂演算法

在單一頁面上停用閱讀時間

docusaurus.config.js
export default {
  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
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          readingTime: ({content, defaultReadingTime}) =>
            defaultReadingTime({content, options: {wordsPerMinute: 100}}),
        },
      },
    ],
  ],
};

使用自訂實作的閱讀時間

docusaurus.config.js
import myReadingTime from './myReadingTime';

export default {
  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
    limit?: number | false | null; // defaults to 20
    // XSLT permits browsers to style and render nicely the feed XML files
    xslt?:
      | boolean
      | {
          //
          rss?: string | boolean;
          atom?: string | boolean;
        };
    // Allow control over the construction of BlogFeedItems
    createFeedItems?: (params: {
      blogPosts: BlogPost[];
      siteConfig: DocusaurusConfig;
      outDir: string;
      defaultCreateFeedItems: (params: {
        blogPosts: BlogPost[];
        siteConfig: DocusaurusConfig;
        outDir: string;
      }) => Promise<BlogFeedItem[]>;
    }) => Promise<BlogFeedItem[]>;
  };
};

範例用法

docusaurus.config.js
export default {
  // ...
  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({
                // keep only the 10 most recent blog posts in the feed
                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

進階主題

僅限部落格模式

你可以不用專屬起始頁來執行你的 Docusaurus 網站，而是使用部落格文章清單頁面作為首頁。將 routeBasePath 設為 '/'，透過根路徑 example.com/ 而不是子路徑 example.com/blog/ 來提供部落格。

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: false, // Optional: disable the docs plugin
        blog: {
          routeBasePath: '/', // Serve the blog at the site's root
          /* other blog options */
        },
      },
    ],
  ],
};

警告

別忘了刪除現有的 ./src/pages/index.js 的起始頁，否則會有兩個檔案對應到相同的路徑！

警告

如果你停用了文件插入外掛程式，別忘了在設定檔的其他地方刪除文件插入外掛程式的參考。特別注意，移除導航列項目相關的文件。

提示

對於只想使用文件的人也有「僅限文件」模式。進一步的說明或更詳細的 routeBasePath 解釋，請參閱僅限文件模式。

多個部落格

預設值下，Classic 主題會假設每個網站只有一個部落格，因此只會包含一個部落格外掛的執行個體。如果你希望於一個網站上有多個部落格，也可以這麼做！你可以指定另一個部落格外掛的方式，在 `docusaurus.config.js` 的 `plugins` 選項中新增另一個部落格。

將 `routeBasePath` 設定成你希望第二個部落格可以被存取的網址路由。請注意，此處的 `routeBasePath` 必須不同於第一個部落格，否則路徑可能會衝突！同時也要設定 `path` 為包含第二個部落格條目的資料夾路徑。

如同多執行個體外掛文件中所述，你需要將一個獨特 ID 指定給外掛程式。

docusaurus.config.js
export default {
  // ...
  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        /**
         * Required for any multi-instance plugin
         */
        id: 'second-blog',
        /**
         * URL route for the blog section of your site.
         * *DO NOT* include a trailing slash.
         */
        routeBasePath: 'my-second-blog',
        /**
         * Path to data on filesystem relative to site dir.
         */
        path: './my-second-blog',
      },
    ],
  ],
};

舉例來說，我們於此處上架了第二個部落格。

初始設定​

增加文章​

部落格清單​

部落格側欄​

部落格文章日期​

部落格文章作者​

內嵌作者​

全球作者​

作者頁面​

網誌文章標籤​

閱讀時間​

摘要​

進階主題​

僅限部落格模式​

多個部落格​