搭建本地的项目

  • docusaurus官网脚手架

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

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 的描述，相当于 img 的 alt。
  • logo.src：页头 Logo 的图片地址。

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

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

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 git@github.com:messiahhh/messiahhh.github.io.git master


# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com: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，等待执行完成就好。