Utensil's Forest

My Zettelkasten-style forest of evergreen notes on math and tech: 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.

Additional dependencies

The following should be all taken cared of by ./prep.sh, at least on Mac.

LaTeX

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.

just

I'm using 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

Bibliography

I use a combination of pandoc and a Python script to generate Forester-style bibliography tree files from a few .bib files.

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.

CI and UTS_DEV=1 builds use working bun and rustup to build the pinned WASM packages. A clean Jujutsu or Git worktree reuses matching generated packages and the Base Theme asset from the primary Forest checkout when they are available. If no matching local cache exists, prime the primary checkout with UTS_DEV=1 just build; the worktree build then fails early with that command when the cache is missing.

License

See REUSE.md for details.