使用 Docusaurus 生成静态网站

Docusaurus 是一个静态网页生成器，Facebook 的产品，基于 React

官网： https://docusaurus.io/

环境要求： Node.js version >= 14 ， Yarn version >= 1.5

生成一个模版站点，名为 website， 使用 classic 默认主题

npx create-docusaurus@latest website classic

文件结构

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.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

Docusaurus 有 3 种页面类型，分别是博客、文档、普通页面。默认配置下 blog 文件夹存放的是博客页面；docs 文件夹存放的是文档； src/pages 为普通页面；docusaurus.config.js 存放配置；static 存放静态资源，会生成在页面根目录下；sidebars.js 是默认侧边栏，被 docusaurus.config.js 引用。

使用 yarn start 命令可以预览网站

配置

docusaurus.config.js 文件可以配置导航栏、站点信息、插件，等等。

const config = {
  title: '健峰的网站',
  url: 'https://wjftu.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
...

代码高亮可以在 themeConfig 里面配置，非默认支持的语言通过 additionalLanguages 配置。

const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
...
prism: {
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
        additionalLanguages: ['java'],
      },

普通页面

支持 react 页面和 markdown 页面。

路由：

• /src/pages/index.js → [baseUrl]
• /src/pages/foo.js → [baseUrl]/foo
• /src/pages/foo/test.js → [baseUrl]/foo/test
• /src/pages/foo/index.js → [baseUrl]/foo/

文档

默认主题文档位于 docs 文件夹。可以不使用默认主题的文档配置，直接用文档插件定义多个文档。如果不使用默认主题的文档，需要修改配置为 docs: false,，然后手动用插件配置文档。

plugins: [

    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'algorithmPractice',
        path: 'note/algorithmPractice',
        routeBasePath: 'note/algorithmPractice',
        sidebarPath: require.resolve('./sidebars.js'),
      }, 
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'designPattern',
        path: 'note/designPattern',
        routeBasePath: 'note/designPattern',
        sidebarPath: require.resolve('./sidebars.js'),
      }, 
    ],

],

每个文档页面自带一个 id ，为文档路径下的相对路径。

文档的侧边栏有 doc, category, link 等类型，可以自己定义，但自己定义太麻烦，也可以自动生成。

module.exports = {
  mySidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        {
          type: 'doc',
          id: 'doc1',
        },
      ],
    },
    {
      type: 'category',
      label: 'Docusaurus',
      items: [
        {
          type: 'doc',
          id: 'doc2',
        },
        {
          type: 'doc',
          id: 'doc3',
        },
      ],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

默认的 siadebars.js 文件定义的是自动生成

tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],

在每个单个文档的 Front Matter 可以定义 title 和 sidebar_position，在 sidebar 中使用。如果不使用 Front Matter ，则以 1 级标题作为 title ，如果使用 Front Matter 而没有定义 title ，则以文件名作为 title 。

---
title: 设计模式
sidebar_position: 1
---

文档肯能包含多个子目录的文档，每个子目录按照同样的规则。子目录会作为一个折叠的 sidebar ，标题默认为文件夹名称。可以添加 category.json 文件定义此子目录在 sidebar 中的位置和标题。

{
  "position": 2,
  "label": "创建型模式",
  "collapsible": true,
  "collapsed": true
}

博客

默认主题已自带博客插件，默认 blog 文件夹为博客内容

文章的 Front Matter ，比较 intuitive 。

---
title: Welcome Docusaurus v2
description: This is my first post on Docusaurus 2.
slug: welcome-docusaurus-v2
tags: [hello, docusaurus-v2]
hide_table_of_contents: false
---
Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/).

<!--truncate-->

This is my first post on Docusaurus 2.

A whole bunch of exploration to follow.

docusaurus.config.js 中可以配置博客，intuitive

blog: {
  showReadingTime: true,
  // Please change this to your repo.
  editUrl:
    'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
  postsPerPage: 4,
},

博客的日期可以在 Front Matter 里面配置，也可以用文件名配置。文件名示例如下

2021-05-28-my-blog-post-title.md
2021-05-28-my-blog-post-title.mdx
2021-05-28-my-blog-post-title/index.md

使用 GitHub Actions 构建

创建用于部署的 key pair ，并添加到服务器

ssh-keygen -t ed25519 -C "my_key" -f /path/to/private_key
ssh-copy-id -i /path/to/private_key.pub user@remote

创建 .github/workflows/deploy.yml 文件，在 GitHub 仓库创建 SERVER_HOST SERVER_USER SERVER_SSH_KEY 这几个 secret

on:
  push:
    branches:
      - deploy 

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '18'

      - name: Install dependencies
        run: |
          npm ci  

      - name: Build Docusaurus site
        run: |
          npm run build
      
      - name: Deploy to server via SCP
        uses: appleboy/scp-[email protected]
        with:
          host: ${{ secrets.SERVER_HOST }}  
          username: ${{ secrets.SERVER_USER }}  
          key: ${{ secrets.SERVER_SSH_KEY }}  
          port: 22  
          source: 'build/*'
          target: '/var/www/' 
          rm: true