87 lines
3.4 KiB
Markdown
87 lines
3.4 KiB
Markdown
# levineuwirth.org
|
|
|
|
Personal site of Levi Neuwirth — essays, blog posts, poetry, fiction, and music.
|
|
Built with [Hakyll](https://jaspervdj.be/hakyll/) and [Pandoc](https://pandoc.org/),
|
|
with a custom build system in `build/` and a Haskell + JS + Python toolchain.
|
|
|
|
## Quickstart
|
|
|
|
```sh
|
|
make build # one-shot production build into _site/
|
|
make dev # dev build (drafts visible) + local server on :8000
|
|
make watch # cabal-watch rebuild (drafts visible)
|
|
make clean # cabal run site -- clean
|
|
make deploy # clean → build → sign → push → rsync to VPS
|
|
```
|
|
|
|
`make build` always runs `make clean` implicitly when invoked from `make deploy`.
|
|
For day-to-day work, prefer `make dev` (which serves the site on
|
|
`http://localhost:8000`) or `make watch` (rebuilds on save without a server).
|
|
|
|
**Run `make build` any time you add or replace binary assets** (JPEG/PNG
|
|
figures, PDFs, music assets). `make dev` and `make watch` skip the
|
|
`convert-images.sh` / `pdf-thumbs` preprocessing steps, so a fresh JPEG
|
|
will have no `.webp` companion and a fresh PDF will have no thumbnail
|
|
until a full `make build` regenerates them. Once the companions exist
|
|
they survive subsequent `make dev` runs.
|
|
|
|
## Optional features
|
|
|
|
- **Similar-links and embeddings.** `tools/embed.py` precomputes
|
|
page-level embeddings for the "Related" block. To enable:
|
|
|
|
```sh
|
|
uv sync # creates .venv with sentence-transformers, faiss-cpu
|
|
```
|
|
|
|
The build silently skips embedding when `.venv` is absent.
|
|
|
|
- **Client-side semantic search.** Downloads a quantized ONNX model
|
|
used by `static/js/semantic-search.js` (run once; files are gitignored):
|
|
|
|
```sh
|
|
make download-model
|
|
```
|
|
|
|
- **Image conversion.** `make build` calls `tools/convert-images.sh` to
|
|
produce `.webp` companions next to every JPEG/PNG. Requires `cwebp`
|
|
(`libwebp` on Arch, `webp` on Debian/Ubuntu).
|
|
|
|
- **PDF thumbnails.** `make pdf-thumbs` generates first-page thumbnails
|
|
for PDFs in `static/papers/` using `pdftoppm` (`poppler` on Arch,
|
|
`poppler-utils` on Debian/Ubuntu). Skipped silently when missing.
|
|
|
|
## Configuration
|
|
|
|
`.env` (gitignored, copy from `.env.example`) holds the GitHub PAT and
|
|
the VPS rsync target consumed by `make deploy`. Never commit it.
|
|
|
|
## Repository layout
|
|
|
|
- `build/` — Haskell build system (Hakyll rules, Pandoc filters, contexts).
|
|
See `build/Filters/` for the Pandoc AST transforms (sidenotes,
|
|
wikilinks, transclusion, score embedding, viz, …).
|
|
- `content/` — authored Markdown (essays, blog, poetry, fiction, music).
|
|
- `templates/` — Hakyll/Pandoc HTML templates.
|
|
- `static/` — CSS, JS, fonts, images, vendored PDF.js.
|
|
- `tools/` — Python tooling (embeddings, importers) and shell scripts.
|
|
- `data/` — generated and source data (commonplace.yaml, annotations.json,
|
|
bibliographies, similar-links.json).
|
|
- `paper/` — LaTeX source for in-progress academic papers.
|
|
- `spec.md` — full architectural notes and design intent.
|
|
|
|
## Architecture pointers
|
|
|
|
- `build/Site.hs` is the Hakyll rules entry point.
|
|
- `build/Patterns.hs` defines canonical content patterns shared by
|
|
Backlinks, Authors, Tags, and Site.
|
|
- `build/Compilers.hs` wires the Pandoc filter chain into Hakyll.
|
|
- `build/Filters/Images.hs` does WebP `<picture>` wrapping; requires
|
|
the `.webp` companions produced by `tools/convert-images.sh`.
|
|
|
|
For deeper architectural detail, see `spec.md`.
|
|
|
|
## License
|
|
|
|
See `LICENSE`.
|