Docusaurus 简单教程

Docusaurus 简介

Docusaurus 是 Facebook 开源的一款静态网站建立工具，Docusaurus 1 是纯粹的文档站点生成器，而 Docusaurus 2 则是保留了 1 易于上手、文档版本化的优势，可用于快速建立常见的内容驱动型的网站，像文档、博客、产品落地页、营销页等。

尽管 Docusaurus 主要关注帮助开发者正确地构建文档网站，但由于它是 React 应用，因此能够构建任何类型的网站。

静态网站生成工具中除了 Docusaurus 外还有 Gatsby、GitBook、Jekyll、VuePress 等，Taro 文档使用 Docusaurus 1 搭建，除了它更关注文档生成外，搜索使用了 docsearch ，整个站点均可以搜索，搜索体验很是好，Taro 3 咱们则升级到了 Docusaurus 2，若是你选择了 Docusaurus 而又暂时不须要多语言版本的文档，2 是个不错的选择，本文的例子也是基于 2 来和你们分享。

安装 Docusaurus

Docusaurus 有三个模板：经典模板 classic，仅适用 Facebook 的模板 facebook ，以及实验性功能的 bootstrap 模板。

咱们建立一个使用经典模板名称为 guide 站点，则可使用 npx 命令安装以下：

npx @docusaurus/init@latest init guide classic
复制代码

它会给你建立一个经典模板的目录结构，同时安装好依赖。安装完成后，目录结构以下：

➜  guide 
.
├── README.md
├── babel.config.js
├── blog                             // 博客文章目录
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2019-05-30-welcome.md
├── docs                             // 文档目录
│   ├── doc1.md
│   ├── doc1.md
│   ├── doc3.md
│   └── mdx.md                       // 支持 mdx 哦
├── docusaurus.config.js             // 配置文件目录
├── node_modules
├── package.json
├── sidebars.js      // 文档侧边栏配置文件
├── src              // 页面或自定义的 React 组件目录
│   ├── css
│   └── pages
├── static                           // 静态文件目录
└── yarn.lock
复制代码

文档的目录还比较清晰，功能给你们标注了，若是要对文档主题进行修改，主题文件夹 theme 放在 src 里，它会优先使用 theme 里的文件。

安装完成后，可使用 yarn start 运行，获得一个可预览的站点，若是浏览器没有自动打开，须要手动打开，输入命令行提示的地址，正常是 http://localhost:3000/, 若是端口被占用了，它会提示

? Something is already running on port 3000. Probably:
  ...
Would you like to run the app on another port instead? Yes
Docusaurus website is running at: http://localhost:3001/
复制代码

此时你就能够按提示给的地址访问啦。启动起来后预览以下图：

配置

基础配置

前面介绍目录时提到 docusaurus.config.js 能够配置站点信息，如今就来配置站点的相关信息，由于咱们 yarn star 启动了预览，因此在这个配置文件里的修改均可以实时看到。

module.exports = {
  title: 'Taro 文档', // 站点名称
  tagline: '开放式跨端跨框架解决方案，支持使用 React/Vue/Nerv 等框架来开发微信/京东/百度/支付宝/字节跳动/ QQ 小程序/H5 等应用。',  // slogan，标语
  url: 'https://docs.taro.zone',   // 站点的地址
  baseUrl: '/',   // 前置路径
  onBrokenLinks: 'throw',        // 编译遇到死链怎么处理
  favicon: 'img/favicon.ico',    // 网站的图标
  organizationName: 'nervjs', // GitHub 上的组织名或者用户名
  projectName: 'docusaurus', // GitHub 上仓库的名称
  themeConfig: {
    navbar: {
      title: 'Taro', // 导航上站点名称
      logo: {
        alt: 'Taro logo', // 站点 logo 文字替换
        src: 'img/logo.svg',  // 站点 logo 连接
      },
      items: [
        {
          to: 'docs/',                // 点击后跳转的连接，站内跳转用 to ,站外用 href
          activeBasePath: 'docs',     // 根据它显示当前高亮
          label: '文档',               // 显示的名称
          position: 'left',           // 显示在导航的 左边 仍是 右边
        },
        {to: 'blog', label: '博客', position: 'left'},
        {
          href: 'https://github.com/facebook/docusaurus',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
        // 这里自行修改
    }
    },
  },
  presets:[], // 鉴于本文篇幅，这里略过
};
复制代码

由配置文件可知搭建一个站点仅需几项配置，若是你想要开启更多的功能则须要添加一下配置项。

文档页面向下滚动时收起顶部导航

navbar: {
    hideOnScroll: true,
    ...
}
复制代码

让边栏可收起展开（须要在 2.0.0-alpha.67 之后）

themeConfig: {
    hideableSidebar: true,
    ...
}
复制代码

开启文档多版本

开启文档多版本，若是想建立新一个版本例如 1.1.0 的文档，只需

npm run docusaurus docs:version 1.1.0
复制代码

在目录下生成 versioned_docs/version-1.1.0/ 存放 1.1.0 的文档文件，生成 versioned_sidebars/version-1.1.0-sidebars.json 存放 1.1.0 文档的侧边栏。

你能够在顶部导航 navbar 上添加多版本切换的下拉菜单

navbar: {
    ... // 省略
    items: [
        {
          type: 'docsVersionDropdown',
          position: 'left',
          dropdownActiveClassDisabled: true
        },
        ... // 省略
    ]
    ... // 省略
}
复制代码

添加后的效果

点击 1.1.0，会切到对应的版本，路径为 http://localhost:3000/docs/，而 Next 则为 http://localhost:3000/docs/next/，由于当前版本就是 1.1.0，下一个版本就是 Next。

若是规划文档多版本，你须要考虑的东西以下：

• 文档数量有多少，若是像 Taro 的文档几百个，按小版本升级会生成不少的文件
• 访问人数众多的项目，删除旧版本会致使访问 404
• 若是你要改旧某个版本的文档，就只能修改 versioned_docs 下对应的版本目录里的文件

多站点

文档可能会有两个站点，一个 GitHub Page 站点和一个本身域名的站点，为了 SEO 设置不一样的 url，咱们须要两步来实现这个需求。

一、给 package.json 里的 script 添加新的命令，添加编译参数

"build": "docusaurus build",
"build:zone": "NODE_OPTIONS=--max-old-space-size=5120 BASE=zone docusaurus build",
复制代码

二、在 docusaurus.config.js 里经过环境变量来判断，填入咱们须要的地址

url:  process.env.BASE === 'zone' ? 'https://docs.taro.zone' : 'https://nervjs.github.io',   //  站点的地址
复制代码

撰写文档

上文可知，文档存放在根目录下的 docs 文件夹里，docusaurus 支持 Markdown 格式和 MDX 格式。

文档开头设置的 id 和 title，id是选填，它是文档的惟一标识，若是省缺的话，文档默认 id ,若是文档的路径是 doc.md 他的 id 就是 doc,若是是apis/doc1.md, 那么他的 id 就是 apis/doc1。

---
id: doc
title: 最佳实践 ---
复制代码

设置侧边栏

根目录下 sidebars.js 能够设置侧边栏，整体而已比较简单，举个例子，如文档（docs)下面有“关于Taro”，“快速开始”，“基础教程”，“进阶指南”，而进阶指南下又有目录，则须要标记type为category，在 items 例如：

module.exports = {
  docs: {
    关于Taro: ['README', 'team', 'CONTRIBUTING'],
    快速开始: ['GETTING-STARTED', 'composition'],
    基础教程: [
        react,
        vue,
        vue3
    ],
    进阶指南: [
        'hooks',
        'hybrid',
        {
            label: '反向转换',
            type: 'category',
            items: [
                'taroize',
                'convert-to-react',
                'taroize-troubleshooting'
            ]
        }
    ]
  }
}
复制代码

添加文档搜索

Docusaurus 支持使用 Algolia DocSearch 进行搜索, 版本 2 已经在增长新的特性以便支持别家的搜索，目前暂时就只能使用 Algolia 了。

进入 DocSearch 网站后，在页面中间 「JOIN THE PROGRAM」 进入申请页面，输入你网站的相关信息，勾选下面的按钮，提交便可。这里必定要按它的指引 checklist 检查你的网站，以便你能快速地申请经过。

最后

若是你使用了 Docusaurus ，别忘了给他们提供 showcase 哦，这么好用的文档工具无以回报，惟有投票（提供案例）支持了。你提交的案例会在官网的 showcase 里展现。