This document describes some of the peculiarities of the maintenance of the JS/WASM documentation stored in this Fossil SCM repository.

Interwiki Map

These docs make use of several interwiki map entries.

Site Skin

This repository's documentation implicitly assumes that it will be rendered using a highly customized Fossil SCM skin suited only for use in this repository. To that end, the CGI wrapper script for hosting this repository is expected to "pin" the skin to the site's default one:

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

or equivalent. The empty skin: entry causes Fossil to use the site's default skin and ignore any client-side requests to use a different skin via the ?skin=NAME URL flag.

Why pin the skin? Because the doc pages rely on no small amount of custom CSS and JS code which gets installed via the skin. If a user may select their own skin, the documentation will not be rendered as intended (e.g. no automated section numbering or syntax highlighting).

That said... being less pedantic in that regard may well be appropriate and we may laxen the forced-skin approach at some point, with the caveat that skins other than the default would lack certain features intended for the docs.

Editing the Skin

The strongly preferred (and simplest) way to develop and edit this site's skin is using a local clone of the repository and the fossil ui command:

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

The files assets/skin/*.txt contain the fossil-format skin files and these are considered to be the canonical skin data (as opposed to any edits made via the fossil skin editor).

Thanks to the --skin flag, those files will be used by the ui command. Simply reload the site after each edit to those files.

To deploy the skin, first install the skin into the local repository with:

$ make skin

and then deploy it to the remote with one of:

$ make push
# or:
$ fossil config push skin

The skin target uses skintxt2config to convert the skin's *.txt files to a format suitable for use with fossil config import, then imports that skin into the local repository. The config push skin step requires that the user have administrator rights on the remote repository.

Site Menu

The site's main menu is configured via fossil's mainmenu setting. There are no specific rules for it but it "should" remain fairly minimal and not provide access to fossil's conventional drop-down hamburger menu (the goal being to "mostly hide" the fact that this is a fossil repository from casual users).

An example:

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 {}

The trickery with the /doc/ckout vs /doc/trunk entries is to give developers access to the tip version by default and casual users access to the trunk by default.

Skin CSS

The CSS in assets/skin/css.txt is the "low-level" CSS which makes up the core skin. CSS may be freely edited in, or added to, that file, but the preferred approach is to keep that file as close to the upstream skin (Fossil's default skin) as possible and maintain edits specific to this repository in assets/fossil-doc.css.

fossil-doc.css contains all styling which is not specifically derived from the upstream fossil skin. It includes CSS for the site's syntax highlighting theme.

Dark Mode

Because this site forces a specific skin on the user, we cannot use fossil's skinning options to simply select a dark-mode skin.

This site's dark mode works by adding the CSS class dark-mode to the document's html element. The skin's css.txt includes many rules which filter on that to overwrite the colors (but not other styling) from the main skin.

The dark-mode preference is stored in the browser's localStorage via an event handler installed via the skin's header.

Site Logo

The logo image is managed via fossil's logo-image setting. A copy of the logo is in the /assets directory. That copy is not used in the site header because we apparently cannot get a cacheable link to it using /raw/... or /doc/..., whereas /logo sets at least a minimal cache duration.

Section Numbering

The section numbers in these docs (if any) are automatically injected via fossil-doc.css, but only to pages served via /doc/.... The same files served from, e.g. /file/..., will not be automatically numbered.

Whether or not automatic section numbering is more of a help or a nuisance is undecided.

Because the numbering applies globally to the the /doc URIs, they can sometimes look out of place. For example, pages which have only one header will have a superfluous section 1 number. To account for that, the site skin disables automatic section numbering in the following cases:

The page has fewer than 2 <H1> elements.
The page contains an element in the form
<span class='disable-section-numbers'></span>
If found, this element will be removed from the DOM, so it will not affect page layout.

Section numbering is disabled by adding the disable-section-numbers CSS class to the <body> element. The corresponding CSS rules are in fossil-doc.css.

Syntax Highlighting

assets/skin/header.txt loads highlight-sqlite3.min.js, which includes a copy/paste version of highlightjs and site-specific on-page-load JS code which installs syntax highlighting on code tags which are wrapped in a pre tag and a lang-XYZ class. i.e. to markdown code blocks in this form:

```XYZ
code goes here
```

highlight-sqlite3.min.js normally only needs to be edited when updating the local copy of highlightjs, taking care that the top part of that file includes a 100% pristine copy of the upstream highlightjs and the bottom section includes this site's related code.

None of the documentation specifically relies on any features of highlightjs, but fossil-doc.css may contain CSS classes which are specific to a given highlightjs version, so care must be taken when upgrading to a new major version of highlightjs.

JS/WASM Doc Maintenance