Utensil's Forest

https://utensil.github.io/forest/

Development

Initial Setup

This forest is initialized with the following command:

brew install opam bubblewrap watchexec
opam init --auto-setup --yes
opam update --yes
opam install forester --yes
forester --version

cd ~/projects/
git init forest
cd forest
git pull https://git.sr.ht/~jonsterling/forest-template

git remote add origin https://github.com/utensil/forest.git
git branch -M main
git push -u origin main

To initialize theme directory, review and run ./thm.sh.

Add a forest.toml, then:

forester new --dest=trees --prefix=uts

How to run

Run ./dev.sh to watch the modified files and serve them to be browsed.

Then open http://localhost:1314 in your browser.

./dev.sh internally run ./build.sh to build the forest and its dependencies. ./build.sh is also used in CI, check out .github/workflows/gh-pages.yml for more details.

Trouble Shooting

If something goes wrong, check out https://github.com/jonsterling/forest .

Locally I will

git clone https://git.sr.ht/~jonsterling/public-trees jms

so I can check Jon Sterling's use of Forester conveniently.

In order to use dvisvgm required by forester to compile LaTeX to SVG, I have to:

brew uninstall texlive
brew install --cask mactex

See https://tex.stackexchange.com/a/676179/75671 for why.

Experimental features

just

I'm experimenting with just as a task runner, ideally one can just install just then install all deps and run all the task via just.

just is useful for registering many few-liner tasks, maintaining sanity for file path handling, environment variable setting, task dependency declaration, and parameter passing.

More complex tasks are still done by Bash and Python scripts.

To install just, run

curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin

To check all available tasks, run

just --list

To add aliases to the current shell, run

source ./alias.sh

bun

I'm experimenting with authoring js/ts/jsx/tsx using bun, so I also need to run

curl -fsSL https://bun.sh/install | bash
# source ~/.bashrc
source ~/.zshrc

to install bun.

Rendering js/ts/jsx/tsx are also done by dev.sh in development with watch support or build.sh in CI. Manually this is:

bun build ./bun/<file-name> --outdir output

To use any package, just figure out the package name from the import and run bun add <package-name>, package.json will be updated by bun.

WASM

I'm also experimenting with WebAssembly, and some of the JS/TS code will rely on WASM.

As long as one has working bun and rustup, the build.sh should take care of the rest. It also silently skips the WASM build if failed, to ensure the rest of the site can still be built.

License

See REUSE.md for details.