# 前言
這篇文章是寫給：
- 沒有程式語言基礎
- 略懂一點HTML和CSS
- 沒碰過Github和任何靜態網頁生成器
- 除了記事本和Notepad++以外沒碰過其他程式碼編輯器
- 幾乎不會使用命令提示字元/終端機
- 系統是Windows 10
- 不想花錢
- 基本上是指我啦。但經歷一兩個月的爬文和當個stack overflow junkie，終究還是搞得起來的。
看了這篇文章後基本上就能學會：
- 安裝程式碼編輯器
- 在Windows上安裝Hugo
- 安裝Hugo佈景主題
- 撰寫markdown格式文章
- 使用Hugo生成靜態網頁
- 將靜態網頁發佈到GitHub
- 利用[GitHub Pages](https://pages.github.com/)託管網站內容
- 利用[AWS Amplify](https://aws.amazon.com/tw/amplify/)託管網站內容
需要安裝的程式/套件：
- Hugo
- Git
- GitHup Desktop
- 程式碼編輯器([Atom](https://atom.io/)或[Visual Studio Code](https://code.visualstudio.com/))
--------------------------
# 安裝程式碼編輯器
相信需要閱讀本篇教學的朋友，應該都不熟怎麼直接在終端機上輸入指令。不想自虐的話乖乖裝編輯器吧，Atom和VSC都是免費的開源軟體。
- GitHub家的[Atom](https://atom.io/)
- 微軟家的[Visual Studio Code](https://code.visualstudio.com/)
裝哪個都行，用力點擊Download然後開始安裝就對喇，個人用的是Atom。
## Atom終端介面
Atom本身沒有終端介面，需要另行安裝package：[PlatformIO IDE Terminal](https://atom.io/packages/platformio-ide-terminal)
安裝方式：
- 進入Atom
- File ⇒ Settings ⇒ Install
- 在+Install Packages的搜尋列輸入`PlatformIO IDE Terminal`
- 點選Install
終端機啟用方式：**ctrl+`**
使用終端機可能會遇到的權限的問題。處理方式：
- 先退開Atom，右鍵Atom圖標 ⇒ 內容 ⇒ 相容性
- 設定 ⇒ 核選「以系統管理員身份執行此程式」⇒ 套用
--------------------------
# 安裝Hugo
本步驟主要參考了Mike Dane的影片教學：
{{< youtube G7umPCU-8xc >}}
[Hugo.io](https://gohugo.io/)建議的方法、需要使用對一般人(比方說我)很陌生的終端機安裝方式，其實也不用那麼麻煩。可以直接到[Hugo官方GitHub release](https://github.com/gohugoio/hugo/releases)下載核心程式。
比方說我的系統是64位元Windows 10，此時Hugo版本已推出到0.80.0，那麼我就在release頁面上尋找`hugo_0.80.0_Windows-64bit.zip`並下載回來，檔案很小只有14.2MB。下到稍微舊一點的版本也無所謂。
在電腦中任意位置創建資料夾，路徑必須是全英文，比方說`C:\User\Hugo\bin`，將zip檔解壓縮後的hugo.exe丟進bin資料夾，其他可以無視。
## 設定環境變數
然而Windows對於程式開發用戶並不是那麼親切，Windows無法自動透過終端指令尋找到Hugo核心程式，必須自行修改系統指認路徑：
- 在Windows左下角的開始鈕按下右鍵 ⇒ 搜尋 ⇒ 搜尋「系統環境變數」
- 在搜得的結果中點擊「編輯系統環境變數」
- 進階 ⇒ 環境變數 ⇒ [用戶名]的使用者變數
- 在項目中的變數欄選取「Path」⇒ 編輯 ⇒ 新增
- 輸入hugo.exe的所在路徑，以本例來說就是`C:\User\Hugo\bin`
- 確定 ⇒ 關閉環境變數視窗、系統內容視窗
接著打開Atom，開啟新的專案，指定根目錄為`C:\User\Hugo\`。啟動終端機並運行指令：
```
hugo version
```
以檢查hugo是否已經能夠正常運作。假設你從終端機看到一行：
`Hugo Static Site Generator v版本 windows/amd64 BuildDate: 日期`，就代表系統已經成功安裝Hugo！
--------------------------
# 安裝Hugo佈景主題
首先，進入Atom並啟用終端機，在專案根目錄`C:\User\Hugo\`運行
```
hugo new site Mysite
```
hugo會在根目錄下創建一個名叫`Mysite`的資料夾，這個資料夾名稱可以隨意自訂。在Mysite裡面會自動生成[以下結構](https://gohugo.io/getting-started/directory-structure/)：
名稱 | 解說
--- | ---
[archetypes](https://gohugo.io/content-management/archetypes/#readout) | 定義文章/資料的原型，本教學中用不到
[content](https://gohugo.io/content-management/organization/) | 放置部落格文章的資料夾
[data](https://gohugo.io/templates/data-templates/) | 類似content資料夾，但存放語法、掛件等組態檔案，本教學中用不到
[layouts](https://gohugo.io/templates/) | 存放網站外觀模板
[static](https://gohugo.io/content-management/static-files/) | 存放所有靜態元件(static element)，比方說css、js、svg等
[themes]((https://themes.gohugo.io/)) | 佈景主題庫
[config.toml](https://gohugo.io/getting-started/configuration/) | 選項(settings)
完全不想碰任何程式和網頁語言的前提下，只需要了解如何使用content、themes、comfig.toml，就能架設自己的部落格。
[Hugo官方網站的主題清單](https://themes.gohugo.io/)，目前已經有三百多個主題任君挑選。我也低調架了一個自己專用的主題，就拿來當做本文的教學範例。
> 我的佈景主題：[Earl Grey](https://github.com/offrecordrae/EarlGrey)
瀏覽官方主題頁面會注意到，Download指向的都是Github的倉庫(repository)。要怎麼下載主題呢嗯？這邊提供兩個方法：
## 直接下載壓縮包
至主題頁面的Github倉庫，點擊「Code」綠色按鈕 ⇒ Download ZIP
Github倉庫壓縮包的資料夾名稱都會加上branch「-master」，以本教學為例，主題的資料夾名稱會變為`EarlGrey-master`。將資料夾解壓縮到`Mysite\themes`底下，修改資料夾名稱(去掉branch名)，使其結果為`Mysite\themes\EarlGrey`。
## 使用Git下載佈景主題
比較主流的主題安裝方式，是透過Git下載。
[Git的下載頁](https://git-scm.com/)，旁邊那個大大綠綠的鈕給它點擊下去，版本號怎樣都隨意，我們只需要用到很簡單的功能，下載完執行它就能完成安裝。安裝中間提供很多選項，不熟悉的話通通用預設值就好，唯注意其中一步驟顯示「Choosing the default editor used by Git」，選擇Git的預設編輯器，以本教學為例應該要選擇Atom(Use Atom as Git's default editor)。
安裝完成後進入Atom，在網站目錄`C:\Users\Hugo\Mysite\`執行
```
$ git init
$ git clone https://github.com/offrecordrae/EarlGrey.git themes/EarlGrey
```
注意$號在這裡僅作為區隔每行指令的提示，每輸入一個指令最末須以enter鍵發送。
## 編輯config.toml
使用Atom或任何純文字編輯器打開Mysite\themes\config.toml，在裡面加上一行
```toml
theme = "EarlGrey"
```
這樣主題就安裝好囉！
--------------------------
# 撰寫Markdown格式的文章
主題安裝完，接下來要編寫第一篇部落格文章。Hugo支持Markdown標記語法，詳細的書寫格式可以從[本站的範例文章](../demo-text/)查閱。
Markdown只是一種標記式語法，十分鐘就能學會。比方說我打開記事本用純文字寫了這麼一段話：
```
# 我是第一級標題
我是第一級標題下的附屬文字內容。
### 我是第三級標題
[網站名稱](網站的網址)
我是列表：
- 列表的第一項目
- 列表的第二項目
- 第二項目的第一子項目
- 第二項目的第二子項目
```
透過Hugo內建的[Goldmark](https://github.com/yuin/goldmark/)引擎渲染後，看起來就會長這樣：
<h1>我是第一級標題</h1>
我是第一級標題下的附屬文字內容。
<h3>我是第三級標題</h3>
[網站名稱](網站的網址)
我是列表：
- 列表的第一項目
- 列表的第二項目
- 第二項目的第一子項目
- 第二項目的第二子項目
只要學會這幾種格式，幾乎就等於掌握了Markdown。有沒有狠簡單！
## Front Matter
每一篇放在Hugo裡的部落格文章，都必須在最開頭加入[Front Matter](https://gohugo.io/content-management/front-matter/)。Hugo支援數種語言格式：TOML、YAML、JSON、ORG，我個人用的是YAML格式。[^1]
[^1]: 在安裝Hugo之前，我曾經使用過台灣團隊開發的[Hexo](https://hexo.io/zh-tw/)，Hexo只支援[YAML和JSON格式](https://hexo.io/zh-tw/docs/front-matter.html)。
以本篇文章為例，Front Matter的寫法為：
```yaml
---
title: Hugo手把手安裝教學
date: 2021-01-19 16:33:57
tags:
- Hugo
- Host
- Github
categories:
- 示例-demo
- 架站-Website
- 教學-Tutorial
---
```
## 文章製作流程
1. 將需要放在部落格裡的文章以markdown格式寫好。
2. 文章開頭加入符合格式的Front Matter。
3. 將文章存檔，副檔名為md。
4. 以本教學為例，將md檔放入Mysite/content/posts路徑下。
5. [運行本地server](#在本地預覽hugo網頁)，可離線即時預覽網站結果。
## 繼續閱讀
舊式的部落格首頁生成的文章列表，通常都包含標題和內文的開頭幾行字，若要閱讀全文，通常需要按下「繼續閱讀」或是「文章標題」，進入單一文章的頁面。在Hugo裡，這種「會顯示在列表的開頭幾行內文文字」，稱做[Summary](https://gohugo.io/content-management/summaries)。
Hugo本身會自動生成Summary，但也可以手動指定Summary的截取點，指定語法為`<!--more-->`。使用範例如下：
```
---
我是front matter
---
我是summary
<!--more-->
我是點下繼續閱讀後，才會看到的文章內容
```
--------------------------
# 在本地預覽Hugo網頁
在Mysite目錄下運行：
```
hugo server
```
然後打開瀏覽器，拜訪`http://localhost:1313/`。每次使用瀏覽器，Hugo都會自動刷新，可以一邊寫文章一邊觀看結果。
有時候會發現文章沒有被瀏覽器顯示出來，這可能是時差產生的問題，Hugo本身採用[世界協調時間(UTC)](https://zh.wikipedia.org/wiki/%E5%8D%8F%E8%B0%83%E4%B8%96%E7%95%8C%E6%97%B6)，慢了台灣十個小時，**然而hugo並不會自動為未來的文章生成網頁內容**！
解決之道是在運行指令上加一個`-F`，顧名思義，F就是future的意思。
```
hugo server -F
```
--------------------------
# 將文章內容生成HTML網頁
在Mysite目錄下運行：
```
hugo
```
會生成一個public資料夾，內含所有需要發布到伺服器/託管平台的文件。
但剛才提到，台灣用戶有時差問題，所以保險一點改成運行：
```
hugo -F
```
--------------------------
# 靜態網頁託管服務
如何將生成的HTML網頁發布到網路上？最主流的管道，是透過靜態網頁託管服務(static website hosting)部署(deploy)自己的網站。這邊先演示兩種管道：[Github pages](https://pages.github.com/)和Amazon的[AWS Amplify](https://aws.amazon.com/tw/amplify/)。
除非網站流量很大，基本上不收費，對個人用戶來說非常足夠。免費方案細節：
| 服務 | 供應商 | 專案數量 | 協作人數 | 儲存空間 | 月流量 | 其他限制(每月) |
|:-------------|:-------|:---------|:---------|:---------|:-------|:-----------|
| Github Pages | GitHub | 無限 | 無限 | 500MB | 無限 | 私人倉庫有2000建立分鐘，公開倉庫則為無限 |
| AWS Amplify | Amazon | 無限 | 無限 | 5GB | 15GB | 1000建立分鐘 |
--------------------------
# 透過Github Pages發布網站
Github Pages是Github提供的網頁代管服務，想用它就要先[辦個github帳號](https://github.com/)。
## 創建GitHub倉庫
1. 建立並登入個人github帳號，主畫面右上角有個小「+」按鈕，點擊後選擇「New repository」。
2. Create a new repository ⇒ Owner，選擇自己的帳號
3. Repository name=倉庫名稱，假設你的用戶名為ABC，那麼在本欄就要輸入`ABC.github.io`
4. 選擇Public
5. Initialize this repository with: 下方的核選表可以啥都不用選。
6. 點下Create repository，倉庫創建完畢。
7. 進入倉庫頁面，點選「小齒輪 Settings」
8. 進入Settings，Optons分頁中往下拉到GitHub Pages區塊
9. Source的第一個下拉式選單，選擇master分支
10. 第二個下拉式選單，選擇/(root)的資料夾
11. 點擊save鈕，本倉庫的內容就會自動發布到GitHub Pages上囉！以本教學為例，發布內容的首頁為`https://ABC.github.com`[^2]
[^2]: 請不要真的去拜訪這個網址，我的帳號不是ABC。
## 安裝GitHub Desktop
GitHub Desktop和雲端空間概念有點像，負責讓用戶「手動」同步電腦(=本地資料夾)和網路(=GitHub倉庫)兩端的資料。注意這邊特別強調是手動，因為它並非即時的同步，每次同步兩端資料，都需要透過用戶手動操作。
如果你也是不熟悉使用終端機指令的用戶(包括我)，就快裝個[桌面版GitHub](https://desktop.github.com/)吧。一樣是看到那大大的藍色鈕就點擊下去，程式大小約80MB。下載點開程式就直接完成安裝[^3]，程式會要求登入已創建的Github帳號。
[^3]: Github desktop一經啟用便會自動安裝在`%appData%\Local\`之下，用戶本身並不能指定它的安裝位置。