# blog.bythewood.me

Personal blog, served by a single Rust axum binary. Self-contained: posts, templates, Vite-built static assets, and the binary all live here. Markdown content in `content/posts/`, no database.

## Features

- Markdown posts with YAML frontmatter (title, slug, date, publish_date, tags, description, cover_image)
- Server-rendered tag and year archives
- Server-rendered + live JSON search (`/search/` and `/search/live/`)
- Per-post PDF export via embedded Typst (no chromium subprocess)
- Per-post raw markdown download
- Dynamic OG image generation per post
- Single-binary deploy via `git push server master`

## Stack

| Concern         | Crate / Tool                 |
|-----------------|------------------------------|
| Web framework   | axum + tokio                 |
| Template engine | minijinja                    |
| Markdown        | comrak                       |
| PDF             | embedded Typst (no chromium) |
| Static assets   | Vite + Bun                   |

Crate selection rationale: axum is the most-pulled async framework, minijinja is the only Rust engine that accepts upstream Jinja2 syntax, comrak's `partial-formatter` story is the closest match to Mistune's renderer-override pattern.

## System dependencies

Local dev needs all of these on your `PATH`:

| Tool | Why | Version |
|---|---|---|
| `rustc` / `cargo` | Build the axum binary | 2021 edition, current stable is fine (1.70+) |
| `bun` | Frontend deps + Vite | 1.x |
| `make` | Run the dev/build targets | any |

The Docker build (see `Dockerfile`) reproduces this on `rust:alpine` + `alpine:3.23`. If you only care about Docker, you do not need any of the above on the host. Runtime image installs `font-jetbrains-mono`, `ttf-dejavu`, `ttf-liberation`, and `fontconfig` so the embedded Typst renderer can find body sans, mono, and fallback fonts.

## Quickstart

```sh
cp samplefiles/env.sample .env
make
```

`make` (alias `make run`) installs frontend deps if needed, then runs Vite watch and `cargo run` concurrently on port 8000. Visit http://localhost:8000.

## Configuration

All config comes from `.env` (loaded via `dotenvy`):

| Variable | Required | Purpose |
|---|---|---|
| `PORT` | no (default `8000`) | HTTP listen port |
| `BLOG_ROOT` | no | Override the project root (where `templates/`, `dist/`, and `content/` are read from) |

## Make targets

| Target | What it does |
|---|---|
| `make run` (default) | Vite watch + `cargo run` on port 8000 |
| `make build` | Vite assets + release binary (`target/release/blog`) |
| `make start` | Run the release binary (after `make build`) |
| `make bench` | `oha` load test sweep across the main routes. Compares against a Flask server on port 8002 (the original `blog.bythewood.me`) if running |
| `make push` | `git push` to every configured remote |
| `make clean` | Remove `target/`, `dist/`, and `frontend/node_modules/` |

There are no tests or linters configured.

## Layout

```
blog.bythewood.me/
├── Cargo.toml, Cargo.lock        # rust deps
├── Makefile, README.md, bench/   # top-level
├── src/                          # rust source
│   ├── main.rs       # tiny entry: server boot
│   ├── app.rs        # AppState + Router assembly
│   ├── render.rs     # render_html helper
│   ├── middleware.rs # request log
│   ├── routes/       # blog, post, search, seo, errors
│   ├── posts.rs      # frontmatter + post loading
│   ├── markdown.rs   # comrak custom renderer
│   ├── templates.rs  # minijinja env, url_for, vite_asset, Jinja2-compat formatter
│   └── pdf.rs        # embedded Typst renderer
├── templates/                    # jinja2 source (minijinja-compatible) + blog_post.typ
├── content/                      # markdown source
│   ├── posts/        # markdown posts with YAML frontmatter
│   └── images/       # served at /content/images/
├── frontend/                     # JS pipeline (package.json, vite.config.js, static_src/)
├── dist/                         # vite build output (gitignored, served at /static/)
├── target/                       # cargo build output (gitignored)
└── samplefiles/                  # Caddyfile.sample, env.sample, post-receive.sample
```

The binary reads `templates/`, `dist/`, and `content/` from the current working directory. Override with `BLOG_ROOT=<path>`.

## Deploy

Production runs on Docker. The standard flow is `git push server master` to a remote whose post-receive hook runs `docker compose up --build --detach`. Sample files in `samplefiles/`:

- `Caddyfile.sample`: reverse proxy with TLS
- `env.sample`: the `.env` shown above
- `post-receive.sample`: the git hook

See [CLAUDE.md](CLAUDE.md) for the full architecture rundown, route table, and PDF pipeline details.

## Caveats

- **Posts loaded once at startup.** Add a post, restart the process.