搭建本地的项目

  • docusaurus官网脚手架

  • 脚手架的设计真的很良心,像react脚手架一样安装启动,my-website就是项目的名字,classicdocusaurus的默认主题,官网中也有其他的可以下载插件配置主题

1
npx @docusaurus/init@latest init my-website classic
  • 安装完成之后根据提示
1
2
cd my-website
npm run start
  • 这个时候已经可以在localhost:3000,看到项目的主页了

修改配置

  • 配置文件是docusaurus.config.js,在里面修改一些主页的展示,这里的部分自己改一改都知道是什么意思了。我在这个文件中写了注释可以参考一下。

  • 侧边栏的配置文件sidebars.js,可以参考,也可以看官方文档。

  • 修改好自己的配置之后,就可以尝试部署了。

站点信息

站点信息的部分:

1
2
3
4
5
6
7
8
9
module.exports = {
title: 'My Site',
tagline: 'The tagline of my site',
url: 'https://your-docusaurus-test-site.com',
baseUrl: '/',
favicon: 'img/favicon.ico',
organizationName: 'facebook',
projectName: 'docusaurus',
};

下面是配置项说明:

  • title:站点标题,显示在浏览器标签页。
  • tagline:网站简介,显示在 meta 标签,可以给搜索结果提供摘要。
  • url:网站域名,用于生成 sitemap 文件。
  • baseUrl:资源文件的路劲。
  • favicon:站点图标的位置,站点图标会显示在标签页标题的前面。
  • organizationName:公司或组织名称。
  • projectName:项目名称。

页头配置

还是在 docusaurus.config.js 中的 module.exports 对象中配置:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
module.exports = {
themeConfig: {
navbar: {
title: 'My Site',
logo: {
alt: 'My Site Logo',
src: 'img/logo.svg',
},
links: [
{
to: 'docs/install/',
activeBasePath: 'docs/',
label: 'Docs',
position: 'left',
},
{ to: 'blog', label: 'Blog', position: 'left' },
{
href: 'https://github.com/facebook/docusaurus',
label: 'GitHub',
position: 'right',
},
],
},
},
};

navbar 中的内容就是页头配置,下面是一些配置项说明:

  • title:页头的标题。
  • logo.alt:页头 Logo 的描述,相当于 imgalt
  • logo.src:页头 Logo 的图片地址。

links中的内容是页头导航链接配置,下面是配置项说明:

  • to:路由链接的跳转地址,地址就是 docs 目录中的文件名,不需要加 md
  • activeBasePath:设置要处于选中状态的路劲,如果设置为 docs,只要访问 docs 目录中的页面,设置了 docs 的链接样式就是选中状态。
  • label:链接标签中的文字内容。
  • position:链接定位,left 居左,right 居右。
  • href:链接跳转地址,相当于 ahref,一般用于外部链接跳转。

href 设置的地址是不能无刷新跳转的,只有 to 才能无刷新跳转,但是 to 只能设置内容链接,而且需要使用相对路劲。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
module.exports = {
themeConfig: {
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Style Guide',
to: 'docs/',
},
{
label: 'Second Doc',
to: 'docs/install/',
},
],
},
],
copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
},
},
};

footer 和 上面的 navbar 一样都是写在 themeConfig 中。

links 中的数组是链接组,一个链接组中可以包含多个链接。链接的属性还是和页头的链接属性是一样的,只是没有 position

copyright 是页脚的版权信息。

首页配置

在项目目录中有一个 src 目录,src 目录中又有一个 pages 目录,pages 目录中的 index.js 就是首页文件。

index.js中有一个 features 数组,数组中的内容就是首页的项目描述。

features数组内容:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
const features = [
{
title: <>Easy to Use</>,
imageUrl: 'img/undraw_docusaurus_mountain.svg',
description: (
<>
Docusaurus was designed from the ground up to be easily installed and
used to get your website up and running quickly.
</>
),
},
{
title: <>Focus on What Matters</>,
imageUrl: 'img/undraw_docusaurus_tree.svg',
description: (
<>
Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
ahead and move your docs into the <code>docs</code> directory.
</>
),
},
{
title: <>Powered by React</>,
imageUrl: 'img/undraw_docusaurus_react.svg',
description: (
<>
Extend or customize your website layout by reusing React. Docusaurus can
be extended while reusing the same header and footer.
</>
),
},
];

要更改元素结构或属性可以在 index.js 中的 Feature 函数中更改。

撰写博客

博客的 Markdown 文件存放在项目目录下的 blog 目录中。

博客的 Markdown 文件开头也需要填写文章信息,如下:

1
2
3
4
5
6
7
8
9
---
id: vscode
title: VSCode 远程开发配置
author: Mr. Ma
author_title: 程序员
author_url: https://github.com/wgao19
author_image_url: https://www.misterma.com/img/avatar.jpg
tags: [VScode, 远程开发]
---

下面是文章信息说明:

  • id:文章 ID,用于自定义 URL 地址。
  • title:文章标题。
  • author:作者。
  • author_title:作者描述。
  • author_url:作者个人主页的 URL。
  • author_image_url:作者的头像图片 URL。
  • tags:文章标签,格式类似于数组。

以上就是 Docusaurus 的简单使用和配置,我这里只是写了一部分 Docusaurus 的配置,如果需要查看更详细的配置和说明可以访问 https://v2.docusaurus.io/。

推送项目

  1. 在 github 新建一个仓库
  2. 在项目的根目录下新建一个deploy.sh脚本文件,注意修改对应的用户名和仓库名:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run build

# 进入生成的文件夹
cd build

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io
# git push -f [email protected]:messiahhh/messiahhh.github.io.git master


# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f [email protected]:messiahhh/blog.git master:gh-pages
git push -f https://${access_token}@github.com/Dcose/dcose.github.io.git master:gh-pages

cd -
  1. 切换到项目的根目录,运行deploy.sh脚本文件。
  2. 注意:执行文件会启动 Git Bash,等待执行完成就好。