Docusaurus 簡單教程

Docusaurus 簡介

Docusaurus 是 Facebook 開源的一款靜態網站建立工具，Docusaurus 1 是純粹的文檔站點生成器，而 Docusaurus 2 則是保留了 1 易於上手、文檔版本化的優勢，可用於快速建立常見的內容驅動型的網站，像文檔、博客、產品落地頁、營銷頁等。css

儘管 Docusaurus 主要關注幫助開發者正確地構建文檔網站，但由於它是 React 應用，因此能夠構建任何類型的網站。html

靜態網站生成工具中除了 Docusaurus 外還有 Gatsby、GitBook、Jekyll、VuePress 等，Taro 文檔使用 Docusaurus 1 搭建，除了它更關注文檔生成外，搜索使用了 docsearch ，整個站點均可以搜索，搜索體驗很是好，Taro 3 咱們則升級到了 Docusaurus 2，若是你選擇了 Docusaurus 而又暫時不須要多語言版本的文檔，2 是個不錯的選擇，本文的例子也是基於 2 來和你們分享。vue

安裝 Docusaurus

Docusaurus 有三個模板：經典模板 classic，僅適用 Facebook 的模板 facebook ，以及實驗性功能的 bootstrap 模板。node

咱們建立一個使用經典模板名稱爲 guide 站點，則可使用 npx 命令安裝以下：react

npx @docusaurus/init@latest init guide classic
複製代碼

它會給你建立一個經典模板的目錄結構，同時安裝好依賴。安裝完成後，目錄結構以下：git

➜  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 裏的文件。github

安裝完成後，可使用 yarn start 運行，獲得一個可預覽的站點，若是瀏覽器沒有自動打開，須要手動打開，輸入命令行提示的地址，正常是 http://localhost:3000/, 若是端口被佔用了，它會提示web

? 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/
複製代碼

此時你就能夠按提示給的地址訪問啦。啓動起來後預覽以下圖：npm

配置

基礎配置

前面介紹目錄時提到 docusaurus.config.js 能夠配置站點信息，如今就來配置站點的相關信息，由於咱們 yarn star 啓動了預覽，因此在這個配置文件裏的修改均可以實時看到。json

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 裏展現。