Compatibility and Direct LSP Integration

Supported path

The VS Code extension packages the server, handles activation, and is the recommended setup for most users.

The extension path should be boring in the best way: install, open a vault or configured Markdown project, wait for ready status, and start using completion or diagnostics. Current releases use a bundled JavaScript server module at `server/main.js` instead of platform-specific native server payloads.

Install the server from npm

For direct LSP use, install the language server package with npm in the environment where your editor client will launch it. This does not install the VS Code extension or configure an editor by itself.

Use a local project install when you want the server pinned with the workspace, or use `npx` for a quick test. Your client still needs to start the command over stdio and send a usable `rootUri`.

npm install --save-dev flavor-grenade-lsp
npx flavor-grenade-lsp

Direct LSP clients

Direct clients must launch the server, provide a usable file `rootUri`, send configuration, and handle file watching.

The root URI is not cosmetic. It decides whether Flavor Grenade can find `.obsidian/` or a Flavor Grenade project config marker, build a vault index, confine local paths, and provide vault-wide features such as note completion, references, and rename.

If your client sends workspace configuration after initialize, use the same public setting names as the VS Code extension:

Direct server options such as `linkStyle`, `completionCandidates`, `diagnosticsSuppress`, and the project-config read cap `projectConfigMaxBytes` belong in `initializationOptions`. Flavor and structured-profile state belongs in `workspace/didChangeConfiguration` unless project configuration or Auto Detect can decide it. A client may also send `projectConfigMaxBytes` in `workspace/didChangeConfiguration` when exposing a live settings UI.

For a project-level override, put a Flavor Grenade project config file at the project root. TOML is still supported and is checked first:

JSONC and YAML use the same logical shape:

Use `structured_profiles = "none"` or `structured_profiles: none` when a repository should not apply structured-document behavior.

{
  "rootUri": "file:///Users/alex/MyVault",
  "workspaceFolders": [
    { "uri": "file:///Users/alex/MyVault", "name": "MyVault" }
  ],
  "initializationOptions": {
    "linkStyle": "file-stem",
    "completionCandidates": 50,
    "diagnosticsSuppress": [],
    "projectConfigMaxBytes": 8192
  },
  "capabilities": {
    "workspace": {
      "configuration": true,
      "didChangeWatchedFiles": { "dynamicRegistration": true }
    }
  }
}

{
  "settings": {
    "flavorGrenade": {
      "markdownFlavor": "auto",
      "markdownStructuredProfiles": ["madr"],
      "projectConfigMaxBytes": 8192
    }
  }
}

[core.markdown]
flavor = "gfm"
structured_profiles = ["keep-a-changelog"]

{
  "core": {
    "markdown": {
      "flavor": "commonmark",
      "structured_profiles": "auto",
      "overrides": [
        { "path": "docs/api", "flavor": "pandoc" },
        { "path": "docs/decisions", "flavor": "commonmark", "structured_profiles": ["madr"] }
      ]
    }
  }
}

core:
  markdown:
    flavor: commonmark
    structured_profiles: auto
    overrides:
      - path: docs/api
        flavor: pandoc
      - path: docs/decisions
        flavor: commonmark
        structured_profiles: [madr]

Initialize shape

A minimal direct-client flow is:

The server accepts normal LSP initialize parameters. Flavor-specific initialization data is not read from initialize options; direct clients with a selector UI should send explicit state with `workspace/didChangeConfiguration`.

spawn: npx flavor-grenade-lsp
send: initialize with file rootUri and workspaceFolders
send: initialized
watch: Markdown files, .obsidian/, and Flavor Grenade project config markers
send: didOpen/didChange/didClose for open documents

{
  "processId": 12345,
  "rootUri": "file:///Users/alex/DocsProject",
  "workspaceFolders": [
    { "uri": "file:///Users/alex/DocsProject", "name": "DocsProject" }
  ]
}

Compatibility boundary

The server speaks LSP, but non-VS-Code clients may need custom transport and configuration work.

If a direct client can launch a Node-based stdio language server and send normal LSP initialize parameters, it has the right starting point. If it cannot provide a stable file root, expect single-file behavior and CommonMark fallback rather than full vault behavior.

Practical check

A direct-client example should include both the command that launches the npm-installed server and the initialize data the client sends afterward. Installing the package is only half the work; the client still owns stdio transport, workspace folders, root URI selection, configuration, file watching, and restart behavior.

Keep the VS Code article linked from here because it is the supported path for most readers. Direct integration is for editor maintainers, advanced users, and test harnesses that already understand LSP wiring.