GitHub Page 是 github.com 上每一個 git 儲存庫的內建功能，可以用來架設靜態 HTML 網站。以筆者的 GitHub 帳號來作為例子，為了這次的鐵人賽範例架設了範例網站。它是由這個儲存庫設定而成。

https://github.com/terrylinooo/ironman-game-2022

從「Settings」進去，在左方導覽列，點選「Pages」即可看到設定區塊。

圖 a: 進入 GitHub Page 設定頁

設定完成後，就可以從以下網址進去。

https://terrylinooo.github.io/ironman-game-2022/

我們只要將 HTML 檔案更新到 GitHub 儲存庫即可，GitHub Page 的 CDN 更新內容的速度稍有延遲，不過最慢 10 分鐘以內就可以看到更新後的網頁。除非日後有其它需要用到資料庫的考量，一般來說，文件網站用純靜態的 HTML 就可以囉。很多開放原始碼的專案都是選擇這樣的方式。

建立文件網站

為專案建立組織

當我們使用個人帳號建立的 GitHub Page，網頁的網址都是屬於自己的 GitHub Page 網域底下的子目錄。有沒有辦法可以讓作品的文件網站網址看起來更短、更氣派一點呢？

答案是「Yes」

我們可以另外建立組織 (orginization)，並且在之間開一個和 GitHub Page 網域同名的儲存庫。

圖 b: 網頁右上方位置，下拉選單

頭像下拉選單，選擇「New organization」。

建立儲存庫

圖 c: 建立儲存庫，設定頁面

建立新的儲存庫，名稱設為「{帳號}.github.io」。

設定 GitHub Page

圖 d: GitHub Page，設定頁面

無論是個人帳號，或是組織帳號建立的儲存庫，在設定 GitHub Page 的方式沒有區別。

圖 e: GitHub Page，選擇套用的分支

設定讀取網頁檔案時，是從那一個指定的分支以及文件是放在那一個目錄。

設定自定網域

在「Custom domain」設定自己註冊的網域名稱之前，參考官方說明，確定將 DNS 設定調整如下：

A 記錄指向：

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

AAAA 記錄指向

2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

DNS 設定

圖 f: 域名註冊商 Dynadot 的 DNS 代管設定頁面

這次示範的網域名稱是在 Dynadot 註冊的，有提供 DNS 代管服務，在設定介紹依序將剛剛上來的 IP 位址填進去。確認有更新 DNS 之後即可。

可先 ping 看看網域名稱的 IP 是否已指向 GitHub Page 的 IP。

圖 h: GitHub Page 自訂域名區塊

接著輸入，按下「Save」按紐，即會開始確認剛剛輸入的網域名稱的 DNS 是否正確設定 A 記錄，指向 GitHub Page 的 IP 位址。

圖 i: GitHub Page 設定頁上方

設定成功，網頁上方即會提示目前 GitHub Page 的網址已經是我們自己的網域名稱。當設定完成後，原本的 GitHub Page 的網域名稱都會轉到新設定的網域名稱。

例如：

https://slidermjs.github.io

會轉址到：

https://sliderm.com

到這邊，建立文件網站的進度可以說完成了一半。

架站工具評估

雖然說直接設計 .html 檔案之後上傳到 GitHub Page 是最直接的方式，除非是很小的作品，也預期它只有幾頁就可以滿足給使用者想知道的內容，不然有幾種相當熱門的靜態網站架設工具可以選擇。

• Hugo
• Gitbook
• Jekyll

Hugo

Hugo 使用 Golang 程式語言編寫，是相當熱門的靜態網站生成工具，社群活躍，專案的維護者很熱情在這個專案上，是很不錯的選擇。

Gitbook

Gitbook 使用 Markdown 文件格式，有相當多的外掛可以使用，支援文件索引搜尋，很適合用來架設文件內容豐富的網站。這邊指的是自己用 NodeJS 架設的 GitBook 文件網站，而不是 GitBook 網站提供的服務。

Jekyll

Jekyll 是使用 Ruby 程式語言編寫，用來架設靜態部落格網站的熱門工具，提供相當多的熱門佈景主題，文件網站的說明也很完整，學習曲線較低，花幾個小時閱讀使用方式，練習使用就可以上手。

它生成的靜態網頁檔案會放在 _site 目錄中，不過不需要上傳這個目錄到 GitHub Page 的 git 儲存庫中，因為 GitHub Page 內建支援 Jekyll，只要上傳文件原始檔就會自動產生靜態網站。

圖 j: 本次鐵人賽作品文件網站首頁

• https://github.com/slidermjs/slidermjs.github.io (GitHub Page 儲存庫)
• https://sliderm.com (文件網站)

這次筆者為 Sliderm 架設的文件網站就是使用 Jekyll。

文件內容規劃

人是怕麻煩的動物，尤其是軟體工程師，常常為了怕麻煩而開發許多簡化流程的工具，反而花了更多時間 XD (感謝分享)。因此文件網站主要的任務是讓使用者快速評估此工具適不適合，而不是寫了很多的文字，但要使用者自己安裝自己試一次。

最重要的內容是提供使用此作品的「展示」(demonstration)，透過視覺讓使用者判斷是否喜歡，先有好感，才會去仔細閱讀文件是否齊全，使用上是否容易上手。

【查看範例】圖 k: 本次鐵人賽作品 DEMO 頁

內容重要性排序：

• 作品展示：實作的操作、效果呈現的網頁。
• 使用方法：套件的下載、安裝、初始化、使用範例。
• 套件的 API 及參數：詳細的說明，提供給使用者完整的細節查詢，也給有興趣參與專案提交 PR 的其它開發者更多的參考。
• 網站的美觀：反而是最不重要的，以上三點都完善了，再來改善網站的美術方面。

鐵人賽總結

以前端套件來說，功能的實現主要還是來自各種 CSS 屬性的應用。這次鐵人賽的內容前 20 篇大多提到很基本的 CSS 屬性及提供互動範例，幫助讀者們有更好的理解。介紹完 Slider 套件會用到的 CSS 屬性及 JavaScript 的事件處理之後，慢慢地才開始帶到 JavaScript 套件開發。

最後 10 篇介紹套件開發環境會用到的工具以及套件，發佈作品到 NPM 套件庫以及實作。

試試 Sliderm

如果你也想試試看這次筆者為鐵人賽示範用而開發的 Slider 套件，以下為使用方法。

安裝

npm install sliderm

透過 NPM 安裝。

import Sliderm from 'sliderm';
import css from 'sliderm/src/assets/scss/index.scss';

如果你也使用 Webpack 來打包專案，可以透過 import 引入 JS 及 SCSS 檔案。

<link rel="stylesheet" href="node_modules/sliderm/dist/css/sliderm.css">
<script src="node_modules/sliderm/dist/js/sliderm.js"></script>

或者在 HTML 中直接指定 JS 及 CSS 的檔案路徑。

<link rel="stylesheet" href="https://sliderm.com/dist/1.0.3/sliderm.css">
<script src="https://sliderm.com/dist/1.0.3/sliderm.js"></script>

由於示範網站放在 GitHub Page，筆者在發佈時也同步依照版號放置了打包好的 JS 及 CSS 檔案，可以直接使用。

HTML 結構

<div id="exampe-slider" class="sliderm">
    <div class="sliderm__slider">
        <div class="sliderm__slides">
            <div class="sliderm__slide">內容 1</div>
            <div class="sliderm__slide">內容 2</div>
            <div class="sliderm__slide">內容 3</div>
            <div class="sliderm__slide">內容 4</div>
            <div class="sliderm__slide">內容 5</div>
        </div>
    </div>
</div>

把要展示的內容依 HTML 結構放置。

如何使用

第一個參數為 CSS 選擇器名稱，第二個參數為組態設定。

 const sliderm = new Sliderm('#exampe-slider', {
    arrow: true,
    pagination: true,
    grouping: false,
    loop: true,
    preview: false,
    columns: 4,
    duration: 1000,
    spacing: 10,
    align: 'center',
});

主要提供兩個事件，後續更新會再提供更多的事件供使用者調用。

sliderm.on('slide.start', () => {
  console.log('開始滑動！');
});

sliderm.on('slide.end', () => {
  console.log('停止滑動。');
});

目前 Sliderm.js 還在後續的功能開發中，因此建議大家要使用的話，版號 1.1 之後再開始使用，筆者要等寫完 Test 以及補齊其它更多的功能，完善文件網站後再開始對外宣傳。

一個 JavaScript 套件從無到有，上架到 NPM 供大家下載使用，整個流程其實就是如此平易近人，有興趣的讀者們，不妨挑一個自己喜歡的主題打造一個套件喔，對自己的技術成長、將來在職場上也可以當作面試的作品集，真的是很棒的選擇！

希望大家看了這次的系列文章會有所收獲，我們明年的鐵人賽再見囉！

這次鐵人賽的文章範例可以在 GitHub Page 閱讀，而相關原始碼可在 2022 鐵人賽專用 GitHub Repo 下載。

Day 25 以後的 Slider 的原始碼在鐵人賽的範例儲存庫中，demo/sliderm-alpha 這個目錄。由於筆者是一邊寫鐵人賽文章一邊寫示範的套件作品，主要以教學為目的，因此在完成鐵人賽之後，新增功能及修正都放在 Sliderm.js git 儲存庫中。