- Objective:
- Breadcrumb:
# 概念阐释
Docusaurus是一个使用独特配置方法的文档站点生成器。它鼓励将站点信息整合到一个名为docusaurus.config.js的文件中，可在整个站点中访问。该配置文件包括站点元数据、部署配置、主题和插件设置以及自定义配置等多个字段。文件的内容可根据具体需求进行定制，并通过React上下文对站点的所有组件进行访问。此外，Docusaurus提供默认配置以简化新项目的设置过程。
- [[Configuration - themeConfig 主题]]
## 配置文件纵览
- 站点元数据
- 部署配置
- 主题、插件和预设配置
- 自定义配置
### site metadata 站点元数据
元数据包括：`title`, `url`, `baseUrl`, and `favicon`.
- `title`：网站的标题
- `url`
- 网站的主域名：https://notes.harryrou.wiki
- `baseurl`
- 设置你的网站在服务器上的子路径: 例如网站在服务器的docs文件夹内，那么 `baseUrl` 应该被设置为` '/docs/'`。
- 如果你的网站直接在主域名下运行（例如 `'https://mywebsite.com'` ），那么 `baseUrl` 应该设置为` '/'`。
- 在GitHub Pages上，如果你想把网站部署在仓库的根目录下，那么 `baseUrl` 应该被设置为 '/<仓库名>/'
- `favicon` 网站页面的logo
### 部署配置
当您使用部署命令部署站点时，会使用部署配置，例如`projectName`、`organizationName`和可选的`deploymentBranch`。建议查看[[部署文档]]以获取更多信息。
### 主题、插件和预设
- 在[[Configuration - themeConfig 主题]]、[[Docusaurus 插件]]和[[preset 预设]]字段中列出您网站所使用的主题、插件和预设。这些通常是npm包：
```js
//调用了主题和插件
module.exports = {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-classic'],
};
//Docusaurus支持缩写
module.exports = {
// ...
plugins: ['content-blog', 'content-pages'],
themes: ['classic'],
};
```
- **也可以加载本地仓库：**
```js
const path = require('path');
module.exports = {
// ...
themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};
```
- **要为[[Docusaurus 插件]]或主题指定选项，请在配置文件中用包含名称和选项对象的数组替换插件或主题的名称：**
```js
module.exports = {
// ...
plugins: [
[
'content-blog',
{
path: 'blog',
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
// ...
},
],
'content-pages',
],
};
```
这段代码是在配置 Docusaurus 的插件，Docusaurus 是一个创建和发布文档的开源框架。插件是 Docusaurus 的重要组成部分，它们可以用来扩展 Docusaurus 的核心功能。
这段代码中的配置做了以下事情：
1. `module.exports = {...}`：这是一个 **Node.js** 语法，用于将配置对象导出为一个模块，以便其他文件可以使用 `require` 或 `import` 语句来引入。
2. `plugins: [...]`：这是一个数组，列出了你要在 Docusaurus 网站中使用的插件。
3. `['content-blog', {...}]`：这是一个插件的数组元素，表示使用 'content-blog' 插件。这个插件使 Docusaurus 能够处理和渲染位于特定路径下的 Markdown 或 MDX 文件，并将其作为博客文章显示。这个插件的配置对象包含以下属性：
- `path: 'blog'`：这告诉 Docusaurus 从项目的 'blog' 目录中读取博客文章。
- `routeBasePath: 'blog'`：这表示博客文章在网站上的 URL 路径将以 '/blog' 为前缀。
- `include: ['*.md', '*.mdx']`：这表示插件将处理所有的 Markdown (`*.md`) 和 MDX (`*.mdx`) 文件。
4. `'content-pages'`：这是另一个插件，它告诉 Docusaurus 要处理和渲染页面内容。
这种配置方式提供了非常灵活的内容管理方式，你可以轻松地根据需要添加更多的插件和配置选项。
- **要为预设中捆绑的插件或主题指定选项，请通过预设字段`preset` 传递选项。 在此示例中，文档指的是@docusaurus**
```js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
},
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
```
这段代码是 Docusaurus 配置文件中的一部分，特别是关于预设（presets）的部分。预设是一组预定义的插件和主题，可以简化配置过程。在这个例子中，代码使用的预设是 '@docusaurus/preset-classic'，这是 Docusaurus 提供的一个包含一组基本功能的预设，包括文档、博客和页面。
这段代码做了以下配置：
1. `module.exports = {...}`: 这是一个 Node.js 的语法，表示它将导出一个对象，以便其他文件可以通过 `require` 或 `import` 语法导入这个配置对象。
2. `presets: [...]`: 这是预设数组，列出了你在 Docusaurus 网站中使用的预设。
3. `['@docusaurus/preset-classic', {...}]`: 这是一个预设数组元素，表示你正在使用 '@docusaurus/preset-classic' 预设。这个预设提供了基本的文档、博客和页面功能。预设的配置对象包含以下属性：
- `docs: {...}`: 这个配置对象定义了文档的行为。`sidebarPath: require.resolve('./sidebars.js')` 表示 Docusaurus 应该从 'sidebars.js' 文件中读取侧边栏配置。
- `theme: {...}`: 这个配置对象定义了主题的行为。`customCss: [require.resolve('./src/css/custom.css')]` 表示你想使用自定义的 CSS 文件来覆盖或增加到默认的 CSS 样式上。
这段代码使得你可以对 Docusaurus 进行更详细的配置，以适应你的项目的具体需求。
### 自定义配置
Docusaurus会保护docusaurus.config.js不受未知字段的影响。要添加自定义字段，请在customFields中定义它们。
```js
module.exports = {
// ...
customFields: {
image: '',
keywords: [],
},
// ...
};
```
### 从组件访问配置文件
您的配置对象将可用于站点的所有组件。您可以通过React上下文访问它们，名称为siteConfig。例如在网站首页`pages/index.js`中访问配置文件中的banner标题
```js
import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const Hello = () => {
const {siteConfig} = useDocusaurusContext();
const {title, tagline} = siteConfig;
return <div>{`${title} · ${tagline}`}</div>;
};
```
### 自定义 Babel Configuration
对于新的Docusaurus项目，我们会在项目根目录自动生成babel.config.js文件。
Babel 是一个 JavaScript 编译器，主要用于将 ES6+ 的代码转换为 ES5 代码，以此来增强代码的兼容性。Babel 配置通常放在一个叫做 `babel.config.js` 的文件中。
"Docusaurus" 是一个用于构建和发布文档网站的开源框架。当你创建一个新的 Docusaurus 项目时，它会自动在项目的根目录中生成 `babel.config.js` 文件。这个文件包含了一些默认的 Babel 配置，为你的 Docusaurus 项目提供了基本的 JavaScript 语法支持。
这个文件主要的作用是定义项目中如何使用 Babel 进行 JavaScript 代码的转换。如果你需要对 Babel 的默认设置进行修改，例如，如果你想添加新的 Babel 插件或预设，你可以直接修改这个 `babel.config.js` 文件。
总的来说，这句话的意思是，当你创建一个新的 Docusaurus 项目时，它会为你提供一个默认的 Babel 配置，以便你可以立即开始写你的代码，而不需要担心代码转换和兼容性的问题。
# 实例
[[Configuration - themeConfig 主题]]配置文件说明： ^233bfb
```js
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
// Replace with your project's social card
image: 'img/docusaurus-social-card.jpg',
navbar: { //导航栏
title: 'My Site',//导航最左侧，通常放公司名称
logo: {
alt: 'My Site Logo',//logo 图片提供替代文本，当图片无法显示或用户使用屏幕阅读器时，会显示或读出这段文本
src: 'img/logo.svg',//logo的图片
},
items: [//这是一个对象数组，定义了导航栏上的项目
{
type: 'docSidebar',//项目类型。在这里的 'docSidebar' 表示这个项目是一个链接到文档doc侧边栏的项目。跳转过去后是侧边栏
sidebarId: 'tutorialSidebar',//与 `type: 'docSidebar'` 配对使用，表示要链接到的侧边栏的 ID。修改链接的地方，这个id在sidebars.js文件中可以找到
position: 'left',//项目在导航栏上的位置，可以是 'left' 或 'right'。float属性
label: 'Tutorial123',//项目的标签，这是在导航栏上显示的文本。
},
{to: '/blog', label: 'Blog', position: 'left'},//用于指向网站内部的链接页面，不指向侧边栏。例如，`to: '/blog'` 创建了一个到 '/blog' 页面的链接。
{
href: 'https://github.com/facebook/docusaurus',//用于指向网站外部的链接
label: 'GitHub',//项目的标签，这是在导航栏上显示的文本。
position: 'right',//项目在导航栏上的位置，右侧
},
],
},
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Tutorial',
to: '/docs/intro',
},
],
},
{
title: 'Community',
items: [
{
label: 'Stack Overflow',
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
},
{
label: 'Discord',
href: 'https://discordapp.com/invite/docusaurus',
},
{
label: 'Twitter',
href: 'https://twitter.com/docusaurus',
},
],
},
{
title: 'More',
items: [
{
label: 'Blog',
to: '/blog',
},
{
label: 'GitHub',
href: 'https://github.com/facebook/docusaurus',
},
],
},
],
copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
},
prism: {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
},
}),
};
```
# 相关内容
## 官方网站的Doc和API导航栏
`config.js`
```
items: [
{
type: 'doc',//链接到单个文件
position: 'left',//导航栏位置
docId: 'introduction',//文件名
label: 'Docs',//导航栏命名
},
{
type: 'docSidebar',//链接到侧边栏
position: 'left',//导航栏位置
sidebarId: 'api',//文件夹名
label: 'API',//导航栏命名
},
```
# 参考资料
[Configuration](https://docusaurus.io/docs/configuration#theme-plugin-and-preset-configurations)：Docs - Getting Started
[Configuration.js的API文档](https://docusaurus.io/zh-CN/docs/api/docusaurus-config)：API - docusaurus.config.js 查阅config文件中的所有api