想將TiddlyWiki搭建在GitLab Pages已經很久。今日終於用半個小時時間完成此事，完成後覺得竟然如此簡單。然而之前始終找不到合適的教程，實在讓人糾結，故而記錄要點（並簡單介紹TiddlyWiki在該模式下的使用），以便有需要者。

簡介

TiddlyWiki是一個工作在瀏覽器中的wiki系統，其對我來說最有用的特性是：1) 支持插件（通過JS）；2) 支持自定義宏 (macro)。

由於TiddlyWiki設計爲在瀏覽器中工作，所以理所當然地可以託管在GitHub Pages或GitLab Pages這類靜態網站上。雖然使用TiddlyWiki本身的單一HTML版即可，但我總覺得這樣比較臃腫，而且不好追蹤版本變更，所以更傾向於這種使用server版功能的方式（即每個tiddler是單一文件，之後轉換爲網站）。

雖然已有前人給出的搭建模板，只用fork過來即可使用，但我個人略有強迫症，想要一個“清淨”的版本。所以簡單翻閱了GitLab的相關說明頁面後，仿照其例子自己從頭構建了一個倉庫（及對應Pages）。

本文假設讀者有基本的git知識，並且已安裝tiddlywiki服務端軟件（tiddlywiki）。下面的描述均假設當前在一個空目錄/空的git倉庫中。

初始化TiddlyWiki

TiddlyWiki支持兩種模式：單一HTML頁面模式和本地服務器模式。既然要使用版本控制，本地服務器模式更加適合：該模式下，每個頁面（即Tiddler）均分別以文件形式存放，更適宜版本控制。

首先，使用下面命令創建服務器模式的TiddlyWiki：

tiddlywiki wiki --init server

該命令將會創建一個名叫wiki的目錄，其中存放TiddlyWiki服務器模式配置。要在本地瀏覽或更改該wiki的內容，執行下面命令，並且打開瀏覽器訪問localhost:8080：

tiddlywiki wiki --server

對該wiki的編輯均會存放在wiki目錄下（的tiddlers目錄中）。而且配置、插件等也是以文件形式存在，可以說是無縫接合。

在該模式下，對tiddler的修改會自動保存（可能有較小延遲），而不需要（也不應該）使用“保存”按鈕——除非你的確想將你的wiki保存爲單一HTML。類似地，在GitLab Pages的頁面上的修改不會被持久化，因爲沒有後端服務程序在執行——但你可以將其當成一個安全的沙箱隨便修改。

GitLab Pages

GitLab Pages是使用GitLab的流水線機制而構建起來的特殊功能。其理念源於GitHub Pages，但實現方式有所區別，且GitLab Pages更爲靈活（至於github pages如要達到該靈活度，則必須依賴外部CI）。

在倉庫根目錄中，.gitlab-ci.yml控制GitLab流水線如何執行——當push發生時，GitLab會自動根據該文件執行CI。GitLab Pages在.gitlab-ci.yml中使用專門的pages節。在該CI執行結束後，倉庫（生成文件中）的public目錄中的文件會被發佈到GitLab Pages上（網址構成同GitHub Pages類似）。GitLab Pages完全依賴該配置文件中的描述，不需要像GitHub那樣手動打開Pages。

對於部署TiddlyWiki來說，所用的.gitlab-ci.yml內容其實很短：

image: node:latest

pages:
  stage: deploy
  script:
    - npm install -g tiddlywiki
    - tiddlywiki wiki --build
    - mv wiki/output public
  artifacts:
    paths:
      - public
  only:
    - master

原理上看，搭建的方法就是通過tiddlywiki的工具，在CI時生成頁面，然後放到public目錄。由於tiddlywiki是nodejs程序，所以在.gitlab-ci.yml的image部分聲明使用nodejs的docker鏡像。

注意，如前文所說，我這裏將tiddlywiki的文件結構（tiddlywiki.info所在地）放在之前所描述的wiki目錄中。該代碼片段中所有引用wiki目錄的地方均是出於此處。

至此，GitLab方面也已經設置完畢。之後只要正常將該倉庫提交，並push到GitLab上即可。