Skinning Fossil
February 28, 2023
fossil ui
and open http://localhost:8080/setup_skin.
Follow the steps including 'Initialize the draft', which copies the current active skin into the selected Draft container. After many cycles and the draft is Published.
Backup the files to version control by adding to the below and committing:
./skin
....
[the skin] does not "push" or "pull" like checked-in files. The skin is local to the repository. However, skins can be shared between repositories using the fossil config command.
From < https://fossil-scm.org/home/doc/trunk/www/customskin.md>
Skin Development Using A Local Text Editor
An alternative approach is to copy the five control files for your baseline skin into a temporary working directory (here called "./newskin") and then launch the fossil ui command with the "--skin ./newskin" option. If the argument to the --skin option contains a "/" character, then the five control files are read out of the directory named. You can then edit the control files in the ./newskin folder using you favorite text editor, and press "Reload" on your browser to see the effects.
From < https://fossil-scm.org/home/doc/trunk/www/customskin.md>
...suggest a different approach to editing skin CSS which has worked out well for me...
In the page's header HTML, immediately after the line which imports skin.css, add something like:
<link rel="stylesheet" href="#root/1U6VvCvHwq9n" type="text/css" />
And add the file path/to/skin-overrides.css to your repository.
When running in local fossil server or fossil ui mode, /doc/ckout will use the copy of that file which is checked out locally, meaning that you can use your CSS-aware tools to edit that file and see the changes in fossil each time you reload a page.
Skin development tricks
The /ext feature was a true godsend here. Specifically, it can serve static content and integrate certain file types (e.g. markdown) into the repo's skin. This allowed me to port the docs in a doc-specific repo so that the migration wouldn't clutter up the main repo's log with dozens upon dozens of doc-only commits, and yet still have the docs integrated with the main site.
When complete, the contents of the doc-specific repo were moved as-is into the main repo. Because of how the /ext integration works, my inter-doc links did not require any modification and links to in-repo resources, e.g /finfo/foo/bar.c, worked identically under both /ext and after importing the docs into the main repo.
Rather by accident, i just learned that using a path like this in the site header:
<link rel="stylesheet" href="#root/LcdaEonTM7ST"font-weight:bold;background:#DBE5F1">ckout/doc/highlightjs/hybrid.css" type="text/css" />(Note the reference to doc/ckout)
... actually works, even if there's no checkout. It apparently takes the trunk or the tip (not sure which) if there is no checkout. That simplifies my configuration by allowing me to always use ckout and get consistent results locally (where there is a checkout) and the remote (where there's not). This whole time I've been carefully using separate headers for the local and remote site. Sigh.