#+title: org-garden

An [[https://orgmode.org/][org-roam]] to static website publishing pipeline. Converts =.org= notes into a rendered site using Emacs/[[https://ox-hugo.scripter.co/][ox-hugo]] for export and [[https://quartz.jzhao.xyz/][Quartz 4]] for site generation.

* Usage

#+begin_example
org-garden serve  <notes-dir>   # dev server with live reload
org-garden build  <notes-dir>   # production static build
org-garden export <notes-dir>   # org -> markdown only
#+end_example

* Running with Nix (recommended)

#+begin_src sh
nix run . -- serve <notes-dir>
nix run . -- build <notes-dir>
#+end_src

* Running with Mix

#+begin_src sh
mix deps.get
mix escript.build
./org_garden serve <notes-dir>
#+end_src

Requires =QUARTZ_PATH= to point to a Quartz install with =node_modules= for =serve= and =build= commands.

* NixOS Service

A NixOS module is provided for running org-garden as a systemd service:

#+begin_src nix
{
  inputs.org-garden.url = "github:ignacio.ballesteros/org-garden";

  outputs = { self, nixpkgs, org-garden }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [
        org-garden.nixosModules.default
        {
          services.org-garden = {
            enable = true;
            package = org-garden.packages.x86_64-linux.default;
            notesDir = /path/to/notes;
            port = 8080;
          };
        }
      ];
    };
  };
}
#+end_src

* Health Checks

When running in serve mode, health endpoints are available on port 9090:

- =GET /health/live= — liveness probe (always 200)
- =GET /health/ready= — readiness probe (200 if all components ready)
- =GET /health= — JSON status of all components

* Environment Variables

| Variable       | Default                   | Description                      |
|----------------+---------------------------+----------------------------------|
| =QUARTZ_PATH=  | (required for serve/build)| Path to Quartz installation      |
| =NODE_PATH=    | =node=                    | Node.js executable               |
| =NOTES_DIR=    | (cli arg)                 | Source notes directory           |
| =OUTPUT_DIR=   | =.=                       | Output base directory            |
| =ZOTERO_URL=   | =http://localhost:23119=  | Zotero Better BibTeX URL         |
| =BIBTEX_FILE=  | (none)                    | Fallback BibTeX file             |
| =CITATION_MODE=| =warn=                    | =silent=, =warn=, or =strict=    |
| =PORT=         | =8080=                    | HTTP server port                 |
| =WS_PORT=      | =3001=                    | WebSocket hot reload port        |
| =HEALTH_PORT=  | =9090=                    | Health check endpoint port       |