对于轻量级的网站、应用程序和其他小型项目，越来越多的开发人员转向静态网站生成器，而不是WordPress或其他内容管理系统（CMS）。静态网站为创建快速、安全和易于维护的网站和应用程序提供了一种简单有效的方法。
Docusaurus就是这样一个静态网站生成器–它在开发社区中迅速得到了普及。
在这篇文章中，我们将深入探讨使用Docusaurs作为静态网站生成器的好处，以及为什么它在开发人员中越来越受欢迎。
-
- 什么是Docusaurus？
- 什么是Docusaurus？
- 自定义你的Docusaurus安装
什么是Docusaurus？
Docusaurus是一个流行的静态网站生成器，它使用React（顶级JavaScript库之一）作为页面创建的UI库。像其他此类生成器一样，它很容易设置，也很容易修改，而且–最重要的是–它为你提供了你的静态网站运行所需的一切。
然而，使Docusaurus与众不同的是，它帮助你创建和管理一个内容发挥关键作用的网站。它允许你快速和容易地建立一个完整的网站–完整的博客功能–从一开始就突出你的内容。
因为内容是Docusaurus的重点，它非常适合创建像维基这样的文档网站。它还利用了markdown，这对于协作和在git仓库中的存储都很理想。更重要的是，它有大量惊人的功能，如i18n、搜索和自定义主题，我们将在后面详细讨论。
以下是使Docusaurus成为一个可靠选择的几个突出特点：
- 使用React构建
- 支持MDX v1
- 支持通过Markdown嵌入React组件
- 文档版本管理
- 与Git、Crowdin和其他翻译管理器兼容，用于文档翻译和批量或单独部署
谁在使用Docusaurus？
Docusaurus是由Facebook创建的，所以它目前被整个网络的许多大品牌和公司使用并不奇怪。
以下是目前使用Docusaurus的几个最大的品牌（随着Docusaurus的知名度不断提高，很快会有更多的品牌使用）：
- Algolia DocSearch
- Jest
- React Native
- Supabase
而且每天都有更多的人加入他们的行列。
如何安装Docusaurus
Docusaurus的安装非常简单，只需要几分钟时间。在本教程中，我们将建立一个带有博客的文档网站，我们将定制网站的外观。
而这里是最酷的部分。我们将花不到一个小时的时间来启动一切。
要求
Docusarus需要Node.js 16.14或更新版本。它是一个平面文件的SSG，这意味着你不需要一个额外的数据库。
如果你还没有Node.js 16.14以上的版本，你将需要先安装Node.js或升级你目前的版本。然后你就可以进入下面的Docusaurus安装过程。
我们还将使用这个GitHub仓库中的Docusaurus样本网站。你可以使用它，也可以在本教程中使用Docusaurus的干净安装。
安装过程
要开始Docusaurus的安装过程，你首先需要运行以下命令：
npx create-docusaurus@latest classic
这将为你的项目创建一个文件夹，并在其中搭建起经典主题。经典主题已经包含了一些预先配置的功能，如博客、自定义页面和CSS框架。
安装后，你需要运行以下命令来启动本地服务器：
npm start
如果你想建立一个可供部署的优化版本，你应该运行这个：
npm run build
架构
一旦你安装了你的Docusaurus实例，你就可以打开你的项目目录，仔细看看你新网站的 “骨架”。
这里是文件结构的样子：
my-website ├── blog │ ├── 2019-05-28-hola.md │ └── 2020-05-30-welcome.md ├── docs │ ├── doc1.md │ └── mdx.md ├── src │ ├── css │ │ └── custom.css │ └── pages │ ├── styles.module.css │ └── index.js ├── static │ └── img ├── docusaurus.config.js ├── package.json ├── README.md ├── sidebars.js └── yarn.lock
关于这些文件和文件夹中的几个，有几个细节需要注意：
/blog: 包含所有与你的博客有关的文件。/docs: 包含所有与你的文档相关的文件。你可以在sidebar.js文件中自定义它们的顺序。/src: 包含所有非文档文件，如页面或自定义组件。/src/pages: 所有的JSX/TSX/MDX文件将被转化为页面。/static: 将被复制到最终构建文件夹的静态文件。docusaurus.config.js: Docusaurus配置文件。packaged.json: 每个Docusaurus网站都是一个React应用，所以在这里你会发现它对React的所有依赖和脚本。sidebar.js: 在这里你可以指定侧边栏中的文件顺序。
自定义你的Docusaurus安装
从其文件结构的简单性可以看出，Docusaurus很容易使用和导航。同样，定制你的Docusaurus网站也是一件轻而易举的事。你可以使用你最喜欢的文本编辑器或IDE打开和编辑这些文件。
让我们来看看你开箱就有的一些定制选项。
Homepage
你可能迫不及待要做的第一件事是定制默认主页，以展示你自己的项目。幸运的是，对Docusaurus的主页做任何改变都不复杂。
要改变主页，打开 src/pages/index.js 文件，在那里进行调整。这是一个典型的React页面，所以你可以通过改变内容或创建自定义React组件来改变或重建它。
配置文件
接下来，我们将深入到关键的 docusaurus.config.js 文件，为我们的实例改变一些重要的细节。
名称和描述
在该配置文件中，你会发现：
const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
url: 'https://your-docusaurus-site.com',
baseUrl: '/',
只要改变这些细节以适应你的网站的需要，然后保存文件。
导航栏
要编辑你的导航栏，找到 navbar 项目。
在我们的例子中，我们要添加一个指向闪电博的链接，将 “Tutorial” 项重命名为 “Starter documentation”，并添加闪电博的标志。
下面是我们要做的事情：
navbar: {
title: 'Wbolt starters',
logo: {
alt: 'Wbolt Logo',
src: 'img/wbolt-logo-alpha-purple.png',
},
items: [
{
label: 'Wbolt starters',
to: '/docs/intro',
},
{to: '/blog', label: 'Blog', position: 'left'},
{
href: 'https://github.com/wbolt',
label: 'GitHub',
position: 'right',
},
],
},
页脚
Docusaurus中的页脚定制由两部分组成：页脚内容本身，以及页脚链接。
（1）页脚内容
主要的页脚内容（不包括链接列表）可以放在你的themeConfig.footer文件中。这是添加标志和版权声明的理想位置。
下面是我们如何修改我们的页脚配置：
module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Wbolt Logo',
src: 'img/wbolt-logo.png',
href: 'https://www.wbolt.com',
width: 160,
height: 51,
},
copyright: `Copyright © ${new Date().getFullYear()} Wbolt. Built with Docusaurus.`,
},
},
};
（2）页脚链接
改变页脚链接与改变顶部导航栏类似。在docusaurus.config.js中找到 footer 部分，然后编辑，直到它适合你的需要。
下面是我们把 footer 部分改成的样子：
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Wbolt starters',
to: '/docs/intro',
},
],
},
{
title: 'Talk with us',
items: [
{
label: 'Discord',
href: 'https://discord.gg/vjRPMhFaBA',
},
{
label: 'Support',
href: 'https://www.wbolt.com/wbolt-support/',
},
{
label: 'Twitter',
href: 'https://twitter.com/wbolt',
},
],
},
{
title: '更多',
items: [
{
label: 'WordPress主题',
href: 'https://www.wbolt.com/themes',
},
{
label: 'WordPress插件',
href: 'https://www.wbolt.com/plugins',
},
{
label: 'WordPress学院',
href: 'https://www.wbolt.com/learn',
},
{
label: '站长工具',
href: 'https://www.wbolt.com/tools',
},
],
},
],
};
颜色和CSS
Docusaurus的经典预设使用Infima CSS框架。考虑到这一点，Docusaurus的创造者做了一个非常有用的网络工具来帮助你改变颜色和其他CSS元素和声明。
一旦你在页面上输入了你的偏好，这个工具就会在几秒钟内生成一个custom.css文件–完整的补充色调的可爱套件。然后，你可以将这个新的CSS文件复制到你的项目的/src/css目录中，以供参考。
Docusaurus官方文档的一部分，展示了他们的自定义CSS工具，其中有一些字段可以为Docusaurus设计中的每个单独元素输入十六进制代码调整。
文档
你新网站上的所有文档都存储在/docs文件夹中。当然，你可以在docusaurus.config.js中改变这个文件夹的名称。
只要在你的文本或HTML编辑器中创建markdown文件，并把它们放到那个文件夹中。每个文件应该看起来像这样：
--- id: the-id title: Title --- # Rest of the document
基于这个ID，Docusaurus为该子文件夹中的文章建立了URLs：yourdomain.com/docs/{id}。
如果想把我们的文档分成不同的、有逻辑的部分，我们也可以创建子文件夹。然而，我们需要做一些额外的工作，使这些子目录以我们期望的方式运作。
假设我们创建了一个名为 “Starters” 的新文档文件夹。如果我们刷新主页并点击自动添加到侧边栏的新的 “Starters”链接，我们会得到一个错误–因为在我们的新文件夹中还没有索引页。
解决这个问题的最简单方法是创建一个 _category_.json文件，它将生成存储在这个文件夹中的所有页面的索引。你只需要添加以下代码：
{
"label": "Starters",
"position": 2,
"link": {
"type": "generated-index",
"description": "All Wbolt Starters"
},
};
正如你所看到的，侧边栏会重新生成，以符合你的文件结构。这是因为sidebar.js文件包含这个 tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],。
如果你喜欢自己处理这个问题，你可以直接把它改为这样的内容：
tutorialSidebar: [
'intro',
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],
Blog
Docusaurus包括一个灵活的博客模块。在你的主网站旁边有一个博客，对于通知你的用户群在你的项目中发生的变化是非常有用的，或者作为一种变化日志的形式保持项目的运行记录。
每篇文章包括一个前言部分，像这样：
--- slug: docusaurus-starter title: Docusaurus Starter authors: palmiak tags: [starters, docusaurus] ---
…当然，还有内容本身。它还有一个非常有用的 标签，这有助于限制所有帖子列表上显示的帖子摘要。
创建一个author.yml文件，以获得信用，也是一个好主意。该文件看起来像这样：
palmiak: name: Maciek Palmowski title: DevRel url: https://github.com/palmiak image_url: https://github.com/palmiak.png
由于这个文件，你将在一个地方拥有所有作者的数据，便于参考。
小结
凭借其令人惊讶的强大功能、友好的设计、直观的导航和对内容的关注，不难看出为什么Docusaurus被认为是任何希望轻松部署和维护一个精简的、组织良好的静态文档网站和/或博客的开发者的一个优秀工具。
一旦你用你的访问者会重视的内容填满你的网站，你就会开始注意到额外的内置功能，这些功能会很方便。例如，Docusaurus的搜索引擎优化功能是完美的，可以帮助你通过更广泛的受众获得更好的可见性，同时你还可以通过其他技术来提高SEO排名。
你用Docusaurus建立过什么吗？请在下面的评论部分与我们分享你的项目和经验。
原文地址：https://www.wbolt.com/docusaurus.html
