学习使用 Docusaurus 的笔记

facebook 推出的开源的静态的内容管理系统，通过它可以快速的部署一个静态网站。

优点：

“开箱即用”：编程小白都是直接使用，使得我们可以专注于内容；
保姆级说明文档：官方说明文档条理清晰、简单易读；
支持我需要的插件（markdown、mdx、mermaid 等），易于引入；
托管到 GitHub 的静态页面上的流程简单。

完美的编程小白的笔记本

这里只列出需要的、关键笔记，更多的详情看官方文档说明。

网址： https://docusaurus.io/

1.基本使用：

安装 npx create-docusaurus@latest my-website classic
启动项目 npm start 或 yarn start
构建项目 npm run build 或 yarn build
启动本地服务器 npm run serve
发布到 GitHub pages npm deploy
配置项目： docusaurus.config.js 项目的配置文件
添加页面：
在 docusaurus 框架中，页面分成三种：1.page，2.blog，3.doc（建议主页用 page，其它用 md）。 md 文件打包后，好像是 html？
案例地址： https://github.com/lilichao/lilichao.github.io

2.插件支持

2.1.对 mermaid 的支持

更多详细看官方的说明（v2.4.1） https://docusaurus.io/zh-CN/docs/markdown-features/diagrams

安装插件： yarn add @docusaurus/theme-mermaid 或 npm install --save @docusaurus/theme-mermaid

配置 docusaurus.config.js：把 markdown.mermaid 设置为 true

 module.exports = {
     markdown: {
         mermaid: true,
     },
     themes: ['@docusaurus/theme-mermaid'],
 };

2.2.对 KaTex 的支持

https://docusaurus.io/zh-CN/docs/markdown-features/math-equations

安装插件 remark-math 和 rehype-katex :

    yarn add remark-math@3 rehype-katex@5 hast-util-is-element@1.1.0

或

    npm install --save remark-math@3 rehype-katex@5 hast-util-is-element@1.1.0

在 docusaurus.config.js 中引入插件：

    const math = require('remark-math');
    const katex = require('rehype-katex');

添加到 content plugin 或 preset options （通常是 @docusaurus/preset-classic 的 docs options）:

    remarkPlugins: [math],
    rehypePlugins: [katex],

在 stylesheets 引入 KaTex CSS :

 stylesheets: [
 {
     href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
     type: 'text/css',
     integrity:
     'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
     crossorigin: 'anonymous',
 },
 ],

总而言之，在 docusaurus.config.js 的改变大致如下：

const math = require('remark-math');    //引入
const katex = require('rehype-katex');  //引入

module.exports = {
  title: 'Docusaurus',
  tagline: 'Build optimized websites quickly, focus on your content',
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          path: 'docs',             //添加(不用添加也能生效)
          remarkPlugins: [math],    //添加
          rehypePlugins: [katex],   //添加
        },
      },
    ],
  ],

  // 引入 KaTex 样式。初始化项目时是没有这一块，得自己添加上来
  stylesheets: [
    {
      href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
      type: 'text/css',
      integrity:
        'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
      crossorigin: 'anonymous',
    },
  ],
};

2.3.支持 MDX 格式的 markdown 文件

MDX格式的文件是可以嵌入 js 的 markdown 文件。在某些需要交互功能场合下可能会方便。详细看官方文档，或初始化项目中的 blog/*.mdx。

Docusaurus 直接支持

注意事项：

1. `docusaurus.config.js` 中配置补充说明

i18n 中改为 zh-CN 。为了时区的对应，使得时间为中国时间显示形式；

2. docs 相关

默认情况下，只有二号、三号标题才进入目录；
默认情况下，以 _开头的文件会被忽视；
默认情况下，文档的标题作为左栏显示的标题，除非你想另外起名字，或添加 id、标签等等信息，在文档的头部添加如下信息：

  ---
  slug: first-blog-post
  id: doc-with-tags
  title: A doc with tags
  tags:     //也可以写成 yaml 数组的形式 tags: [Demo, Getting started]
    - Demo
    - Getting started
  ---

slug 表示文章的访问路径，例如： slug: first-blog-post 也就是说我们可以通过 first-blog-pos 来访问此文档。在 blog 中，也类似的处理。
文件夹结构：
- 一个篇文档有唯一的 id，默认的 id 是相对于 docs 文件夹的相对路径，比如： docs/welcome/index.md，则此文档的 id 为 welcome/index ；如果在文档的头部指定了文档的 id:part1，那么最终 id 为 welcome/part1。
- 文档 id 是用来对文档进行相关操作的“凭证”。

3. blog 相关

常用作者信息，可以定义在 authors.yml 中，成为全局的“信息”，然后在 blog 的 markdown 中直接使用，很方便。比如：

endi:
  name: Endilie Yacop Sucipto
  title: Maintainer of Docusaurus
  url: https://github.com/endiliey
  image_url: https://github.com/endiliey.png

yangshun:
  name: Yangshun Tay
  title: Front End Engineer @ Facebook
  url: https://github.com/yangshun
  image_url: https://github.com/yangshun.png

blog 中文件以如下格式来命名，系统会自动提取文件名的时间作为 blog 的时间等等信息，总而言之，这样按照这个格式来命名文件就对了。例如
- 2019-05-30-welcome.md
- 2019-05-30-welcome/index.md
- 2019-05-28-first-blog-post.md
如果 markdown 需要插入图片，最好弄个单独的文件夹，图片放文件夹内，比如上面示例的 welcome/index.md。

4.样式和 Layout

如果用的是 @docusaurus/preset-classic，则全局样式在 /src/css/custom.csshttps://docusaurus.io/docs/styling-layout 官网提供一个颜色计算方案。
在 page 中可以用 Layout 标签包裹起我们的代码，使得和默认主题样式有一定的一致性。

学习使用 Docusaurus 的笔记

1.基本使用：​

2.插件支持​

2.1.对 mermaid 的支持​

2.2.对 KaTex 的支持​

2.3.支持 MDX 格式的 markdown 文件​

注意事项：​

1. docusaurus.config.js 中配置补充说明​

2. docs 相关​

3. blog 相关​

4.样式和 Layout​