From 1875efe41e188ba6139863a408bada802c3116ee Mon Sep 17 00:00:00 2001
From: Oscar Wallberg <oscar.wallberg@outlook.com>
Date: Sun, 17 May 2026 06:34:04 +0200
Subject: [PATCH] docs: add README with install and build notes

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

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2e8011b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,87 @@
+# 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,
+packaged as a drop-in Neovim runtime tree.
+
+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                     # rebuild parser/tumblr.so for Neovim
+```
+
+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.