[邊寫邊學(xué)系列] — 超級(jí)好用的文檔站建站框架 Docusaurus

時(shí)間：2023-08-05 11:15:02 | 來源：網(wǎng)站運(yùn)營

時(shí)間：2023-08-05 11:15:02 來源：網(wǎng)站運(yùn)營

[邊寫邊學(xué)系列] — 超級(jí)好用的文檔站建站框架 Docusaurus：前言
要寫這篇文章，起因是一個(gè)小伙伴來求助我，說 React 社區(qū)感覺沒有類似于 VuePress 的文檔站工具或者框架。然后 VuePress 使用起來有感覺沒有那么順手，所以想讓我?guī)兔ν扑]一個(gè)。秉承著加了我的群，就是我的人的思想理念，我反手直接打字說出 —— 用 Docusaurus，非常匹配你的要求。哈哈哈，扯犢子了，寫這篇文章的時(shí)候我還不知道這個(gè)單詞到底是啥意思呢，怎么可能給小伙伴推薦，實(shí)際上找尋過程是這樣的：
第一步，百度 / Google



差不多就是這個(gè)樣子，進(jìn)去搜索一圈，看了幾個(gè)推薦，感覺都不是我想要的框架（不對(duì)，感覺都不是我小伙伴想要的框架）。
第二步，去 React 官方首頁
既然在社區(qū)找不到合適的，當(dāng)然，很有可能是因?yàn)槲覀儧]搜對(duì)關(guān)鍵詞，但是我確實(shí)不知道該如何描述，所以老樣子，我們?nèi)ス倬W(wǎng)推薦看看，這里我其實(shí)也推薦大家，如果遇到問題，找不到思路追本溯源一下，最好的指引其實(shí)就在官方網(wǎng)站的文檔里藏著。
去官方推薦看了一圈，結(jié)果如下：



OK，看到了 CRA 、Next.js 和 Gatsby，說實(shí)話，靜態(tài)內(nèi)容站其實(shí) Next.js 和 Gatsby 這倆我都用過，都可以勝任，并且其實(shí)我之前也寫過類似的文章，但是出于理解小伙伴的真實(shí)想法，其實(shí)他只是想要一個(gè)開箱即用的文檔內(nèi)容站，這倆不是那么的匹配，所以繼續(xù)尋找。
第三步，去 Facebook 倉庫
官方網(wǎng)站居然都沒有，看來只能祭出大殺招 —— 去官方 Git 倉庫去找找。為啥子呢？一般來說，一個(gè)成熟的前端框架，為了更健壯的發(fā)展都會(huì)有自身的社區(qū)擴(kuò)展，比如 React 自身的 CRA，比如 Vue 自身的 Vue-Cli。誰能比自己團(tuán)隊(duì)更了解框架本身呢？因此大概率他們會(huì)自己去做一個(gè)的，廢話不多說，去找找不就知道了。



進(jìn)入官方倉庫，按照關(guān)鍵字隨便搜了一下，映入眼簾的就是這串英文字符 —— Docusaurus，別看我還沒點(diǎn)進(jìn)去，但是我已經(jīng)知道，這個(gè)可愛的小家伙就是我今天要找尋的目標(biāo)。
在這里我想吐槽一下，這個(gè)框架知名度不高（或者我孤陋寡聞了）的大部分原因，總覺得是這個(gè)名字起的不夠接地氣，Doc 很容易明白是文檔的意思，但是后面的一大串，確實(shí)不知道是啥意思，如果有知道的大佬，可以留言給我解釋一下～

最后，完美的幫助小伙伴解決了問題，本周份 resolve 小伙伴 issue 任務(wù)達(dá)成～（本來希望的是每日一份，但是寫文章這件事確實(shí)比較費(fèi)時(shí)間，平時(shí)只有周末才有時(shí)間寫）
想入群交流的可以通過掘金主頁找到我的聯(lián)系方式，進(jìn)群交流～

上面的找尋流程引出了本篇文章，既然是給小伙伴推薦的框架，那么我自己忍不住也要來看看到底這個(gè) Docusaurus 到底怎么樣，不然砸了老臉豈不是很沒面子。說實(shí)話，React 社區(qū)的相關(guān)技術(shù)棧我用的還算是比較多，對(duì)于靜態(tài)站文檔類內(nèi)容站如果不是幫小伙伴找一個(gè)一鍵上手即用框架，我覺得自己可能會(huì)用 Next.js 或者 Gatsby 來動(dòng)手搭建一個(gè)。主要原因是因?yàn)榇罱ǖ倪^程是一個(gè)知識(shí)的積累過程，但是現(xiàn)在的話其實(shí)會(huì)覺得專業(yè)的事情交給專業(yè)的框架工具去做，開發(fā)者只需要專注做應(yīng)該做的事情效率更高。使用 Docusaurus 之前先來看看有哪些知名文檔站是用它來進(jìn)建站的。

• Jest

• React Native

• Create-React-App

• ...真的還有非常多 React 社區(qū)響當(dāng)當(dāng)?shù)拿?/li>

好了，確實(shí)是官方的親兒子，F(xiàn)acebook 很多知名的框架以及 React 社區(qū)很多知名框架文檔站都是用 Docusaurus 來搭建的，既然是這樣說明框架本身是經(jīng)過驗(yàn)證的，接下來我們就來自己動(dòng)手嘗試一下。
Hello Docusaurus - 初識(shí)
個(gè)人現(xiàn)在學(xué)習(xí)任何新框架的習(xí)慣，上來就是直接 Get Started 然后起一個(gè) Hello World 應(yīng)用簡(jiǎn)單明了的上手。所以本篇文章就跟著我的思路，一起來看看這個(gè)框架對(duì)于建文檔站來說到底有多方便。
初始化項(xiàng)目

npx @docusaurus/init@latest init [名稱] [模板]npx @docusaurus/init@latest init docusaurus-luffyzh-website classic初始化過后，啟動(dòng)項(xiàng)目，我們來看看效果：



簡(jiǎn)單看了一下，基本的內(nèi)容站架構(gòu)都自動(dòng)建好了，包括了首頁和內(nèi)置的兩個(gè)文檔頁：Tutorial 和 Blog。至于為什么是兩個(gè)功能 Tab，后面會(huì)介紹到，同時(shí)還自動(dòng)支持暗黑模式的轉(zhuǎn)換，真的算是很良心了。
對(duì)于文檔站，無非就是寫 MD 文件然后渲染到頁面上，這沒什么可說的，所以其實(shí)文檔站框架的核心其實(shí)是 config 配置文件，嘗試著改一下 docusaurus.config.js 這個(gè)核心配置文件，更改一些網(wǎng)站的基本信息。

module.exports = { title: '前端周同學(xué)/'s Blog', tagline: ' 公眾號(hào): 前端周同學(xué)', url: 'https://github.com', baseUrl: '/', onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'warn', favicon: 'img/favicon.ico', organizationName: 'luffyZh', // Usually your GitHub org/user name. projectName: 'docusaurus-luffyzh-website', // Usually your repo name. themeConfig: { navbar: { title: '前端周同學(xué)', logo: { alt: 'My Site Logo', src: 'img/logo.svg', }, items: [ { type: 'doc', docId: 'intro', position: 'left', label: '文檔', }, { position: 'left', to: '/blog', label: '博客', }, { href: 'https://github.com/luffyZh/docusaurus-luffyzh-website', label: 'GitHub', position: 'right', }, ], }, footer: { style: 'dark', links: [ { title: 'Docs', items: [ { label: '文檔', to: '/docs/intro', }, ], }, { title: 'Blog', items: [ { label: '博客', to: '/blog', }, ], }, { title: '更多', items: [ { label: '掘金', href: 'https://juejin.cn/user/96412752681079' }, { label: 'GitHub', href: 'https://github.com/luffzh/docusaurus-luffyzh-website', }, ], }, ], copyright: `Copyright ? ${new Date().getFullYear()} 前端周同學(xué)～`, }, prism: { theme: lightCodeTheme, darkTheme: darkCodeTheme, }, },};

可以看到，我就改了幾個(gè)簡(jiǎn)單的配置文案，內(nèi)容站已經(jīng)十分的有模有樣了，真的是非常簡(jiǎn)便，忍不住繼續(xù)向下探索～

目錄結(jié)構(gòu)

來看看整個(gè)工程的目錄結(jié)構(gòu)，邊看邊了解每個(gè)目錄每個(gè)文件對(duì)應(yīng)的功能。

docusaurus-luffyzh-website├── blog // 包含博客的 Markdown 文件。 若您不需要博客，您可刪除此目錄│ ├── 2019-05-28-hola.md│ ├── 2019-05-29-hello-world.md│ └── 2020-05-30-welcome.md├── docs // 包含文檔的 Markdown 文件。 您可在 sidebars.js 中自定義文檔的側(cè)邊欄順序。│ ├── doc1.md│ ├── doc2.md│ ├── doc3.md│ └── mdx.md├── src // 如頁面或自定義 React 組件一類的非文檔文件│ ├── css│ │ └── custom.css│ └── pages // 放在此處的所有文件都將被轉(zhuǎn)換成網(wǎng)站頁面，類似 Next.js。│ ├── styles.module.css│ └── index.js├── static // 靜態(tài)資源│ └── img├── docusaurus.config.js // 站點(diǎn)配置文件├── package.json├── README.md├── sidebars.js // 用于指定側(cè)邊欄中的文檔順序└── yarn.lock看了一圈下來發(fā)現(xiàn) Docusaurus 的配置以及功能真的是非常的簡(jiǎn)潔并且目的十分明確，就感覺它專門就是為了內(nèi)容站而生的，框架本身只為開發(fā)者開了兩個(gè)口子，一個(gè)是文檔（主要目的之一：文檔站，上面也提到了有那么多的文檔站使用它生成的。），另一個(gè)是博客。上面提到了，這倆功能是有區(qū)別的，那么具體有啥區(qū)別呢？

• /doc —— 文檔文件夾

這個(gè)文件夾專門用來生成文檔站核心的，它識(shí)別 .md 文件的同時(shí)，還對(duì)下面的子目錄進(jìn)行解析，生成目錄樹結(jié)構(gòu)的側(cè)邊欄，如下圖所示：













【文檔規(guī)則】： 文檔的 .md 可以直接進(jìn)行內(nèi)容的書寫，和普通的 Markdown 文檔一模一樣書寫就可以，唯一一點(diǎn)需要注意的就是，可以通過一個(gè)頭部，來進(jìn)行文件在側(cè)邊欄順序的展示：

---sidebar_position: 3 // 此篇文檔顯示在第三個(gè)順序---

• /blog —— 博客文件夾

這個(gè)文件夾是用來生成博客文章的，它識(shí)別的也是 .md 文件，但是區(qū)別就是它無法識(shí)別目錄，它生成的側(cè)邊欄順序是根據(jù)文檔名稱來進(jìn)行排序的～如下圖：













【文檔規(guī)則】： 博客的 md 文件文檔頭部，需要按照一定的規(guī)則去匹配識(shí)別，詳細(xì)如下：

---slug: first-post // 轉(zhuǎn)化成路由 -> /blog/first-posttitle: First Post // 轉(zhuǎn)化成文檔標(biāo)題author: luffyZh // 轉(zhuǎn)化成文章作者昵稱author_title: 周公子 @掘金 // 轉(zhuǎn)化成作者標(biāo)題author_url: https://github.com/luffyZh // 轉(zhuǎn)化成作者鏈接author_image_url: https://avatars.githubusercontent.com/u/17840558?s=60&v=4 // 轉(zhuǎn)化成頭像tags: [test] // 轉(zhuǎn)化成分類標(biāo)簽---這里直接寫標(biāo)題以外的內(nèi)容。對(duì)比
非常簡(jiǎn)單的上手了一下，用著說實(shí)話，感覺還不錯(cuò)，并且其實(shí)大部分開發(fā)者如果不關(guān)心建站類操作，看到這里就可以完全弄出來一個(gè)很成型的文檔以及博客站了。那么既然是一個(gè)靜態(tài)內(nèi)容站生成的工具，那么到底它有哪有優(yōu)點(diǎn)呢？比如大部分內(nèi)容站，文檔類的需求我們所見到的大部分應(yīng)該是 Gitbook、VuePress 甚至是語雀和飛書等。相信大家還是想知道，為什么選擇用 Docusaurus 而不是用其他的框架？總要有一個(gè)理由嘛，關(guān)于答案，我們依然可以從官網(wǎng)入手來找找看，讓它自己來告訴我們它自身并不是一個(gè) KPI 框架，而是真正能幫開發(fā)者解決文檔建站痛點(diǎn)問題的。

• Gatsby - 優(yōu)秀但是曲線陡峭

如果用過 Gatsby，相信大家應(yīng)該了解，Gatsby 是通過 Graphql 驅(qū)動(dòng)的，如果你單純的只做文檔類內(nèi)容站，那么用 Gatsby 有些大材小用了，當(dāng)然不否認(rèn) Gatsby 的優(yōu)秀。

• Next.js - 優(yōu)秀但是沒必要

殺雞焉用宰牛刀用來形容使用 Next.js 建文檔站再合適不過了，Next.js 作為 React 社區(qū)最為優(yōu)秀的混合框架，它能做的事情真的是太多了，SSR、PWA、SSG 等等，因此還是那句古話，術(shù)業(yè)有專攻，如果單純的用 Next.js 自己開發(fā)是可以做的，但是有一定的成本并且如果只是希望專注寫文檔建立文檔站點(diǎn)，沒必要用 Next.js 這把大刀。

• VuePress - 同樣優(yōu)秀

之前提到過了，小伙伴說 VuePress 用不習(xí)慣，因?yàn)樗?React 技術(shù)棧，因此可以這么說，Docusaurus 就是 React 社區(qū)對(duì)標(biāo) VuePress 的文檔建站框架。

• Gitbook - 優(yōu)秀但是理念不同

Gitbook 應(yīng)該是很多開源工具官方文檔的不二之選，但是因?yàn)樗陨韴F(tuán)隊(duì)的理念慢慢發(fā)生了變化，導(dǎo)致重心逐漸改到了商業(yè)化產(chǎn)品，所以損失了很多用戶。最熟悉的就是 Redux 文檔已經(jīng)由 Gitbook 變成了 Docusaurus，并且 Docusaurus 的理念就是對(duì)所有用戶免費(fèi)（當(dāng)然了，以后會(huì)不會(huì)變我是不知道，不過背靠大樹好乘涼，坐擁 Facebook 這個(gè)金主爸爸，相比不差錢）。



這里我想說一句，Docusaurus 官網(wǎng)很值得我們甚至各個(gè)框架學(xué)習(xí)的一點(diǎn)就是，它介紹別的框架對(duì)比的時(shí)候沒有貶低任何框架，而是把各個(gè)框架的在內(nèi)容站這一點(diǎn)的優(yōu)缺點(diǎn)都說出來了，并且誠懇的說了自己借鑒了對(duì)方框架的某些優(yōu)點(diǎn)。比起很多框架為了抬高自己貶低對(duì)方的行為真的優(yōu)秀很多～。更多詳細(xì)對(duì)比介紹，可以參考官方文檔，我這里只是簡(jiǎn)單總結(jié)。comparison-with-other-tools

Advance Docusaurus - 進(jìn)階
寫到進(jìn)階的時(shí)候，其實(shí)我就已經(jīng)覺得這次給小伙伴的推薦是沒錯(cuò)的，如果你只是想單純的做一個(gè)內(nèi)容文檔站，那么基本上十分鐘，就可以搭建一個(gè)非常像樣的內(nèi)容站，包含文檔和博客，只需要按照官方文檔的規(guī)則去書寫就可以了。
不過個(gè)人在學(xué)習(xí)一個(gè)新框架的過程里，希望能把它所有功能都盡可能的用一遍，可能不一定那么深入，淺嘗輒止即可，以后如果有類似的需求的時(shí)候就可以直接拿來使用，因?yàn)樗呀?jīng)在你的知識(shí)儲(chǔ)備庫里面了～
部署
一個(gè)基本功能的文檔博客內(nèi)容站點(diǎn)已經(jīng)完成了，但是還僅限于本地，接下來看看如何部署到公網(wǎng)，無論是自己看還是分享出去，都十分的方便。在這里我就簡(jiǎn)單介紹兩種：Github Pages 和 Vercel。

• Github Pages

部署 Github Pages 原本非常的簡(jiǎn)單，但是因?yàn)槟承┰驅(qū)е聶?quán)限驗(yàn)證踩了點(diǎn)坑，這里會(huì)詳細(xì)介紹。

官方說法： 部署你的文檔站到 github 只需要一個(gè)過程，那就是運(yùn)行命令 GIT_USER=your_username && yarn deploy。不過經(jīng)過我的實(shí)踐，因?yàn)槟承﹤}庫某些權(quán)限設(shè)置，所以并不能部署成功，如下圖所示：







因此需要額外的方法才可以部署成功。

周同學(xué)親身實(shí)踐：

// build.shGIT_USER=your_github_username GIT_PASS=your_personal_token yarn deploy關(guān)于 personal token 的生成方法以及可能遇到的問題，這里貼兩個(gè)網(wǎng)站，方便大家排查問題。
生成你的 personal token
如果生成 token 之后還部署失敗，那么很有可能就是你倉庫使用的是 ssh 協(xié)議而不是 https 協(xié)議，這里需要進(jìn)行切換。 ssh -> https
這樣之后，就肯定沒問題了。

看看我們最后的效果部署成功，搞定，直接看效果～

其實(shí)還可以利用 Github Actions 進(jìn)行自動(dòng)部署構(gòu)建，這里因?yàn)闀r(shí)間關(guān)系，大家可以自己去嘗試，官方有詳細(xì)的文檔，還是挺清晰的～

• Vercel

有點(diǎn)小波折的介紹了 Github Pages，接下來我來介紹一下 Vercel，這里相信不會(huì)有太多的波折，因?yàn)閭€(gè)人 Vercel 用的很多，感覺 Vercel 對(duì)于部署靜態(tài)站來說，真的不需要額外做很多事，話不多說直接開干。
首先，就是進(jìn)入 Vercel，然后導(dǎo)入我們的 Github 倉庫項(xiàng)目。



然后，啥都不用做，直接點(diǎn)擊發(fā)布，因?yàn)?Vercel 會(huì)幫我們識(shí)別倉庫類型，只要是他支持的，就都是一鍵部署。



部署好之后的效果如下圖所示：



哎呀，難道是我錯(cuò)付了嗎？我最信任的 Vercel 也離我而去了？別著急，我們仔細(xì)看看 Vercel 的強(qiáng)大能力，因?yàn)槲覀円呀?jīng) Github Pages 部署過一次了，因此我們的配置文件其實(shí)是按照 Github Pages 進(jìn)行配置的，所以比如 baseUrl 這個(gè)字段由于 Github Pages 的特殊性我們項(xiàng)目里配置的是 /repo-name/，但是 Vercel 其實(shí)沒有 Github Pages 的限制，baseUrl 直接是 / 就可以了，所以我們新開一個(gè)分支，feature/vercel，修改配置后重新部署，回到 Vercel，把部署分支切換成 feature/vercel，再看看效果：






我就不多說啥了吧，非常完美，到此，兩種非常方便的文檔站部署方法也就介紹完成了。
豐富功能
文檔內(nèi)容站初始化過程里，Docusaurus 已經(jīng)幫開發(fā)者做了大量的工作，比如首頁的生成，路徑的配置以及暗黑模式的適配等。那么除了這些功能之外，是否還有其他功能我們沒接觸到到呢？當(dāng)然有而且還有很多，在這里，就簡(jiǎn)單介紹幾個(gè)，其他的各位看官可以在自己搭建項(xiàng)目的過程里去摸索探尋～
1 - 美化首頁
前面介紹的博客站的搭建過程到部署基本上沒寫過一行代碼，十分的方便，也正因如此，導(dǎo)致其實(shí)我們的博客站目前來看很多東西都是必須按照約定來，比如首頁就是千篇一律的樣式，那么如果我們想讓首頁看起來更加好看或者說更加的個(gè)性化應(yīng)該怎么去做呢？結(jié)下來就介紹如何通過編寫代碼的形式美化首頁。



其實(shí)，Docusaurus 為我們保留了二開的能力，和 Next.js 很像，pages 文件夾的文件會(huì)被渲染成路有頁面，所以我們可以使用 React 的開發(fā)模式來對(duì)我們的頁面進(jìn)行擴(kuò)展，甚至出了文檔以外你也可以把它當(dāng)成一個(gè)系統(tǒng)去開發(fā)，下面我簡(jiǎn)單的把首頁進(jìn)行了改造，最后的效果如下：



2 - 搜索內(nèi)容
當(dāng)文檔博客站內(nèi)容太多的時(shí)候，搜索功能就顯得尤為重要了，Docusaurus 內(nèi)置就支持搜索功能，我們來把他暴露給用戶，方便使用。
實(shí)現(xiàn)搜索有兩種途徑：第一種，使用 algolia 提供的搜索能力（推薦），第二種，自己寫一個(gè)。還是前面那句話，我們只是想便捷建站，避免不必要的開發(fā)，所以直接使用第一種。


yarn add @docusaurus/theme-search-algolia然后去官網(wǎng)申請(qǐng)一下權(quán)限，因?yàn)槊恳粋€(gè)網(wǎng)站需要一個(gè)對(duì)應(yīng)的 apiKey 和 indexName，官方會(huì)給你發(fā)郵件把兩個(gè)必要內(nèi)容發(fā)給你，這里為了簡(jiǎn)單可用，我使用官方給的 Demo Key 來演示。



申請(qǐng)完權(quán)限之后，需要一定的審核時(shí)間，大家如果著急，可以用下面的進(jìn)行測(cè)試。

algolia: { apiKey: '25626fae796133dc1e734c6bcaaeac3c', indexName: 'docsearch',},配置完過后效果如下圖所示，可以看到還是非常的不錯(cuò)的








其他功能
其實(shí) Docusaurus 還有很多其他的功能，比如：

• Markdown 特性
  
• 瀏覽器支持
  
• 國際化等等
  

作為探索系列教程，更多內(nèi)容感興趣的各位小伙伴可以去自己根據(jù)自己的需求去試驗(yàn)一下，簡(jiǎn)單來說一句話，真的非常值得使用。
總結(jié)
最后，整個(gè)項(xiàng)目地址在這里 -> docusaurus-luffyzh-website，感興趣的小伙伴可以去看看，用來搭建自己的個(gè)人博客，抑或是框架文檔站，那真的是不二之選，非常的便捷給力～

---

我建了一個(gè)前端小白交流群，點(diǎn)擊下面的官方小卡片復(fù)制我的微信號(hào)，添加進(jìn)入交流群。我會(huì)給大家分享我收集整理的各種學(xué)習(xí)資料，組織大家一起做項(xiàng)目練習(xí)，幫助大家匹配一位學(xué)習(xí)伙伴互相監(jiān)督學(xué)習(xí)，歡迎加入