utensil.tngl.sh
Utensil's Zettelkasten-style forest of evergreen notes on math and tech.
utensil.tngl.sh/forest/
3.8 kB
126 lines
1# Utensil's Forest
2
3[](https://github.com/utensil/ocaml-forester)
4
5My Zettelkasten-style forest of evergreen notes on math and tech: https://utensil.github.io/forest/
6
7## Development
8
9[](https://bun.sh) [](https://lightningcss.com) [](https://biomejs.dev)
10
11### Initial Setup
12
13This forest is initialized with the following command:
14
15```bash
16brew install opam bubblewrap watchexec
17opam init --auto-setup --yes
18opam update --yes
19opam install forester --yes
20forester --version
21
22cd ~/projects/
23git init forest
24cd forest
25git pull https://git.sr.ht/~jonsterling/forest-template
26
27git remote add origin https://github.com/utensil/forest.git
28git branch -M main
29git push -u origin main
30```
31
32To initialize `theme` directory, review and run `./thm.sh`.
33
34Add a `forest.toml`, then:
35
36```bash
37forester new --dest=trees --prefix=uts
38```
39### How to run
40
41Run `./dev.sh` to watch the modified files and serve them to be browsed.
42
43Then open `http://localhost:1314` in your browser.
44
45`./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.
46
47### Trouble Shooting
48
49If something goes wrong, check out https://github.com/jonsterling/forest .
50
51Locally I will
52
53```bash
54git clone https://git.sr.ht/~jonsterling/public-trees jms
55```
56so I can check Jon Sterling's use of Forester conveniently.
57
58### Additional dependencies
59
60The following should be all taken cared of by `./prep.sh`, at least on Mac.
61
62#### LaTeX
63
64In order to use `dvisvgm` required by forester to compile LaTeX to SVG, I have to:
65
66```bash
67brew uninstall texlive
68brew install --cask mactex
69```
70
71See https://tex.stackexchange.com/a/676179/75671 for why.
72
73#### `just`
74
75I'm using [just](https://github.com/casey/just) as a task runner, ideally one can just install `just` then install all deps and run all the task via `just`.
76
77`just` is useful for registering many few-liner tasks, maintaining sanity for file path handling, environment variable setting,
78task dependency declaration, and parameter passing.
79
80More complex tasks are still done by Bash and Python scripts.
81
82To install `just`, run
83
84```bash
85curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
86```
87
88To check all available tasks, run
89
90```bash
91just --list
92```
93
94#### Bibliography
95
96I use a combination of `pandoc` and a Python script to generate Forester-style bibliography tree files from a few `.bib` files.
97
98#### `bun`
99
100I'm experimenting with authoring `js/ts/jsx/tsx` using [bun](https://bun.sh/), so I also need to run
101
102```bash
103curl -fsSL https://bun.sh/install | bash
104# source ~/.bashrc
105source ~/.zshrc
106```
107
108to install `bun`.
109
110Rendering `js/ts/jsx/tsx` are also done by `dev.sh` in development with watch support or `build.sh` in CI. Manually this is:
111
112```bash
113bun build ./bun/<file-name> --outdir output
114```
115
116To 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`.
117
118#### WASM
119
120I'm also experimenting with WebAssembly, and some of the JS/TS code will rely on WASM.
121
122As long as one has working `bun` and [rustup](https://rustup.rs/), 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.
123
124## License
125
126See [REUSE.md](REUSE.md) for details.