@staticbolt/lsp 1.0.0-beta.29 → 1.0.0-beta.31

package/README.md

@@ -1 +1,32 @@
 # Staticbolt lsp
+
+The language server for Staticbolt projects, built on [Volar](https://volarjs.dev). It serves HTML and markdown files:
+
+- Completion and hover for the tags and attributes the project's plugins declare (`lspHtmlData`), with path completion that knows the project's aliases.
+- Links resolved the way the build resolves them.
+- The problems plugins find (`lspValidate`).
+- The code plugins embed in HTML (`lspEmbeddedLanguages`), such as `<script type="application/x-typescript">` bodies and the layout plugin's `{{ placeholders }}`, through TypeScript: completion, hover, diagnostics, semantic tokens, definitions, references, rename, folding, signature help, inlay hints and code actions.
+
+## Plugin API
+
+A plugin takes part through three optional hooks, each given the document already parsed (`DocumentInfo`: the text, every element with its attributes and ranges, `select(...tags)`, `textOf(range)` and `resolve(source)` through the project's aliases):
+
+- `lspHtmlData()` — the tags and attributes it adds, in the [VS Code custom data](https://github.com/microsoft/vscode-html-languageservice/blob/main/docs/customData.md) format.
+- `lspValidate(document, report)` — the problems it finds, reported at an element, an attribute or a range.
+- `lspEmbeddedLanguages()` — the code it embeds: a `filter` for the files that carry it, `findRegions(document)` for where it sits, an optional `prelude` declaring what the code can see, and `isColouredByEditor` when the editor's grammar already colours the regions. Regions are claimed in config order, so a plugin that knows a script better than the core HTML plugin, last in the config, simply claims it first.
+
+## TypeScript
+
+The server runs TypeScript's API in process, so it needs a TypeScript that ships one (6.x; the native 7 builds do not). It looks, in order, at:
+
+1. `initializationOptions.typescript.tsdk` — the directory holding `typescript.js`, `node_modules/typescript/lib` say. The VS Code extension passes VS Code's own TypeScript here unless `typescript.tsdk` is set.
+2. A `--tsdk=<directory>` argument.
+3. The nearest `node_modules/typescript/lib` above the working directory that has an API.
+
+## Running
+
+```sh
+node node_modules/@staticbolt/lsp/lib/index.mjs --stdio
+```
+
+Editors find the server through the `@staticbolt/lsp` package installed in the project.