Docusaurus 2 介紹與使用

Docusaurus是一個產生靜態網站的工具(static-site generator,雖然官方的Github中不以這個關鍵字稱它)。它使用了 React 技術,提供快速簡易的建置、佈署與維護文件型的網站。本文提供了v2的簡單介紹與建置說明。

Docusaurus 2 版本尚在 alpha 開發中,有許多計劃中的功能(多國語言、外掛...等等)還未完成,也有可能有很多潛在的問題,使用時請自行評估React 與更新未來版本的能力。

實例

許多 Facebook 開放原始碼或周邊專案的官網都已經使用了 Docusaurus 2,例如Create React AppReact NavigationuniformsHermesComponentKit等等。

使用 Docusaurus 建置的網站範例有:React NativeBabelPrettier等等。

靜態網站產生工具是什麼

它只是一種能將內容產生、佈署與維護靜態網頁(html)的工具,也就是說最終所有服務網站上的網頁都是 HTML 檔案。

因此這種工具並「不是」以下的兩種常見與網站有相關的名詞:

CMS

它不會有協助你管理網站上內容的地方,在這種工具中,管理內容的方式是要透過一般電腦中的管理和編寫檔案方式(常見的是 Markdown 檔案)。

網站應用程式

它不是一個會在網站主機上執行的應用程式,它只有在本地端命令列工具可以執行使用,可以先在本地端的電腦中測試,最後用來打包或佈署到遠端的網站主機上。

為什麼要使用靜態網站產生工具來建置網站

因為無資料庫或網站伺服器上的執行程式(php, .net, node.js...),加上網站伺服器會作快取,頻寬使用上也會減少很多。

值得一提得是,目前靜態網站伺服器有很多免費的主機可以使用,也可以自訂自己的網址和有免費的SSL功能,省去了自架主機的工夫,所以也很省時省錢。綜合起來有以下的幾個優點:

  • 安全
  • SEO
  • 可預覽
  • 可版本管理

Docusaurus 2 適合我嗎

Facebook 團隊創造了 Docusaurus 用於建置文件類的靜態網站,它適合於以下的幾種網站的類型:

  • 技術性文章網站(見上面的範例)
  • 單純的部落格網站

相較於其它的的稱為靜態網站產生工具,例如gatsby,Docusaurus 2目前還少了很多東西,因為它是以文件型的網站為導向,以下幾點是個人在使用後,了解的幾個限制或缺點(以目前的v2.0.0-alpha.58來說):

  • 製作網頁要會 React:Docusaurus 中的頁面(pages)是 React 元件,當然你不會 JSX 語法或 React 就可能用不了。
  • 只支援 Markdown 檔案文件:不如其它的像gatsby工具的內容支援性高,目前 blog 與 doc 都只支援 markdown 檔案。(註:內建支援MDX)
  • 版面固定:網站都差不多長得一樣(見上面的範例),除了(pages)保留了高度的客製化彈性外。
  • CSS樣式框架客制不易:Docusaurus 2 預設的佈景(theme)使用了一套叫infima CSS 樣式框架,這大概也是為了 Docusaurus 2 特別作的,不是一般常見的 CSS 樣式框架。但所幸還有提供了其它 CSS 的客制樣式的部份,但需要小心會互相覆蓋到。

安裝

參考官網上的 Installation 文件,安裝在自己的電腦上,推薦先安裝Node.jsYarn

下面的指令會在執行目錄下建立一個my-website的專案目錄,使用classic樣版:

npx @docusaurus/init@next init my-website classic

下面的指令可以在電腦中執行這個網站:

cd my-website
yarn run start

參考上面的官網說明,看.md的所在位置就大概知道怎麼開始撰寫文件或部落格,網站相關的全站設定都在docusaurus.config.js這個檔案中。

下面的指令是打包用的,會將整個網站的資料打包到/build資料夾中,這與佈署有關,請參考這一章的資料 Deployment

yarn run build

客製化(中文化)佈景

預設網站佈景中,有許多操作介面的文字都是寫死在佈景元件檔案(React元件)裡,官方提供了 Swizzling 的機制,可以讓你在專案的src/theme目錄中客制這些預設的佈景。

在專案根目錄執行以下的指令,然後重啟開發用伺服器:

yarn run swizzle @docusaurus/theme-classic

加入 scripts 或 stylesheets 在head

除了可以在 src/CSS/custom.CSS 自訂樣式外,如果需要外加 script 或 stylesheet 在 <head>...</head> 中,可以直接在 docusaurus.config.js 加入。

加入scripts

scripts: [
// 字串格式
'https://docusaurus.io/script.js',
// 物件格式
{
src: 'https://use.fontawesome.com/releases/v5.3.1/js/all.js',
defer: true,
},
],

加入stylesheets

stylesheets: [
// String format.
'https://docusaurus.io/style.CSS',
// Object format.
{
href: 'https://use.fontawesome.com/releases/v5.0.9/CSS/all.CSS',
// type: 'text/CSS',
crossorigin: 'anonymous',
},
],

其它

TODO: 已中文化好的 github repo