本文檔描述了儲存在此 Fossil SCM 儲存庫中的 JS/WASM 文件維護的一些特殊性。

跨Wiki連結對應表

更新 JS/WASM 版本

此網站以兩種形式託管 SQLite JS/WASM 組建：一種用於示範應用程式，另一種用於預發佈快照。更新它們需要一份標準的 SQLite 原始碼樹。

首先，從該樹的最上層目錄執行...

（注意：以下所有提及的「make」都需要 GNU Make。）

$ ./configure --enable-all
$ cd ext/wasm

然後，要更新示範程式碼

$ make update-docs

如果找到此儲存庫的 checkout，它將自動執行其工作，否則它將發出如何將其指向此儲存庫 checkout 的說明。它的輸出是更新此儲存庫的 checkout，但它不會 check in 任何東西。要測試結果，請從*此*儲存庫的最上層 checkout 目錄執行以下操作

$ make ui

這應該會開啟一個指向此儲存庫的瀏覽器視窗。從那裡，瀏覽到示範應用程式（連結在首頁上），並使用頁面底部的連結試用示範應用程式（如果成功不明顯，則可能失敗）。

要更新預發佈快照，請切換回標準 checkout 的 ext/wasm 目錄並執行

$ make snapshot

完成後，如果它可以找到此儲存庫的 checkout，則它會將生成的 ZIP 檔案移動到該目錄中，否則它將發出執行此操作的說明。

完成後，從此儲存庫的最上層 checkout 目錄執行以下命令

$ make uv-sync

如果它抱怨有多個 ZIP 檔案，請刪除除最舊的檔案以外的所有檔案，然後重新執行它。

這將更新 /uv/snapshot.html，將新的 ZIP 檔案打包到儲存庫中，並將其推送到遠端儲存庫（大概是標準網站，https://sqlite.dev.org.tw/wasm）。

此網站的客製化面板

此儲存庫的文件隱含地假設它將使用僅適用於此儲存庫的高度客製化的 Fossil SCM 面板來呈現。為此，託管此儲存庫的 CGI 包裝器腳本預計會將面板「固定」到網站的預設面板

#!/usr/bin/fossil
repository: /fossil/wasmdocs.fossil
jsmode: bundled
skin:

或等效項。空的 skin: 項目會導致 Fossil 使用網站的預設面板，並忽略任何透過 ?skin=NAME URL 標誌使用不同面板的客戶端請求。

編輯面板

開發和編輯此網站面板的*強烈建議*（也是最簡單的）方法是使用儲存庫的本地副本和 fossil ui 命令

$ fossil ui --skin $PWD/assets/skin
# Which can be abbreviated to:
$ make ui

檔案 assets/skin/*.txt 包含 fossil 格式的面板檔案，這些檔案被視為標準面板資料（而不是透過 fossil 面板編輯器進行的任何編輯）。

由於 --skin 標誌，這些檔案將被 ui 命令使用。只需在每次編輯這些檔案後重新載入網站即可。

要部署面板，首先使用以下指令將面板安裝到本地儲存庫：

$ make skin

然後使用以下其中一個指令將其部署到遠端儲存庫：

$ make push
# or:
$ fossil config push skin

skin 目標使用 skintxt2config 將面板的 *.txt 檔案轉換為適合 fossil config import 使用的格式，然後將該面板匯入到本地儲存庫。config push skin 步驟需要使用者在遠端儲存庫上擁有管理員權限。

網站選單

網站的主要選單是透過 Fossil 的 mainmenu 設定來配置的。對此沒有特定的規則，但它「應該」保持相當簡潔，並且*不*提供存取 Fossil 常規下拉式漢堡選單的途徑（目標是對一般使用者「盡可能隱藏」這是 Fossil 儲存庫的事實）。

範例

Home /doc/ckout/index.md L {}
Home /doc/trunk/index.md !L {}
{API Index} /doc/ckout/api-index.md L {}
{API Index} /doc/trunk/api-index.md !L {}
Timeline /timeline * {}
Files /dir L {}
Admin     /setup       {a s}          {}
Login /login !L {}
Account /login L {}

/doc/ckout 與 /doc/trunk 項目的技巧是讓開發人員預設存取最新版本，而一般使用者預設存取主幹版本。

面板 CSS

assets/skin/css.txt 中的 CSS 是構成核心面板的「低階」CSS。可以在該檔案中自由編輯或新增 CSS，但建議的做法是盡可能保持該檔案與上游面板（Fossil 的預設面板）一致，並在 assets/fossil-doc.css 中維護此儲存庫的特定編輯。

fossil-doc.css 包含所有並非特別衍生自上游 Fossil 面板的樣式。它包含網站語法高亮主題的 CSS。

深色模式

因為此網站強制使用者使用特定面板，所以我們無法使用 Fossil 的面板選項來簡單地選擇深色模式面板。

此網站的深色模式透過將 CSS 類別 dark-mode 新增到文件的 html 元素來運作。面板的 css.txt 包含許多以此為篩選條件的規則，以覆寫主要面板的顏色（但不覆寫其他樣式）。

深色模式偏好設定是透過面板的 header 安裝的事件處理器儲存在瀏覽器的 localStorage 中。

網站標誌

標誌圖像是透過 Fossil 的 logo-image 設定來管理的。標誌的副本位於 /assets 目錄中。該副本並未用於網站標頭，因為我們顯然無法使用 /raw/... 或 /doc/... 取得可快取的連結，而 /logo 至少會設定最短的快取持續時間。

章節編號

這些文件中（如果有的話）的章節編號是透過 fossil-doc.css 自動插入的，但僅限於透過 /doc/... 提供的頁面。從例如 /file/... 提供的相同檔案將不會自動編號。

自動章節編號是否有幫助或造成困擾尚未確定。

因為編號全域套用於 /doc URI，所以它們有時看起來會 misplaced。例如，只有一個標題的頁面將會有一個多餘的章節 1 編號。為了應對這種情況，網站面板會在下列情況下停用自動章節編號

頁面少於 2 個 <H1> 元素。
頁面包含以下格式的元素
<span class='disable-section-numbers'></span>
如果找到此元素，它將會從 DOM 中移除，因此它不會影響頁面佈局。

章節編號是透過將 disable-section-numbers CSS 類別新增到 <body> 元素來停用的。對應的 CSS 規則位於 fossil-doc.css 中。

語法高亮

assets/skin/header.txt 載入 highlight-sqlite3.min.js，其中包含 highlightjs 的複製/貼上版本，以及網站特定的頁面載入 JS 程式碼，該程式碼會在以 pre 標籤和 lang-XYZ 類別包裝的 code 標籤上安裝語法高亮。也就是以下格式的 Markdown 程式碼區塊

```XYZ
code goes here
```

highlight-sqlite3.min.js 通常僅在更新本地的 highlightjs 副本時才需要編輯，需要注意的是，該檔案的上半部必須包含 100% 原始的上游 highlightjs 程式碼，而下半部則包含本網站的相關程式碼。

雖然沒有任何文件明確依賴 highlightjs 的任何功能，但 fossil-doc.css 可能包含特定 highlightjs 版本的 CSS 類別，因此升級到 highlightjs 的新主要版本時必須格外小心。