创建和自定义一个带博客功能的Docusaurus网站

docusaurus

对于轻量级的网站、应用程序和其他小型项目,越来越多的开发人员转向静态网站生成器,而不是WordPress或其他内容管理系统(CMS)。静态网站为创建快速、安全和易于维护的网站和应用程序提供了一种简单有效的方法。

Docusaurus就是这样一个静态网站生成器–它在开发社区中迅速得到了普及。

在这篇文章中,我们将深入探讨使用Docusaurs作为静态网站生成器的好处,以及为什么它在开发人员中越来越受欢迎。

    1. 什么是Docusaurus?
    2. 什么是Docusaurus?
    3. 自定义你的Docusaurus安装

什么是Docusaurus?

Docusaurus是一个流行的静态网站生成器,它使用React(顶级JavaScript库之一)作为页面创建的UI库。像其他此类生成器一样,它很容易设置,也很容易修改,而且–最重要的是–它为你提供了你的静态网站运行所需的一切。

然而,使Docusaurus与众不同的是,它帮助你创建和管理一个内容发挥关键作用的网站。它允许你快速和容易地建立一个完整的网站–完整的博客功能–从一开始就突出你的内容。

因为内容是Docusaurus的重点,它非常适合创建像维基这样的文档网站。它还利用了markdown,这对于协作和在git仓库中的存储都很理想。更重要的是,它有大量惊人的功能,如i18n、搜索和自定义主题,我们将在后面详细讨论。

以下是使Docusaurus成为一个可靠选择的几个突出特点:

  • 使用React构建
  • 支持MDX v1
  • 支持通过Markdown嵌入React组件
  • 文档版本管理
  • 与Git、Crowdin和其他翻译管理器兼容,用于文档翻译和批量或单独部署

谁在使用Docusaurus?

Docusaurus是由Facebook创建的,所以它目前被整个网络的许多大品牌和公司使用并不奇怪。

以下是目前使用Docusaurus的几个最大的品牌(随着Docusaurus的知名度不断提高,很快会有更多的品牌使用):

而且每天都有更多的人加入他们的行列。

如何安装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官方文档的一部分,展示了他们的自定义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]
---

…当然,还有内容本身。它还有一个非常有用的 <!--truncate--> 标签,这有助于限制所有帖子列表上显示的帖子摘要。

创建一个author.yml文件,以获得信用,也是一个好主意。该文件看起来像这样:

palmiak:
name: Maciek Palmowski
title: DevRel
url: https://github.com/palmiak
image_url: https://github.com/palmiak.png

由于这个文件,你将在一个地方拥有所有作者的数据,便于参考。

小结

凭借其令人惊讶的强大功能、友好的设计、直观的导航和对内容的关注,不难看出为什么Docusaurus被认为是任何希望轻松部署和维护一个精简的、组织良好的静态文档网站和/或博客的开发者的一个优秀工具。

一旦你用你的访问者会重视的内容填满你的网站,你就会开始注意到额外的内置功能,这些功能会很方便。例如,Docusaurus的搜索引擎优化功能是完美的,可以帮助你通过更广泛的受众获得更好的可见性,同时你还可以通过其他技术来提高SEO排名

你用Docusaurus建立过什么吗?请在下面的评论部分与我们分享你的项目和经验。

评论留言