Skip to main content

使用 docusaurus 快速打造部落格

一直以來都有做一個網站來放筆記的想法，除了可以透過 markdown 語法寫作之外，也可以透過這個渠道和網民交流， 所以這個連假花了些時間使用 docusaurus 打造了一個部落格，以下是使用 docusaurus 建部落格的步驟。

Installtion​

npx create-docusaurus@latest [your project\'s name] [template]

File Strcture:

my-website
├── blog
│   ├── 2021-08-26-welcome
│   ├── 2019-05-28-first-blog-post.md
│   ├── 2019-05-30-2019-05-29-long-blog-post.md
│   └── 2021-08-01-mdx-blog-post.mdx
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Blog​

blog demo

  1. blog sidebar 裡的文章會依照檔名的時間排序，越晚的越上面，2021 的文章會比 2020 上面。
  2. 可以設定 blog only mode，請參考 blog only mode。
  3. 可以透過 routeBasePath 更改路由，並透過 path 更改檔案讀取位置，達到網站客製化，像是我把 blog 當作放作品集的地方，請參考 plugin-content-blog。

Docs​

docs demo

  1. 因為 sidebar.js 的關係，Docs 側邊的 sidebar 會自動依照 docs 資料夾裡的檔案生成，一個資料夾為一個 category，一個檔案為一篇文章，請參考 Autogenerated。
  2. 可以透過 front matter 客製化 siedebar items，像是順序與標題，請參考 Autogenerated sidebar metadata
  3. 可以設定 docs only mode，請參考 docs only mode。

Page​

page demo

docusaurus 和 jekyll 最不一樣的地方，就是可以用 React 寫 page 和處理互動的部分。

  1. 一個 component 等於一個 url，比方說，helloworld.js 等於 http://localhost:3000/helloworld.js。
  2. / 預設會顯示 pages 檔案夾裡的 index.js，可以透過 blog only mode 或 docs only mode 更改。
  3. 如果需要 navbar 與 footer，要把 component 包在 <Layout> 裡。
  4. 請參考 Creating Pages

Deploy​

部署相關設定主要在 docusaurus.config.js，需要特別注意的欄位：

  1. url: 'host name'
  2. baseUrl: 'base url'
  3. organizationName: <your github user name>
  4. projectName: 'minhsiungw.github.io'
  5. deploymentBranch: 'gh-pages'

特別注意 organizationName，如果不符合的話會無法部署。

這些設定完之後，到 github 開一個 repo，準備部署：

GIT_USER=<GITHUB_USERNAME> npm run deploy

GIT_USER 為 environment setting，如要使用 ssh key 部署的話可以把 GIT_USER 換成 USE_SSH = true。更多設定可以參考 Environment settings。

結語​

用 docusaurus 建立部落格真滴快，無論是樣式與使用者互動都已經設定好了，我們只需要把文章寫好，並針對一些路由做客製化設定即可開始部署，最後反而是部署花最多時間><