> ## Documentation Index
> Fetch the complete documentation index at: https://hitspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Editor Setup

> Configure syntax highlighting, snippets, and shell completions for hitspec.

## VSCode Extension

The official hitspec VSCode extension (v0.2.0) provides syntax highlighting, snippets, and language configuration for `.http` and `.hitspec` files.

### Features

* Full syntax highlighting via TextMate grammar
* 46 code snippets covering requests, assertions, captures, annotations, blocks, and built-in functions
* Comment toggling (`#`)
* Bracket matching and auto-closing for `{}`, `[]`, `()`, `""`, `''`, `{{}}`, and `>>>` / `<<<`
* Code folding for request separators (`###`) and assertion blocks

### Syntax Highlighting

The TextMate grammar highlights these elements:

* **HTTP methods** -- GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE, CONNECT, WS
* **Request separators** -- `###` lines
* **Annotations** -- `@name`, `@tags`, `@auth`, `@depends`, `@if`, `@unless`, `@import`, `@stress.*`, `@contract.*`, and others
* **Headers** -- key-value pairs like `Content-Type: application/json`
* **Assertion blocks** (`>>>` / `<<<`) -- `expect` keyword, comparison operators (`==`, `!=`, `>`, `<`, `>=`, `<=`), matchers (`contains`, `matches`, `exists`, `type`, `schema`, `snapshot`, etc.), and subjects (`status`, `body`, `header`, `duration`)
* **Typed blocks** -- `>>>capture`, `>>>graphql`, `>>>db`, `>>>shell`, `>>>mock`, `>>>multipart`, `>>>variables`
* **Variable interpolation** -- `{{variable}}`
* **Built-in functions** -- `$uuid()`, `$timestamp()`, `$env()`, `$random()`, and others
* **File includes** -- `< ./path/to/file`
* **Query parameters** -- `? key = value` and `& key = value`
* **Strings, numbers, booleans, null**

### Installation

<Steps>
  <Step title="Build the extension">
    ```bash theme={null}
    cd apps/vscode
    npm install
    npm run package
    ```

    This generates a `.vsix` file in the `apps/vscode` directory.
  </Step>

  <Step title="Install in VSCode">
    1. Open the Command Palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Windows/Linux)
    2. Run **Extensions: Install from VSIX...**
    3. Select the generated `.vsix` file
  </Step>
</Steps>

<Note>
  The extension is declarative-only -- no IntelliSense or autocomplete beyond snippets. The [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) extension is an alternative for basic `.http` support, but it does not highlight assertion blocks, typed blocks, or annotations.
</Note>

## Neovim

The hitspec Neovim plugin provides syntax highlighting, filetype detection, buffer settings, and optional LuaSnip snippets for `.http` and `.hitspec` files.

### Features

* Syntax highlighting via Vim syntax file (not TreeSitter)
* Filetype detection for `.http` and `.hitspec`
* Buffer settings: `commentstring` (`# %s`), 2-space indentation
* 57 LuaSnip snippets (optional) covering HTTP methods, assertion/capture blocks, annotations, built-in functions, and a complete request template

### Installation

<Tabs>
  <Tab title="lazy.nvim">
    ```lua theme={null}
    {
      "abdul-hamid-achik/hitspec",
      ft = { "http", "hitspec" },
      config = function()
        require("hitspec").setup()
      end,
    }
    ```
  </Tab>

  <Tab title="packer.nvim">
    ```lua theme={null}
    use {
      "abdul-hamid-achik/hitspec",
      config = function()
        require("hitspec").setup()
      end,
    }
    ```
  </Tab>

  <Tab title="Manual">
    Copy the plugin directories to your Neovim config:

    ```bash theme={null}
    cp -r apps/nvim/ftdetect ~/.config/nvim/
    cp -r apps/nvim/syntax ~/.config/nvim/
    cp -r apps/nvim/ftplugin ~/.config/nvim/
    cp -r apps/nvim/lua ~/.config/nvim/
    ```

    Then add to your `init.lua`:

    ```lua theme={null}
    require("hitspec").setup()
    ```
  </Tab>
</Tabs>

<Tip>
  Snippets require [LuaSnip](https://github.com/L3MON4D3/LuaSnip). Call `require("hitspec").setup()` in your config to register them. If LuaSnip is not installed, snippets are silently skipped.
</Tip>

## Shell Completions

hitspec can generate completion scripts for your shell, giving you tab completion for commands and flags.

<CodeGroup>
  ```bash Bash theme={null}
  hitspec completion bash > /etc/bash_completion.d/hitspec
  ```

  ```bash Zsh theme={null}
  hitspec completion zsh > "${fpath[1]}/_hitspec"
  ```

  ```bash Fish theme={null}
  hitspec completion fish > ~/.config/fish/completions/hitspec.fish
  ```

  ```powershell PowerShell theme={null}
  hitspec completion powershell > hitspec.ps1
  ```
</CodeGroup>

After installing completions, restart your shell or source the completion file for changes to take effect.

<Tip>
  On macOS with Homebrew, Bash completions are typically loaded from `/opt/homebrew/etc/bash_completion.d/`. For Zsh, you may need to add the completions directory to your `fpath` in `~/.zshrc` before `compinit` is called.
</Tip>