主题

像插件一样,主题(themes)旨在为你的 Docusaurus 网站添加功能。根据经验,主题主要关注点是客户端,而插件则更侧重于服务器端的功能。主题还被设计为可被其它主题覆盖。

使用主题

要使用主题,请在 docusaurus.config.js 配置文件中指定主题即可。也可以使用多个主题:

docusaurus.config.js
module.exports = {
// ...
themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

主题组件

在大多数情况下,主题用于提供一组 React 组件,例如导航栏、布局、页脚。

用户可以通过使用 @theme 形式的 webpack 别名来导入(import)这些组件并在代码中使用它们:

import Navbar from '@theme/Navbar';

@theme 别名可以引用多个目录,并分为以下优先级:

  1. 用户的 website/src/theme 目录,这是具有较高优先级的特殊目录。
  2. Docusaurus 主题包的 theme 目录。
  3. Docusaurus core 提供的后备组件(通常不需要)。

假设有以下结构:

website
├── node_modules
│ └── docusaurus-theme
│ └── theme
│ └── Navbar.js
└── src
└── theme
└── Navbar.js

每当导入 @theme/Navbar 时,website/src/theme/Navbar.js 被优先使用。此行为称为组件 swizzling。在 iOS 中,swizzling 方法能够更改现有 selector(方法)的实现方式。在网站开发的语境中,组件级的 swizzling 意味着提供了一个替代组件,该组件优先于主题所提供的组件。

主题提供了用于内容呈现的 UI 组件。 大多数内容处理相关的插件需要与主题配合才能真正有用。UI 是与数据架构分离的一层,因此可以轻松地将主题替换为其他设计(例如 Bootstrap)。

例如,Docusaurus 博客由博客插件和博客主题组成。

docusaurus.config.js
{
theme: ['theme-blog'],
plugins: ['plugin-content-blog'],
}

如果您想使用 Bootstrap 样式,可以将主题替换为 theme-blog-bootstrap(一个虚构的不存在主题):

docusaurus.config.js
{
theme: ['theme-blog-bootstrap'],
plugins: ['plugin-content-blog'],
}

内容处理插件保持不变,唯一需要更改的就是主题。

Swizzling 主题组件

caution

在我们至少达到 Beta 阶段前,我们不鼓励组件的 swizzling。组件 API 一直在快速变化,并且可能会不断变化,直到我们达到 Beta 阶段。如果可能的话,请尽量使用默认主题,以免将来自己遭受潜在的痛苦。

Docusaurus 的主题组件被设计为可更换的。为了让你替换主题组件能够更容易,我们为你创建了 swizzle 命令。

要替换主题的组件,请在你的文档站点中运行以下命令:

docusaurus swizzle <theme name> [component name]

例如,要为你的站点替换 @docusaurus/theme-classic 主题中的 <Footer /> 组件,请运行:

npm run swizzle @docusaurus/theme-classic Footer

这会将当前主题所使用的 <Footer /> 组件复制到站点根目录下的 src/theme/Footer目录中,Docusaurus 将在该目录中查找被替换的组件。然后,Docusaurus 将使用被替换的组件代替主题中的原始组件。

尽管我们强烈建议不要替换(swizzling)所有组件,但是如果您希望这样做,请运行:

npm run swizzle @docusaurus/theme-classic

注意:你需要重新启动 webpack 开发服务器,以使 Docusaurus 知道新组件。

Docusaurus 官方主题

@docusaurus/theme-classic

这是 Docusaurus 的经典主题。你可以参考 classic 主题配置 获取有关配置的更多详细信息。

npm install --save @docusaurus/theme-classic
tip

如果您已经安装了 @docusaurus/preset-classic,则不需要在将其安装为依赖项了。

@docusaurus/theme-search-algolia

这个主题提供了一个 @theme/SearchBar 组件,可以轻松地与 Algolia DocSearch 集成。与 @docusaurus/theme-classic 一起使用,它集成了非常简单的搜索功能。你可以阅读 搜索 章节的文档。

npm install --save @docusaurus/theme-search-algolia

这个主题还添加了具有 OpenSearch 支持的 /search 路径中可用的搜索页面。

tip

如果您已经安装了 @docusaurus/preset-classic,则不需要将其安装为依赖项。

@docusaurus/theme-live-codeblock

这个主题提供了一个 @theme/CodeBlock 组件,该组件基于 react-live 构建。您可以阅读更多有关 交互式代码编辑器 相关的文档。

npm install --save @docusaurus/theme-live-codeblock

主题设计

尽管主题与插件共享完全相同的生命周期方法,但是它们的实现看起来与基于主题设计目标的插件的实现有很大不同。

主题旨在完成 Docusaurus 网站的构建,并为你的网站提供所需的组件、插件和主题本身。因此,一个典型的主题实现看起来像是一个 src/index.js 文件,并将其连接到生命周期方法中。他们很可能不会使用插件所使用的 loadContent。主题通常伴随着一个 src/theme目录,其中包含所有组件。

总结一下:

  • 主题与插件共享相同的生命周期方法
  • 在所有现有插件之后才运行主题
  • 存在通过扩展 webpack 配置来添加组件别名的主题

编写自定义的 Docusaurus 主题

Docusaurus 主题通常包括一个 index.js 文件,你可以在此文件中调用生命周期方法,以及一个存放组件的 theme/ 目录。一个典型的 Docusaurus 主题的 theme 目录如下所示:

website
├── package.json
└── src
├── index.js
└── theme
├── MyThemeComponent
└── AnotherThemeComponent.js

有两个生命周期方法对于实现主题至关重要:

Last updated on by wangsai