📦 plugin-content-blog

提供網誌功能，且是 Docusaurus 的預設網誌外掛程式。

有些功能僅限於正式版本

動態消息功能會從建置輸出中萃取資料，而且只在正式版本中開啟。

安裝

npm

npm install --save @docusaurus/plugin-content-blog

Yarn

yarn add @docusaurus/plugin-content-blog

pnpm

pnpm add @docusaurus/plugin-content-blog

秘訣

如果您使用預設值 @docusaurus/preset-classic，不需要將這個外掛程式安裝為相依性。

您可以透過 預設值選項 來設定這個外掛程式。

配置

接受的欄位

名稱	型別	預設	描述
path	string	'blog'	相對於網站目錄，前往檔案系統的部落格內容目錄的路徑。
editUrl	string | EditUrlFn	未定義	編輯您網站的基礎網址。最終的網址是透過 editUrl + relativePostPath 計算的。使用函式允許針對每個檔案進行更細緻的控制。完全略過這個變數會停用編輯連結。
editLocalizedFiles	boolean	false	編輯網址目標將會是語言本土化的檔案，而不是原始未語言本土化的檔案。在 editUrl 是函式的同時忽略它。
blogTitle	string	'部落格'	部落格標題讓 SEO 更佳。
blogDescription	string	'部落格'	部落格元資料描述讓 SEO 更佳。
blogSidebarCount	number | 'ALL'	5	在部落格側欄中顯示的部落格貼文元素數量。'ALL' 顯示所有部落格貼文；0 停用。
blogSidebarTitle	string	'最新貼文'	部落格側欄的標題。
routeBasePath	string	'blog'	您網站部落格區的網址路由。不要包含尾斜線。使用 / 將部落格置於根路徑。
tagsBasePath	string	'tags'	您部落格標籤區的網址路由。將附加至 routeBasePath。
pageBasePath	string	'page'	您部落格頁面區的網址路由。將附加至 routeBasePath。
archiveBasePath	string | null	'archive'	您部落格封存區的網址路由。將附加至 routeBasePath。不要包含尾斜線。使用 null 停用封存產生。
authorsBasePath	string	'authors'	您部落格作者頁面的網址路由。將附加至 path。
include	string[]	['**/*.{md,mdx}']	相對於內容路徑，與 Markdown 檔案匹配的 glob 模式陣列，組建中。
exclude	string[]	查看範例配置	與 Markdown 檔案匹配的 glob 模式陣列，排除。作為基於 include 選項的細化。
postsPerPage	number | 'ALL'	10	在清單頁顯示的每頁貼文數量。使用 'ALL' 在一個清單頁顯示所有貼文。
blogListComponent	string	'@theme/BlogListPage'	部落格清單頁的根元件。
blogPostComponent	string	'@theme/BlogPostPage'	各個部落格貼文頁的根元件。
blogTagsListComponent	string	'@theme/BlogTagsListPage'	標籤清單頁的根元件。
blogTagsPostsComponent	string	'@theme/BlogTagsPostsPage'	「包含標籤的文章」頁面的根組件。
blogArchiveComponent	string	'@theme/BlogArchivePage'	部落格文章資料庫頁面的根組件。
blogAuthorsPostsComponent	string	'@theme/Blog/Pages/BlogAuthorsPostsPage'	部落格作者頁面的根組件。
blogAuthorsListComponent	string	'@theme/Blog/Pages/BlogAuthorsListPage'	部落格作者頁面索引的根組件。
remarkPlugins	any[]	[]	傳遞給 MDX 的 Remark 插件。
rehypePlugins	any[]	[]	傳遞給 MDX 的 Rehype 插件。
rehypePlugins	any[]	[]	Recma 插件傳遞給 MDX。
beforeDefaultRemarkPlugins	any[]	[]	在傳遞給 MDX 的預設 Docusaurus Remark 插件之前傳遞的自訂 Remark 插件。
beforeDefaultRehypePlugins	any[]	[]	在傳遞給 MDX 的預設 Docusaurus Rehype 插件之前傳遞的自訂 Rehype 插件。
truncateMarker	RegExp	/<!--\s*truncate\s*-->/ | \{\/\*\s*truncate\s*\*\/\}/	標記摘要結束處的截斷標記。
showReadingTime	boolean	true	顯示部落格文章的預估閱讀時間。
readingTime	ReadingTimeFn	預設閱讀時間	自訂顯示的閱讀時間數字的 callback。
authorsMapPath	string	'authors.yml'	相對於部落格內容目錄的作者對應檔路徑。
feedOptions	請參閱下方	{type: ['rss', 'atom']}	部落格 feed。
feedOptions.type	FeedType | FeedType[] | 'all' | null	必填	要產生的 feed 類型。使用 null 停用產生。
feedOptions.createFeedItems	CreateFeedItemsFn | undefined	未定義	一個可用的選用函式，用於轉換及/或過濾 feed 中的項目。
feedOptions.limit	數字 | null | false	20	將 feed 的文章限制在指定的數字內，false 或是 null 表示所有文章。預設為 20。
feedOptions.title	string	siteConfig.title	feed 的標題。
feedOptions.description	string	`${siteConfig.title} Blog`	feed 的描述。
feedOptions.copyright	string	未定義	版權訊息。
feedOptions.xslt	布林 | FeedXSLTOptions	未定義	版權訊息。
feedOptions.language	字串（詳情請見 文件 的可能值）	未定義	feed 的語言元資料。
sortPosts	'descending' | 'ascending'	'descending'	控制部落格文章排序的方向。
processBlogPosts	ProcessBlogPostsFn	未定義	一個可用的選用函式，用於轉換部落格文章（過濾、修改、刪除等）。
showLastUpdateAuthor	boolean	false	是否顯示最後更新部落格文章的作者。
showLastUpdateTime	boolean	false	是否顯示部落格文章最後更新日期。這需要在建置時存取 git 歷程記錄，因此不會與淺層複製一起正常運作（CI 系統的常見預設）。對於 GitHub actions/checkout，請使用 fetch-depth: 0。
tags	字串 | false | null | undefined	tags.yml	預先定義標籤的 YAML 標籤檔案路徑。相對於部落格文章目錄。
onInlineTags	'ignore' | 'log' | 'warn' | 'throw'	warn	當部落格文章中包含內嵌標籤（未出現於預先定義標籤清單中，通常為 tags.yml）時的外掛行為。
onUntruncatedBlogPosts	'ignore' | 'log' | 'warn' | 'throw'	warn	當部落格文章不包含截斷標記時的外掛行為。

類型

EditUrlFn

type EditUrlFunction = (params: {
  blogDirPath: string;
  blogPath: string;
  permalink: string;
  locale: string;
}) => string | undefined;

ReadingTimeFn

type ReadingTimeOptions = {
  wordsPerMinute: number;
  wordBound: (char: string) => boolean;
};

type ReadingTimeCalculator = (params: {
  content: string;
  frontMatter?: BlogPostFrontMatter & Record<string, unknown>;
  options?: ReadingTimeOptions;
}) => number;

type ReadingTimeFn = (params: {
  content: string;
  frontMatter: BlogPostFrontMatter & Record<string, unknown>;
  defaultReadingTime: ReadingTimeCalculator;
}) => number | undefined;

FeedType

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

FeedXSLTOptions

允許調整部落格 XML Feed 的樣式，以便瀏覽器使用 XSLT 漂亮地呈現它們。

• 使用 true 以讓部落格使用內建的 .xsl 和 .css 檔案為部落格 Feed 調整樣式
• 使用非真值（undefined | null | false）來停用此功能
• 使用 string 來提供自訂 .xsl 檔案的文件路徑，相對於部落格文章資料夾。依慣例，你必須提供一個與名稱完全相同的 .css 檔案。

type FeedXSLTOptions =
  | boolean
  | undefined
  | null
  | {
      rss?: string | boolean | null | undefined;
      atom?: string | boolean | null | undefined;
    };

CreateFeedItemsFn

type CreateFeedItemsFn = (params: {
  blogPosts: BlogPost[];
  siteConfig: DocusaurusConfig;
  outDir: string;
  defaultCreateFeedItemsFn: CreateFeedItemsFn;
}) => Promise<BlogFeedItem[]>;

ProcessBlogPostsFn

type ProcessBlogPostsFn = (params: {
  blogPosts: BlogPost[];
}) => Promise<void | BlogPost[]>;

範例組態

你可以透過預設選項或外掛選項來組態此外掛。

秘訣

大多數 Docusaurus 使用者透過預設選項來組態此外掛。

預設值選項

如果你使用預設值，請透過 預設值選項 來組態此外掛

docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          path: 'blog',
          // Simple use-case: string editUrl
          // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
          // Advanced use-case: functional editUrl
          editUrl: ({locale, blogDirPath, blogPath, permalink}) =>
            `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`,
          editLocalizedFiles: false,
          blogTitle: 'Blog title',
          blogDescription: 'Blog',
          blogSidebarCount: 5,
          blogSidebarTitle: 'All our posts',
          routeBasePath: 'blog',
          include: ['**/*.{md,mdx}'],
          exclude: [
            '**/_*.{js,jsx,ts,tsx,md,mdx}',
            '**/_*/**',
            '**/*.test.{js,jsx,ts,tsx}',
            '**/__tests__/**',
          ],
          postsPerPage: 10,
          blogListComponent: '@theme/BlogListPage',
          blogPostComponent: '@theme/BlogPostPage',
          blogTagsListComponent: '@theme/BlogTagsListPage',
          blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
          remarkPlugins: [require('./my-remark-plugin')],
          rehypePlugins: [],
          beforeDefaultRemarkPlugins: [],
          beforeDefaultRehypePlugins: [],
          truncateMarker: /<!--\s*(truncate)\s*-->/,
          showReadingTime: true,
          feedOptions: {
            type: '',
            title: '',
            description: '',
            copyright: '',
            language: undefined,
            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,
              });
            },
          },
        },
      },
    ],
  ],
};

外掛選項

如果你使用獨立外掛，請直接提供選項給外掛

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        path: 'blog',
        // Simple use-case: string editUrl
        // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
        // Advanced use-case: functional editUrl
        editUrl: ({locale, blogDirPath, blogPath, permalink}) =>
          `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`,
        editLocalizedFiles: false,
        blogTitle: 'Blog title',
        blogDescription: 'Blog',
        blogSidebarCount: 5,
        blogSidebarTitle: 'All our posts',
        routeBasePath: 'blog',
        include: ['**/*.{md,mdx}'],
        exclude: [
          '**/_*.{js,jsx,ts,tsx,md,mdx}',
          '**/_*/**',
          '**/*.test.{js,jsx,ts,tsx}',
          '**/__tests__/**',
        ],
        postsPerPage: 10,
        blogListComponent: '@theme/BlogListPage',
        blogPostComponent: '@theme/BlogPostPage',
        blogTagsListComponent: '@theme/BlogTagsListPage',
        blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
        remarkPlugins: [require('./my-remark-plugin')],
        rehypePlugins: [],
        beforeDefaultRemarkPlugins: [],
        beforeDefaultRehypePlugins: [],
        truncateMarker: /<!--\s*(truncate)\s*-->/,
        showReadingTime: true,
        feedOptions: {
          type: '',
          title: '',
          description: '',
          copyright: '',
          language: undefined,
          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,
            });
          },
        },
      },
    ],
  ],
};

Markdown 前置事項

Markdown 文件可以使用以下 Markdown 前置事項 資料欄位，以 --- 行分隔兩側。

接受的欄位

名稱	型別	預設	描述
authors	作者	未定義	部落格文章作者（或單一作者）清單。閱讀 authors 指南以取得詳細的說明。即使是單一作者的部落格文章，也建議優先使用 authors 而非 author_* 前置事項欄位。
author	string	未定義	⚠️ 建議使用 authors。部落格文章作者的姓名。
author_url	string	未定義	⚠️ 建議使用 authors。連結到作者姓名的 URL。可以是 GitHub、Twitter、Facebook 個人資料 URL 等。
author_image_url	string	未定義	⚠️ 建議使用 authors。作者的縮圖圖片 URL。
author_title	string	未定義	⚠️ 建議使用 authors。作者的描述。
title	string	Markdown 標題	部落格文章標題。
date	string	檔案名稱或檔案建立時間	部落格文章的建立日期。如果未指定，可以從檔案或資料夾名稱擷取，例如 2021-04-15-blog-post.mdx、2021-04-15-blog-post/index.mdx、2021/04/15/blog-post.mdx。否則，就是 Markdown 檔案的建立時間。
tags	Tag[]	未定義	字串列表或具有兩個字串欄位 label 和 permalink 的物件，用於標記您的貼文。字串可以參考 標籤檔（通常為 tags.yml）的 key。
draft	boolean	false	草稿部落格文章只會在開發期間提供。
unlisted	boolean	false	未列出的部落格文章將在開發和正式環境同時提供。它們在正式環境中會「隱藏」、不會被索引、不包含在 Sitemap 中，而且只能由持有直接連結的使用者存取。
hide_table_of_contents	boolean	false	是否隱藏右方的目錄。
toc_min_heading_level	數字	2	目錄中顯示的最小標題層級。必須介於 2 到 6 之間，而且必須小於或等於最大值。
toc_max_heading_level	數字	3	目錄中顯示的最大標題層級。必須介於 2 到 6 之間。
keywords	string[]	未定義	關鍵字 meta 標籤，將會變成 <meta name="keywords" content="keyword1,keyword2,..."/> 出現在 <head> 中，由搜尋引擎使用。
description	string	第一行 Markdown 內容	文件說明，將會變成出現在 <head> 中的 <meta name="description" content="..."/> 和 <meta property="og:description" content="..."/>，由搜尋引擎使用。
image	string	未定義	封面或縮圖圖片，將會用作 <head> 中的 <meta property="og:image" content="..."/>，提升在社群媒體和訊息平台上的連結預覽效果。
slug	string	檔案路徑	允許自訂部落格文章 URL（/<routeBasePath>/<slug>）。支援多種模式：slug: my-blog-post、slug: /my/path/to/blog/post、slug: /。
last_update	FrontMatterLastUpdate	未定義	允許覆寫最後更新作者/日期。日期可以是任何 可解析的日期字串。

type FrontMatterLastUpdate = {date?: string; author?: string};

type Tag = string | {label: string; permalink: string};

// An author key references an author from the global plugin authors.yml file
type AuthorKey = string;

// Social platform name -> Social platform link
// Example: {MyPlatform: 'https://myplatform.com/myusername'}
// Pre-defined platforms ("x", "github", "twitter", "linkedin", "stackoverflow") accept handles:
// Example: {github: 'slorber'}
type AuthorSocials = Record<string, string>;

type Author = {
  key?: AuthorKey;
  name: string;
  title?: string;
  url?: string;
  image_url?: string;
  socials?: AuthorSocials;
};

// The front matter authors field allows various possible shapes
type Authors = AuthorKey | Author | (AuthorKey | Author)[];

範例

---
title: Welcome Docusaurus
authors:
  - slorber
  - yangshun
  - 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
tags: [docusaurus]
description: This is my first post on Docusaurus.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---

A Markdown blog post

標籤檔

使用 tags 外掛選項 設定 YAML 標籤檔的 路徑。

依據慣例，外掛會在內容資料夾的根目錄尋找 `tags.yml` 檔案。

這個檔案可以包含預先定義的標籤清單。使用 markdown 檔案中的前置標籤，您可以根據這些標籤的鍵值參照這些標籤，這要歸功於 標籤 前置標籤。

保持標籤一致

使用標籤檔案，您可以確保在外掛內容集中的標籤用量一致。使用 onInlineTags: 'throw' 外掛選項，強制執行這種一致性，並禁止使用即時宣告的內嵌標籤。

類型

提供的標籤檔案的 YAML 內容應符合以下格式

type Tag = {
  label?: string; // Tag display label
  permalink?: string; // Tag URL pathname segment
  description?: string; // Tag description displayed in the tag page
};

type TagsFileInput = Record<string, Partial<Tag> | null>;

範例

tags.yml

releases:
  label: 'Product releases'
  permalink: '/product-releases'
  description: 'Content related to product releases.'

# A partial tag definition is also valid
announcements:
  label: 'Announcements'

# An empty tag definition is also valid
# Other attributes will be inferred from the key
emptyTag:

content.md

---
tags: [releases, announcements, emptyTag]
---

# Title

Content

作者檔案

使用 作者 外掛選項，設定 YAML 作者檔案的路徑。

依據慣例，外掛會在部落格內容資料夾的根目錄尋找 `authors.yml` 檔案。

這個檔案可以包含預先定義的 全域性部落格作者 清單。使用 markdown 檔案中的前置標籤，您可以根據這些作者的鍵值參照這些作者，這要歸功於 作者 前置標籤。

類型

提供的作者檔案的 YAML 內容應符合以下格式

type AuthorsMapInput = {
  [authorKey: string]: AuthorInput;
};

type AuthorInput = {
  name?: string;
  title?: string;
  description?: string;
  imageURL?: string;
  url?: string;
  email?: string;
  page?: boolean | {permalink: string};
  socials?: Record<string, string>;
  [customAuthorAttribute: string]: unknown;
};

範例

tags.yml

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

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]
  page:
    permalink: '/joel-marcey'
  socials:
    x: joelmarcey
    github: JoelMarcey

blog/my-blog-post.md

---
authors: [slorber, jmarcey]
---

# My Blog Post

Content

i18n

首先閱讀 i18n 簡介。

翻譯檔案的位置

• 基底路徑：website/i18n/[locale]/docusaurus-plugin-content-blog
• 多重實例路徑：website/i18n/[locale]/docusaurus-plugin-content-blog-[pluginId]
• JSON 檔案：使用 docusaurus write-translations 萃取
• Markdown 檔案：website/i18n/[locale]/docusaurus-plugin-content-blog

範例檔案系統結構

website/i18n/[locale]/docusaurus-plugin-content-blog
│
│ # translations for website/blog
├── authors.yml
├── first-blog-post.md
├── second-blog-post.md
│
│ # translations for the plugin options that will be rendered
└── options.json