跳到主要内容

📦 plugin-content-pages

道格龙（Docusaurus）默认的页面插件。经典模板默认集成了此插件并采用默认配置。该插件提供了创建页面的功能。

安装​

npm install --save @docusaurus/plugin-content-pages
提示

如果你使用了 @docusaurus/preset-classic 预设，则无需单独安装此插件。

你可以通过 预设选项 配置此插件。

配置​

可用字段：

名称类型默认值说明
pathstring'src/pages'文件系统中相对于站点目录的数据路径。该目录下的组件会自动转换为页面。
editUrlstring | EditUrlFnundefined仅适用于 Markdown 页面。编辑站点的基础 URL。最终 URL 由 editUrl + relativePostPath 计算得出。使用函数可为每个文件实现更灵活的控制。完全省略该变量将禁用编辑链接。
editLocalizedFilesbooleanfalse仅适用于 Markdown 页面。编辑 URL 将指向本地化文件，而不是原始未本地化文件。当 editUrl 为函数时忽略此项。
routeBasePathstring'/'页面部分的 URL 路由。不要包含结尾斜杠。
includestring[]['**/*.{js,jsx,ts,tsx,md,mdx}']匹配的文件会被包含并处理。
excludestring[]见示例配置匹配的文件不会生成路由。
mdxPageComponentstring'@theme/MDXPage'每个 MDX 页面使用的组件。
remarkPlugins[]any[]传递给 MDX 的 Remark 插件。
rehypePlugins[]any[]传递给 MDX 的 Rehype 插件。
rehypePluginsany[][]传递给 MDX 的 Recma 插件。
beforeDefaultRemarkPluginsany[][]在默认道格龙 Remark 插件之前传递给 MDX 的自定义 Remark 插件。
beforeDefaultRehypePluginsany[][]在默认道格龙 Rehype 插件之前传递给 MDX 的自定义 Rehype 插件。
showLastUpdateAuthorbooleanfalse仅适用于 Markdown 页面。是否显示页面最后更新作者。
showLastUpdateTimebooleanfalse仅适用于 Markdown 页面。是否显示页面最后更新时间。此功能需要在构建时访问 git 历史，因此在浅克隆（CI 系统常见默认设置）下无法正常工作。使用 GitHub actions/checkout 时需设置 fetch-depth: 0。

类型定义​

EditUrlFn​

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

示例配置​

你可以通过预设选项或插件选项配置此插件。

提示

大多数道格龙用户通过预设选项配置此插件。

// 预设选项：pages
// 插件选项：@docusaurus/plugin-content-pages

const config = {
  path: 'src/pages',
  routeBasePath: '',
  include: ['**/*.{js,jsx,ts,tsx,md,mdx}'],
  exclude: [
    '**/_*.{js,jsx,ts,tsx,md,mdx}',
    '**/_*/**',
    '**/*.test.{js,jsx,ts,tsx}',
    '**/__tests__/**',
  ],
  mdxPageComponent: '@theme/MDXPage',
  remarkPlugins: [require('./my-remark-plugin')],
  rehypePlugins: [],
  beforeDefaultRemarkPlugins: [],
  beforeDefaultRehypePlugins: [],
};

Markdown front matter​

Markdown 页面可以使用如下 Markdown front matter 元数据字段，需用 --- 包裹。

可用字段：

名称类型默认值说明
titlestringMarkdown 标题页面标题。
descriptionstringMarkdown 内容第一行页面描述，将作为 <meta name="description" content="..."/> 和 <meta property="og:description" content="..."/> 出现在 <head>，供搜索引擎使用。
keywordsstring[]undefined关键词 meta 标签，将作为 <meta name="keywords" content="keyword1,keyword2,..."/> 出现在 <head>，供搜索引擎使用。
imagestringundefined封面或缩略图，将作为 <meta property="og:image" content="..."/> 出现在 <head>，用于增强社交媒体和消息平台的链接预览效果。
slugstring文件路径自定义页面 URL（/<routeBasePath>/<slug>）。支持多种模式：slug: my-page、slug: /my/page、slug: /。
wrapperClassNamestring添加到包裹元素的类名，便于定向特定页面内容。
hide_table_of_contentsbooleanfalse是否隐藏右侧目录。
draftbooleanfalse草稿页面仅在开发环境可见。
unlistedbooleanfalse未列出的页面在开发和生产环境均可访问，但在生产环境下会被"隐藏"，不被索引、不会出现在 sitemap，只能通过直链访问。

示例：

---
title: Markdown Page
description: Markdown 页面 SEO 描述
wrapperClassName: markdown-page
hide_table_of_contents: false
draft: true
slug: /markdown-page
---

Markdown 页面内容

i18n​

请先阅读i18n 介绍。

翻译文件位置​

  • 基础路径：website/i18n/[locale]/docusaurus-plugin-content-pages
  • 多实例路径：website/i18n/[locale]/docusaurus-plugin-content-pages-[pluginId]
  • JSON 文件：通过 docusaurus write-translations 提取
  • Markdown 文件：website/i18n/[locale]/docusaurus-plugin-content-pages

文件系统结构示例​

website/i18n/[locale]/docusaurus-plugin-content-pages
│
│ # website/src/pages 的翻译
├── first-markdown-page.md
└── second-markdown-page.md