From 8198c5271003a22349d2cc22f6fa8e173cbc2341 Mon Sep 17 00:00:00 2001
From: eltrac <hi@eltr.ac>
Date: Fri, 28 Aug 2026 23:17:52 +0800
Subject: docs: add README.md

---
 README.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..356bd7f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,35 @@
+> [!warning]
+> This project is still under active development. Features are incomplete and buggy. Do not use in production.
+
+# tempest 
+
+Convert `.lisp` files to `.html` templates using [spinneret](https://github.com/ruricolist/spinneret), meant for simple templating like [Hugo](https://gohugo.io/) themes and plain HTML pages.
+
+## Usage 
+
+First, build from source. Make sure you have [SBCL](https://www.sbcl.org/), [Quicklisp](https://www.quicklisp.org/beta/) and [make](https://www.gnu.org/software/make/) set up.
+
+```shell
+make build 
+```
+
+Then a binary named `tempest` will be produced. Run it. 
+
+```shell 
+# the following command all accept multiple arguments
+./tempest build <dir>   # build all tempest .lisp in dir
+./tempest build-each <file>  # build each specified tempest .lisp 
+# watch, for now, only accpets one
+./tempest watch <dir>   # watch for changes and build modified or created .lisp 
+```
+
+Only `.lisp` file whose content starts with `;;;; TEMPEST` will be built.
+
+# Todos
+
+- [ ] Integrate [Parenscript](https://parenscript.common-lisp.dev/), compile `.lisp` to `.js` or `<script>` embedded in `.html`.
+- [ ] `.lisp` to `.css`.
+- [ ] Parse metadata defined in header comments, e.g. `;;;; OUT = ...` specifies a destination.
+- [ ] Add macros for writing [Go templates](https://pkg.go.dev/text/template), e.g. `(mu ...)` to `{{ ... }}`, `(mu-if ...)` to `{{ if }}...{{ end }}`...
+- [ ] Add macros for writing [Vue](https://vuejs.org/) templates
+
-- 
cgit v1.2.3