# tree-sitter-sisu

Tree-sitter grammar for **SiSU markup** (`.sst`, `.ssm`, `.ssi`),
covering both header dialects of the SiSU family:

- **Bespoke / original SiSU** headers: `@title:`, `@creator:`, with
  ` :sub-key:` continuation lines and `%` line comments throughout.
- **YAML / sisudoc-spine** headers: yaml mapping, with `#` line
  comments in the header and `%` line comments in the body.

The two body grammars are identical; only the header preamble
differs. A document picks one header dialect; mixing both inside
the same file is parseable but not idiomatic.

Provides structural syntax highlighting, folding, and text-object
queries for any editor that hosts a tree-sitter runtime: Neovim,
Emacs 29+ (`treesit`), Helix, Zed, and others.

## What this is for

- Editor / IDE syntax highlighting that respects nested inline
  markup, block bodies, and multi-line footnotes (cases where
  regex-based highlighters break down).
- Structural queries: jump heading to heading, fold a block body,
  select "inside a footnote" or "outside a code block", etc.
- A second implementation of the SiSU markup parser, useful as a
  cross-check on the production parser in
  [sisudoc-spine](https://git.sisudoc.org/projects/sisudoc-spine).

## Audience

Editor tooling maintainers and end users who want SiSU markup
support inside their editor. Not aimed at end-user document
authors directly; it is consumed via your editor's tree-sitter
integration.

## Relationship to spine and to original sisu

This grammar parses the input syntax shared by
[sisudoc-spine](https://git.sisudoc.org/projects/sisudoc-spine)
(yaml headers) and the original
[sisu](https://sisudoc.org/projects/sisu/) tool (bespoke headers).
Bodies are the same. Spine produces the canonical parse used for
output generation; this grammar provides editor-side parsing for
highlighting and navigation, and is kept in sync with the markup
rules of both tools. See
[`sisu-markup_tree-sitter.md`](sisu-markup_tree-sitter.md) for the
corpus-level test results and known limitations.

## Quickstart

### Neovim (via nvim-treesitter)

The simplest path is to use the Neovim drop-in shipped by spine
itself:

```sh
# clone sisudoc-spine
git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine

# add to runtime path
ln -s "$PWD/sisudoc-spine/sundry/editor-syntax-etc/nvim" \
      "$HOME/.config/nvim/pack/sisu/start/sisu-spine"
```

then in your `init.lua`:

```lua
require("sisu-spine").setup()
require("nvim-treesitter.configs").setup({
  ensure_installed = { "sisu" },
  highlight = { enable = true },
  fold      = { enable = true },
  indent    = { enable = true },
})
```

and `:TSInstall sisu` builds and registers this parser.

### Emacs 29+

```elisp
(add-to-list 'treesit-language-source-alist
  '(sisu "https://git.sisudoc.org/tools/tree-sitter-sisu"
         :source-dir "src"))
;; M-x treesit-install-language-grammar RET sisu RET
```

A complete major mode that uses this parser lives in spine's
`sundry/editor-syntax-etc/emacs/sisu-spine-ts-mode.el`.

### Build locally

```sh
nix-shell -p tree-sitter nodejs --run "tree-sitter generate"
nix-shell -p tree-sitter nodejs --run "tree-sitter test"
nix-shell -p tree-sitter nodejs --run "tree-sitter parse path/to/doc.sst"
```

## Documentation

- [`sisu-markup_tree-sitter.md`](sisu-markup_tree-sitter.md) -
  detailed notes on what the grammar parses, corpus test results,
  known limitations, and the rationale for grammar design choices.
- [`queries/`](queries/) - tree-sitter queries: `highlights.scm`,
  `folds.scm`, `textobjects.scm`, `indents.scm`, `injections.scm`.
- [`test/corpus/`](test/corpus/) - unit-test corpus.

## License

AGPL-3.0-or-later. See [`package.json`](package.json) and the
parent [sisudoc-spine](https://git.sisudoc.org/projects/sisudoc-spine)
project for full licence text.

## Repository

- **Canonical URL:** https://git.sisudoc.org/tools/tree-sitter-sisu
- **Clone:** `git clone --depth=1 git://git.sisudoc.org/tools/tree-sitter-sisu`

## Related projects

- [sisudoc-spine](https://git.sisudoc.org/projects/sisudoc-spine) -
  the SiSU spine document engine (D) that consumes this markup.
- [sisudoc-spine-samples](https://git.sisudoc.org/markup/sisudoc-spine-samples) -
  corpus of real SiSU documents this grammar is tested against.
- [ssp-reader](https://git.sisudoc.org/tools/ssp-reader) -
  reader for the `.ssp` document-abstraction text format that
  spine emits.