學習透過 Gatsby.js 架設部落格

本文會提到

1. 一些對使用個人部落格的想法 (個人廢話)
2. 開發環境的前置準備實際執行一輪的筆記
3. 稍微了解 Gatsby.js 如何產生出一頁、模組以及 CSS 套用等

前言

一直以來都有架設一個部落格的想法，
覺得日常的學習可以被記下來是一件很好的事情，
但心裡又會覺得似乎不用那麼麻煩 (其實就是懶)，
上一季因為公司要求績效報告要交學習心得以後，
開始嘗試紀錄學習心得以後發現，
有寫下紀錄與只是讀過甚至是自己動手做一輪卻沒有記錄下來的差異是很大的，
因為在紀錄的過程中會從要講述給別人聽的角度去發現有些地方自己其實無法去解釋，
所以又會回過頭了解沒有弄懂的地方。
剛好在這一季的績效報告有要求學習心得一定要以部落格的形式，
(我是上一季學習筆記寫 MD 放在 gist 上的懶人..XD)
也算是加速了我在這一季重新架設出一個部落格。

為什麼我用 Gatsby.js 來架設部落格

其實要達成自我學習筆記放在部落格這個條件，
有很多免費且簡單的方案可以選擇，
我曾經用 Blogger 寫過文，
雖然很方便，
但是寫作體驗上我非常不喜歡，
改樣板也很麻煩。

我心中理想的部落格有:

1. 要可以用 MD 格式
   (目前沒看過網頁編輯器比直接寫 MD 好用的)
2. 設定到可以寫第一篇文的前置作業的成本不要太高
   (成本包含時間與金錢等)
3. 方便部落格搬家
   (現成部落格服務搬家通常不容易)
4. 程式碼高亮
5. [加分條件] SEO 支援
6. [加分條件]可以用 Git 版控做文章管理

大部分除 WordPress.com 的部落格服務可以達成

• [] 要可以用 MD 格式
  (這應該是不一定有支援)
• 設定到可以寫第一篇文的前置作業的成本不要太高
• [] 方便部落格搬家 (部落格搬家是可以當一門生意的，搬部落格其實很麻煩)
• [] 程式碼高亮
  (這個算是不一定支援，大部分要透過 js 套件來完成)
• [加分條件] SEO 支援
  (基本上都會支援)
• [] [加分條件]可以用 Git 版控做文章管理

WordPress.com 的部落格服務可以達成:

• 要可以用MD格式
• 設定到可以寫第一篇文的前置作業的成本不要太高
• 方便部落格搬家
  (官方直接支援搬到自架 WordPress 主機)
• 程式碼高亮
• [加分條件] SEO 支援
• [] [加分條件]可以用 Git 版控做文章管理

但搬到 WordPress 自架主機則會變成:

• 要可以用 MD 格式
• [] 設定到可以寫第一篇文的前置作業的成本不要太高
  (主機設定時間成本以及主機金錢成本等，WP 主機維護相關知識對目前的我來說能在工作上沿用的程度不高)
• 方便部落格搬家
• 程式碼高亮
  (需安裝套件)
• [加分條件] SEO 支援
• [] [加分條件]可以用 Git 版控做文章管理

而靜態網頁產生器(Static site generator)可以達成的有:

• 要可以用 MD 格式
• 設定到可以寫第一篇文的前置作業的成本不要太高
  ( Github 以及 MD 都是現成的，網頁前端技能學習可以直接在網頁開發領域沿用)
• 方便部落格搬家
  (都是靜態檔案可遷移性最高)
• 程式碼高亮
  (目前看過的都支援)
• [加分條件] SEO 支援
  (可能需要自己再優化)
• [加分條件]可以用 Git 版控做文章管理

SSG 看起來很美好，
但其實這樣會捨棄掉一些東西， 比方像是:

1. 點擊計數器
2. 留言功能

這部分只能依賴外部服務來達成，
但目前先不考慮。

在動手前看了 Gatsby.js 跟 Next.js 這兩套以 React 為基底的框架，
選擇 Gatsby.js 的原因還蠻單純的，
看起來 Gatsby.js 的 Plugin 生態系比較充足，
且 Next.js 現成合適的 Starter 比較少，
最後聽見強者我同事說 Next.js 沒有 server site render 的話會有些問題， 就確定以 Gatsby.js 起手了。

前置環境

使用 Gatsby 需要以下環境

1. Node.js
2. Git
3. Gatsby cli

可參考 Gatsby 官方網站教學

以下簡單帶過

Node.js

Gatsby 需要 Node.js 環境，
可以到 NodeJs 官方網站有安裝的方法，
或是參考 Gatsby 官方網站的教學，
這裡我使用 choco 在 windows 平台上做安裝 NodeJs lts 版

choco install nodejs-lts

安裝完後再 terminal 下檢查是否正確安裝

node -v

會顯示類似以下訊息

v12.18.3

Git

如果沒有裝的話， Gatsby 有提供 Git 安裝教學，
或是可以參考網路上的其他教學做安裝

安裝 gatsby-cli

官方安裝教學

以下是實際操作的簡略紀錄

執行以下指令

npm install -g gatsby-cli

個人不喜歡開啟匿名資料收集 ( telemetry )，
所以如果想要關閉的話可以下以下指令關閉

gatsby telemetry --disable

可以參考 Gatsby 官方網站的說明

一個簡單的Hello World

可參考官方網站的教學，
以下是實際操作的簡略紀錄

在 terminal 下以下指令新增專案

gatsby new hello-world https://github.com/gatsbyjs/gatsby-starter-hello-world

gatsby new 指令的結構是

gatsby new [SITE_DIRECTORY_NAME] [URL_OF_STARTER_GITHUB_REPO]

在跳到工作目錄以後執行指令就可以將網站以開發模式跑起來，

cd hello-world

gatsby develop

小插曲

在我學習期間，
線上的 hello-world 照著跑是無法開啟的，
會看到以下錯誤:

Error: Cannot find module 'gatsby-cli/lib/reporter'

這部分只要

1. 到 package.json 的 Gatsby 從 2.24.41 > 2.24.42
2. 刪除 package-lock.json

3. 執行以下指令

   npm i gatsby-cli
   npm install
   gatsby develop

就可以了

如果照著操作到現在，
就可以透過 localhost:8000 來訪問範例 Gatsby 網站，
如果自己產生最小可用的 Hello-world 的話則需要以下檔案

.
├── src
├── gatsby-config.js
└── package.json

並在工作目錄下執行 npm install 後就可以執行 gatsby develop 並成功啟動 Gatsby 開發模式

Gatsby Page

在前面一點的文章中我們按照 Gatsby 官方教學跑了一個 Hello-World，
當使用 gatsby develop 指令啟動開發伺服器後，
會開啟 Homepage，
這個檔案在 src/pages/index.js，
在 Gatsby 中，
任何定義在 src/pages/*.js 的 React component 會被當成是 Gatsby Page，
舉例像是如果要新增一個 about 頁的話，
就要新增 src/pages/about.js

import React from "react"

export default function About() {
  return (
    <div style={{ color: `green` }}>
      <h1>About Kevin</h1>
      <p>Some introduction.</p>
    </div>
  )
}

page components & sub components

現代網頁比較複雜，
通常網頁前端開發上也會做模組化，
如果要增加模組的話要新增 src/components/*.js
如果我們新增一個 src/components/header.js

import React from "react"

export default function Header(props) {
  return <h1>{props.headerText}</h1>
}

並將首頁改成

import React from "react"
import Header from "../components/header"

export default function Home() {
  return(
    <div>
      <Header headerText="Header from index" />
      <div>Hello world! aaa</div>
    </div>
  )  
}

此時畫面就會顯示

Header from index
Hello world! aaa

如果要從Home頁跳到 About 頁的話可以使用

<Link to="/about/">About</Link>

在使用時要額外 import 套件

import { Link } from "gatsby"

增加網站的 Style

通常來說一個網站都會有一些全站共用樣式，
在 Gatsby 中， 我們需要先建立 gatsby-browser.js，
然後再將 .css 檔案加在 gatsby-browser.js，
如果要加入全站用的樣式的話，
可以加入
src/styles/global.css

並在 gatsby-browser.js 加入

ES Module syntax

import "./src/styles/global.css"

或是

CommonJS syntax

require('./src/styles/global.css')

*以上的差別是 CommonJS 可以在 node.js 環境中執行，ES Module 不可以

sub components CSS

在 src/components 加入以下檔案

articles-part.js

import React from "react"
import ArticlesCSS from "./articles.module.css"

console.log(ArticlesCSS);

export default function ArticlesPart() {
  return (<div class="articles-part">some article</div>)
}

articles.module

.articles-part {
    margin: 5%;
    background-color: aqua;
}

這時候會發現 CSS 沒有正確在套用在畫面上，
原因是在 build 的時候 CSS 會被打包成特定檔案格式，
實際產生的 CSS 檔與 build 出來的 CSS 檔內容不同，
從 debug console 可以發現加載的 CSS 檔內的 CSS 樣式是有加上隨機字串的，
這時候只要參考 console.log(ArticlesCSS) 內的物件， 改成

import React from "react"
import ArticlesCSS from "./articles.module.css"

console.log(ArticlesCSS);

export default function ArticlesPart() {
  return (<div class={ArticlesCSS.articlesPart}>some article</div>)
}

就能正確套用 CSS 樣式。

學習了一些基礎前置知識以後，
可以參考以下兩篇文來部署部落格:
透過 Travis CI 部署部落格
透過 GitHub Action 部署部落格

ref:

1. Tutorial: Learn how Gatsby works