docs: rephrase the README opening

Makefile

@@ -49,16 +49,14 @@ ifneq ($(filter $(shell uname),FreeBSD NetBSD DragonFly),)
 endif
 endif
 
-all: lib$(LANGUAGE_NAME).a lib$(LANGUAGE_NAME).$(SOEXT) $(LANGUAGE_NAME).pc
+parser: parser/tumblr.$(SOEXT)
-
-# Neovim expects parser/<lang>.<soext> on its runtimepath. Build with
-# `make nvim-parser` after cloning so the drop-in runtime tree works.
-nvim-parser: parser/tumblr.$(SOEXT)
 
 parser/tumblr.$(SOEXT): $(PARSER) $(EXTRAS)
 	@mkdir -p parser
 	$(TS) build --output $@
 
+lib: lib$(LANGUAGE_NAME).a lib$(LANGUAGE_NAME).$(SOEXT) $(LANGUAGE_NAME).pc
+
 lib$(LANGUAGE_NAME).a: $(OBJS)
 	$(AR) $(ARFLAGS) $@ $^
 
@@ -86,7 +84,7 @@ $(SRC_DIR)/grammar.json: grammar.js
 $(PARSER): $(SRC_DIR)/grammar.json
 	$(TS) generate $^
 
-install: all
+install: lib
 	install -d '$(DESTDIR)$(DATADIR)'/tree-sitter/queries/tumblr '$(DESTDIR)$(INCLUDEDIR)'/tree_sitter '$(DESTDIR)$(PCLIBDIR)' '$(DESTDIR)$(LIBDIR)'
 	install -m644 bindings/c/tree_sitter/$(LANGUAGE_NAME).h '$(DESTDIR)$(INCLUDEDIR)'/tree_sitter/$(LANGUAGE_NAME).h
 	install -m644 $(LANGUAGE_NAME).pc '$(DESTDIR)$(PCLIBDIR)'/$(LANGUAGE_NAME).pc
@@ -120,4 +118,4 @@ clean:
 test:
 	$(TS) test
 
-.PHONY: all install uninstall clean test nvim-parser
+.PHONY: parser lib install uninstall clean test

README.md

@@ -0,0 +1,88 @@
+# tree-sitter-tumblr
+
+A [tree-sitter](https://tree-sitter.github.io/) grammar for [Tumblr
+theme](https://www.tumblr.com/docs/en/custom_themes) template syntax.
+The repository also ships filetype detection, queries, and the build
+glue Neovim needs, so you can install it directly as a plugin.
+
+The grammar recognises the structure of theme files (variables, block
+tags, attributes, `lang:` tags, prefixed forms, size suffixes) and
+treats everything else as opaque content. Surrounding HTML is parsed
+via injection, which in turn injects CSS into `<style>` and JS into
+`<script>` through HTML's own queries.
+
+## Install (Neovim)
+
+The parser binary lives at `parser/tumblr.so` and is gitignored, so
+every install path needs a build step that runs `make`.
+
+### lazy.nvim
+
+```lua
+{
+  "https://git.owall.dev/warg/tree-sitter-tumblr",
+  build = "make",
+}
+```
+
+### vim.pack
+
+```lua
+vim.api.nvim_create_autocmd("PackChanged", {
+  callback = function(ev)
+    if ev.data.spec.name ~= "tree-sitter-tumblr" then return end
+    if ev.data.kind == "install" or ev.data.kind == "update" then
+      vim.system({ "make" }, { cwd = ev.data.path }):wait()
+    end
+  end,
+})
+
+vim.pack.add({
+  { src = "https://git.owall.dev/warg/tree-sitter-tumblr" },
+})
+```
+
+### Manual
+
+```sh
+git clone https://git.owall.dev/warg/tree-sitter-tumblr /path/to/repo
+cd /path/to/repo && make
+```
+
+```lua
+vim.opt.runtimepath:append("/path/to/repo")
+```
+
+### Injections
+
+For HTML, CSS, and JS to highlight inside theme files, those parsers
+need to be on `runtimepath` too. With `nvim-treesitter`:
+
+```vim
+:TSInstall html css javascript
+```
+
+## Filetype detection
+
+Files are recognised as `tumblr` by extension or by double-extension:
+
+- `*.tumblr`
+- `*.tumblr.html` (the convention used by the `tumblr.vim` plugin)
+
+## Development
+
+```sh
+tree-sitter generate     # regenerate src/parser.c from grammar.js
+tree-sitter test         # run the test corpus under test/corpus/
+make                     # build parser/tumblr.so
+```
+
+The known-name lists in `queries/tumblr/highlights.scm` were extracted
+from the official Tumblr theme docs. They drive richer highlighting
+(`@variable.builtin`, `@function.builtin`) for documented names while
+unknown names still parse and highlight as generic captures.
+
+## License
+
+Apache-2.0. See `LICENSE` for the full text and `NOTICE` for
+third-party attributions.