使用 Docusaurus 搭建个人网站项目

前言

参考的资料都有如下：

1. 实践指南-快速搭建文档网站
2. 超简单！使用 Docusaurus 搭建个人博客（一）
3. Github中的官方docusuarus

关于该项目，主要用来搭建个人网站，基于react的一个架构

通过docusaurus的官网以及了解vue，react的一些相关知识
对于前端的知识点可以不用懂那么多
但是如果要了解，也可看我之前的文章：

选型

1. 快速搭建

安装docusaurus，本身是一个脚手架，也就是node的一个全局库
拉取源码并且创建项目：
name就是网站名，template是模板，官方使用的是classic

npm @docusaurus/init@next init website classic

之后在website文件夹中进行

• npm install（初始化依赖包以及下载）
• npm run start（部署打包项目）

项目结构大致为：（多数为md文档）

• /blog/ ，记录博客
• /docs/ ， 记录文档。
• /src/ ， 源代码（内有css文件夹，写自定义css代码。内有pages放一些自定义的页面，都是react语法书写）
• /static/ ，存放静态资源文件

更加详细的结构为：

├─build（使用`npm run build `生成build包）
│  └─assets
│      ├─css
│      ├─images
│      └─js
├─docs（md格式文档）
│  ├─img
│  ├─客户端SDK文档
│  │  └─img
├─src
│  ├─components
│  │  └─HomepageFeatures
│  ├─css
│  └─pages（主页）
└─static（静态资源文件）
    ├─bootstrap-4.6.1-dist（bootstrap依赖包）
    │  ├─css
    │  └─js
    ├─icons（转换成svg格式的存放位置）
    └─img（静态图片）

2. 配置详解

2.1 docusaurus.config.js

关于这部分的更多参数可查看如下链接：
配置参数

const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: '主标题',
  tagline: '副标题，标语',  
  url: '官网域名',
  baseUrl: '/',  //前置路径
  onBrokenLinks: 'throw',   //  编译遇到死链怎么处理
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/xx_logo.ico',  //图标

  organizationName: 'facebook', // GitHub 上的组织名或者用户名
  projectName: xx, // GitHub 上仓库的名称

  // Even if you don't use internalization, you can use this field to set useful
  // metadata like html lang. For example, if your site is Chinese, you may want
  // to replace "en" with "zh-Hans".
  i18n: {
    defaultLocale: 'en',
    locales: ['en'],
  },

  presets: [
    [
      //此为docusaurus的默认界面风格
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
       //此为docs的侧边栏修饰
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
         
         //不想要可以去除
          editUrl:
          //此为网页左下的Edit this page 链接地址          
            '编辑的gitlab网址',
        },
		//修饰的css文件格式
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
        //导航条
      navbar: { 
        title: '左侧导航条显示',  
        logo: {
           alt: 'XX',  //导航条左侧多一个XX文字图标，
          src: 'img/XX.png', //附带左侧XX的图片
        },
        //导航条显示的产品文档，如果想增加额外的页面，可在此处
        items: [
          {
          	to: 'docs/',                // 点击后跳转的链接，站内跳转用 to ,站外用 href
          	activeBasePath: 'docs',     // 根据它显示当前高亮
            type: 'doc', //此处的格式可为doc或者为blog等，具体要参照docusaurus
            docId: 'intro', 
            position: 'left', 
            label: '文档', 
          },
        ],
      },
      //下侧栏目
      footer: {
          //格式为暗黑色
        style: 'dark',
        links: [
          {
            title: '帮助与文档',
            items: [
              {
                html: `
                    <a href="链接" target="_blank" rel="noreferrer noopener" class="footer__link-item">
                      链接介绍
                    </a>
                  `,
              },
            ],
          },

			//多出来一个下边框
          {
            title: '友情链接',
            items: [
              {
                html: `
                    <a href="域名链接" target="_blank" rel="noreferrer noopener" class="footer__link-item">
                    具体介绍
                    </a>
                  `,
              },
  
            ],
          },

        ],
        
        copyright: `网页最下面的下标`,
      },
      //网页右上角的 开灯以及关灯，这些都是开源的主题
      prism: {
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
      },
    }),
};

module.exports = config;

2.2 sidebar.js

配置文档页面侧边栏，只有文档页面才有，主要定义目录结构

//文档md中的侧边栏

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],

  // But you can create a sidebar manually
  

  tutorialSidebar: [
    {
      type: 'category',
      label: 'Tutorial',
      items: ['hello'],
    },
  ],
   
};

3. 自动部署

网站的自动部署可看我这篇比较详细的文章：
Gitlab CI/CD教程以及实战docker自动部署前端项目（全）