orca/docs/reference/plugin-syntax.md

Plugin syntax highlighting

A plugin adds highlighting for a language through contributes.syntaxes in orca-plugin.json:

{
  "id": "typst",
  "title": "Typst",
  "scopeName": "source.typst",
  "path": "syntaxes/typst.tmLanguage.json",
  "configuration": "syntaxes/language-configuration.json",
  "extensions": [".typ"],
  "filenames": []
}

• path is a TextMate grammar in JSON (at most 1 MiB) whose scopeName matches the entry. Keys the TextMate engine does not use are dropped.
• include may name #repository entries, $self, $base, or another syntaxes scope in the same plugin; those must resolve when the plugin is approved, or its card shows the error. An include of a scope outside the plugin (for example an embedded source.js) is allowed but resolves to nothing, so that region stays plain.
• configuration (optional, at most 64 KiB) sets comment markers, brackets, auto-closing and surrounding pairs. Every marker is printable text on one line. Auto-closing and surrounding pairs are at most 8 characters, because the editor types them as you type. Comment markers and brackets can be up to 128. validate:plugin refuses an entry that breaks these limits; Orca skips just that entry and loads the rest. Without autoClosingPairs, Orca auto-closes only the brackets that fit in 8 characters.
• A plugin can contribute up to 16 syntaxes. Scope names must be unique within the plugin.

How Orca uses it

• While a plugin is enabled, its syntax colors every file whose name or extension it declares, replacing Orca's own guess for that file. For example, a MATLAB plugin that claims .m wins over Orca's Objective-C, an OCaml plugin that claims .ml wins over F#, a Julia plugin wins over Orca's basic Julia colors, and a Haskell or Erlang plugin colors .hs or .erl files that Orca maps but has no grammar for.
• The exception is a file Orca opens as TypeScript, JavaScript, JSON, CSS, SCSS, Less, HTML or Markdown: those keep Orca's language, because it also drives completions, diagnostics, or Markdown features that a plugin grammar would turn off. JSP (.jsp, .jspf) is not covered by this exception; Orca shows it as HTML only until a real grammar is available.
• When several enabled syntaxes claim a file, an exact file name wins over an extension, a longer extension wins over a shorter one, and an exact tie goes to the lower syntax id (plugin:...), so the winner does not depend on load order. There is no per-file language picker yet, so a plugin that claims a broad extension such as .txt highlights every such file while it is enabled; disable the plugin to get Orca's own colors back.
• Grammars load when a matching file opens, compile once in a worker, and stay warm while you type. Each line has the same limits as Orca's own grammars (1,000 characters, 50 ms); from a line that exceeds them, the rest of the file stays plain.
• Highlighting is applied as Monaco semantic tokens, so while a new pass runs the previous colors stay in place, shifted by your edits.
• A worker that stops reporting progress for 2 seconds or crashes is terminated, the language stays plain, and the plugin card says highlighting stopped.
• Files over 500,000 characters or 20,000 lines stay plain.
• Highlighting follows the plugin live: enabling, updating or disabling it re-highlights open files without a reload.