本文档描述了存储在此 Fossil SCM 仓库中的 JS/WASM 文档维护的一些特殊之处。

站点间映射

更新 JS/WASM 版本

此站点以两种形式托管 SQLite JS/WASM 构建：一种用于演示应用程序，另一种用于预发布快照。更新它们需要一份规范的 SQLite 源代码树副本。

首先，从该树的最顶层目录执行以下操作…

（注意：下面所有对“make”的引用都需要 GNU Make。）

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

然后，要更新演示代码

$ make update-docs

如果它找到此存储库的检出，它将自动执行其工作，否则它将发出有关如何将其指向此存储库的检出的说明。其输出是更新此存储库的检出，但它不会检入任何内容。要测试结果，请从此存储库的最顶层检出目录执行以下操作

$ make ui

这应该会启动一个指向此存储库的浏览器窗口。从那里，浏览到演示应用程序（链接在第一页上），并使用页面底部的链接尝试演示应用程序（如果成功不明显，则可能失败）。

要更新预发布快照，请切换回规范检出的 ext/wasm 目录并执行

$ make snapshot

完成后，如果它可以找到此存储库的检出，则它会将生成的 ZIP 文件移动到该目录中，否则它会发出有关如何执行此操作的说明。

完成后，从此存储库的最顶层检出目录运行以下命令

$ make uv-sync

如果它抱怨有多个 ZIP 文件，请删除除最旧文件以外的所有文件并重新运行它。

这将更新 /uv/snapshot.html，将新的 ZIP 文件打包到存储库中，并将其推送到远程存储库（可能是规范站点，https://sqlite.ac.cn/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 包含许多规则，这些规则会对此进行过滤以覆盖主皮肤的颜色（但不会覆盖其他样式）。

深色模式首选项存储在浏览器的 localStorage 中，方法是通过皮肤的标题安装的事件处理程序。

站点徽标

徽标图像通过 fossil 的 logo-image 设置进行管理。徽标的副本位于 /assets 目录中。该副本未在站点标题中使用，因为我们显然无法使用 /raw/... 或 /doc/... 获取可缓存的链接，而 /logo 至少设置了最小的缓存持续时间。

章节编号

这些文档中的章节编号（如果有）是通过 fossil-doc.css 自动注入的，但仅限于通过 /doc/... 提供服务的页面。例如，从 /file/... 提供服务的相同文件不会自动编号。

自动章节编号是否有用尚无定论。

由于编号全局应用于 /doc URI，因此它们有时看起来可能不合适。例如，只有一个标题的页面将具有多余的第 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 标记安装语法高亮显示。即此形式的降价代码块

```XYZ
code goes here
```

highlight-sqlite3.min.js 通常仅在更新 highlightjs 的本地副本时需要编辑，注意该文件的上半部分包含上游 highlightjs 的 100% 原版副本，而下半部分包含此站点的相关代码。

文档中没有任何内容特别依赖于 highlightjs 的任何功能，但 fossil-doc.css 可能包含特定于给定 highlightjs 版本的 CSS 类，因此在升级到新版本的 highlightjs 时必须小心。