hx-lsp

April 28, 2026 · View on GitHub

English

一个为 Helix Editor 提供代码片段（snippets）和代码操作（Code Actions）的 LSP 工具。

功能特性

LSP 命令

  • reload snippets - 重新加载代码片段配置
  • reload actions - 重新加载代码操作配置

核心功能

功能说明相关 PR
代码补全支持 VSCode 格式的代码片段helix#9801
代码操作自定义 Shell 脚本操作-
文档颜色识别并显示 CSS/Bevy 颜色helix#12308
单词风格转换下划线、驼峰、大驼峰转换-

Markdown 专属功能

  • 表格格式化 - 自动对齐表格列（选择区域需包含表头分隔符 |:-）
  • 文本样式 - 粗体、斜体、删除线
  • 列表转换 - 有序列表、无序列表、任务列表

安装

从 crates.io 安装（推荐）

cargo install --force hx-lsp

从源码编译

git clone https://github.com/erasin/hx-lsp.git
cd hx-lsp
cargo install --path .

配置

hx-lsp 通过 Helix 的 languages.toml 文件进行配置，使用 TOML 格式。

Helix 语言配置

Helix 使用 languages.toml 配置 LSP 和语言服务器：

  • 全局配置：$XDG_CONFIG_HOME/helix/languages.toml
  • 项目配置：WORKSPACE_ROOT/.helix/languages.toml

关于 WORKSPACE_ROOT：从 Helix 提供的 initialize 请求中的 rootPath 获取。当存在多层级的 .helix 目录时，会读取最近的一层。

配置示例

为 Markdown 添加 hx-lsp 支持并自定义配置：

[language-server.hx-lsp]
command = "hx-lsp"

[language-server.hx-lsp.config]
markdown = false              # 禁用 markdown 功能
documentColor = true         # 启用文档颜色

[[language]]
name = "markdown"
language-servers = ["hx-lsp"]

[[language]]
name = "html"
language-servers = [
  "vscode-html-language-server",
  "hx-lsp"
]

关于 language id：参考 helix/languages.toml 和 Helix Wiki。

Helix 支持使用 only-features 和 except-features 过滤 LSP 功能，hx-lsp 支持以下功能：

  • completion - 代码补全
  • code-action - 代码操作
  • document-colors - 文档颜色

LSP 配置协议

hx-lsp 支持通过 LSP 协议动态配置。配置可通过以下方式传递：

  1. language-server.hx-lsp.config 在 languages.toml 中（TOML 格式）
  2. initializationOptions 在服务器初始化时（JSON 格式）

配置选项

选项类型默认值说明
markdownbooleantrue启用/禁用 markdown 语言功能
documentColorbooleantrue启用/禁用文档颜色提供者

配置格式

TOML 格式（在 languages.toml 中）：

[language-server.hx-lsp.config]
markdown = false
documentColor = true

JSON 格式（initializationOptions）：

{ "markdown": true, "documentColor": true }

或嵌套格式：

{
  "settings": {
    "markdown": true,
    "documentColor": true
  }
}

配置文件

配置文件使用 jsonc 格式（支持注释，但不支持尾随逗号）。

支持的注释格式：// ...、/* ... */、# ...

文件加载路径

代码片段（Snippets）：

  • 全局：$XDG_CONFIG_HOME/helix/snippets/
  • 项目：WORKSPACE_ROOT/.helix/snippets/

代码操作（Actions）：

  • 全局：$XDG_CONFIG_HOME/helix/actions/
  • 项目：WORKSPACE_ROOT/.helix/actions/

当 LSP 收到 textDocument/didOpen 请求时，会自动加载对应语言的配置文件。

使用 Helix 命令 :lsp-workspace-command 可以唤起命令选择器，手动重载 snippets 或 actions。

代码片段（Snippets）

hx-lsp 兼容 VSCode Snippets 格式。

文件命名规则

  • 全局片段：{name}.code-snippets
  • 语言专属：{language_id}.json
snippets/
├── global.code-snippets    # 全局代码片段
├── html.json              # HTML 代码片段
└── markdown.json          # Markdown 代码片段

Snippet 格式

字段类型说明
prefixString 或 String[]触发补全的关键词
bodyString 或 String[]代码片段内容
descriptionString 或 String[]描述信息（可选）

示例

{
  "mdbookNote": {
    "prefix": "mdbookNote",
    "body": [
      "```admonish note ${1:title=\"\$2\"}",
      "${3:content}",
      "```"
    ],
    "description": "mdbook admonish note"
  },

  "mdbookBob": {
    "prefix": "mdbookBob",
    "body": "```svgbob\n\$1\n```",
    "description": "mdbook svgbob"
  },

  "dir": {
    "prefix": "dir",
    "body": [
      "TM_FILENAME: $TM_FILENAME",
      "TM_FILENAME_BASE: $TM_FILENAME_BASE",
      "TM_DIRECTORY: $TM_DIRECTORY",
      "TM_FILEPATH: ${TM_FILEPATH}",
      "RELATIVE_FILEPATH: $RELATIVE_FILEPATH",
      "WORKSPACE_NAME: $WORKSPACE_NAME",
      "WORKSPACE_FOLDER: $WORKSPACE_FOLDER"
    ],
    "description": "显示当前文件路径信息"
  }
}

代码操作（Actions）

Actions 允许根据条件执行 Shell 脚本，并将输出结果插入到编辑器中。

actions/
├── html.json
└── markdown.json

Action 格式

字段类型说明
titleString在 Helix 中显示的标题
filterString 或 String[]Shell 脚本，返回 true、1 或空字符串时启用该 Action
shellString 或 String[]Shell 脚本，输出结果将替换选中文本
descriptionString 或 String[]描述信息（可选）

注意：选中的文本通过 Stdio::piped 传递给脚本，可以使用 $(cat) 捕获，或使用变量 $TM_SELECTED_TEXT。

示例

Markdown 文本格式化：

/* actions/markdown.json */
{
  "bold": {
    "title": "加粗",
    "filter": "",
    "shell": ["echo -n \"**${TM_SELECTED_TEXT}**\""],
    "description": "将选中文本加粗"
  },
  "italic": {
    "title": "斜体",
    "filter": "",
    "shell": ["echo -n \"_${TM_SELECTED_TEXT}_\""],
    "description": "将选中文本设为斜体"
  }
}

Go 语言运行脚本：

/* actions/go.json */
{
  "run main": {
    "title": "运行 main",
    "filter": "[[ \"$TM_CURRENT_LINE\" == *main* ]] && echo true || echo false",
    "shell": [
      "alacritty --hold --working-directory ${TM_DIRECTORY} -e go run ${TM_FILENAME};",
      "notify-send \"Golang\" \"RUN: ${TM_FILENAME}\""
    ],
    "description": "在新终端中运行 Go 主程序"
  },
  "run main in tmux": {
    "title": "tmux: 运行 main",
    "filter": "[[ \"$(cat)\" == *main* ]] && echo true || echo false",
    "shell": [
      "tmux split-window -h -c ${WORKSPACE_FOLDER}; tmux send 'go run ${TM_FILENAME}' Enter"
    ],
    "description": "在 tmux 中运行 Go 主程序"
  }
}

变量（Variables）

变量可以在 snippet.body、action.filter 和 action.shell 中使用。

语法：支持 $VARIABLE 和 ${VARIABLE} 两种格式。

路径相关

变量说明
TM_SELECTED_TEXT当前选中的文本
TM_CURRENT_LINE光标所在行的内容
TM_CURRENT_WORD光标所在的单词
TM_LINE_INDEX光标所在行（0 开始索引）
TM_LINE_NUMBER光标所在行（1 开始索引）
TM_FILENAME当前文件名
TM_FILENAME_BASE当前文件名（不含扩展名）
TM_DIRECTORY当前文件所在目录
TM_FILEPATH当前文件的完整路径
RELATIVE_FILEPATH相对于工作区的文件路径
CLIPBOARD剪贴板内容
WORKSPACE_NAME工作区/文件夹名称
WORKSPACE_FOLDER工作区/文件夹路径
CURSOR_INDEX光标索引（0 开始）
CURSOR_NUMBER光标索引（1 开始）

日期时间

变量说明示例
CURRENT_YEAR当前年份2025
CURRENT_YEAR_SHORT年份后两位25
CURRENT_MONTH月份（补零）02
CURRENT_MONTH_NAME月份全称February
CURRENT_MONTH_NAME_SHORT月份缩写Feb
CURRENT_DATE日期（补零）08
CURRENT_DAY_NAME星期全称Saturday
CURRENT_DAY_NAME_SHORT星期缩写Sat
CURRENT_HOUR小时（24 小时制）14
CURRENT_MINUTE分钟30
CURRENT_SECOND秒45
CURRENT_SECONDS_UNIXUnix 时间戳1738930245
CURRENT_TIMEZONE_OFFSET时区偏移+08:00

随机值

变量说明
RANDOM6 位随机数字
RANDOM_HEX6 位随机十六进制字符串
UUIDUUID v4

注释符号（预留）

变量说明
BLOCK_COMMENT_START块注释开始符号
BLOCK_COMMENT_END块注释结束符号
LINE_COMMENT行注释符号

文档颜色（DocumentColor）

hx-lsp 支持识别多种颜色格式，并在编辑器中显示颜色预览。

标准 CSS 颜色

十六进制：

  • #ffffff - 标准 6 位十六进制

RGB/RGBA：

  • rgb(255, 255, 255) - 整数形式
  • rgb(2.0, 255.0, 255.0) - 浮点数形式
  • rgb(100%, 0%, 50%) - 百分比形式
  • rgba(1.0, 0.0, 0.0, 0.5) - 带透明度

HSL/HSLA：

  • hsl(240, 50%, 50%) - 色相 0-360 度，饱和度/亮度百分比
  • hsl(180, 0.5, 0.5) - 浮点数形式
  • hsla(300, 100%, 100%, 0.5) - 带透明度

HSV/HSVA：

  • hsv(300, 100%, 100%) - 色相 0-360 度，饱和度/明度百分比
  • hsv(180, 0.5, 0.5) - 浮点数形式
  • hsva(180, 0.5, 0.5, 0.5) - 带透明度

Bevy 游戏引擎颜色

  • srgb(1.0, 0.0, 0.0) - 标准 RGB（0.0-1.0）
  • srgba(1.0, 0.0, 0.0, 0.8) - 带透明度

参考