logo
Published on

Docusaurus 2 介紹與使用

Authors
  • avatar
    Name
    Eddy Chang
    Twitter

實例

許多 Facebook 開放原始碼或周邊專案的官網都已經使用了 Docusaurus 2，例如Create React App、React Navigation、uniforms、Hermes、ComponentKit等等。

使用 Docusaurus 建置的網站範例有：React Native、Babel、Prettier等等。

靜態網站產生工具是什麼

它只是一種能將內容產生、佈署與維護靜態網頁(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.js與Yarn。

下面的指令會在執行目錄下建立一個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

Discuss on Twitter • View on GitHub