Docusaurus 是一个静态网页生成器，Facebook 的产品，基于 React
环境要求： 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