GitHub Lua Weekly Trending

neovim/nvim-lspconfig

Quickstart configs for Nvim LSP

nvim-lspconfig

nvim-lspconfig is a collection of LSP server configurations for the Nvim LSP client.

View all configs, or run :help lspconfig-all from Nvim.

Important ⚠️

require('lspconfig') (the legacy "framework" of nvim-lspconfig) is deprecated in favor of vim.lsp.config (Nvim 0.11+).
- The lspconfig.lua module will be dropped. Calls to require('lspconfig') will show a warning, which will later become an error.
nvim-lspconfig itself is NOT deprecated. It provides server-specific configs.
- The configs live in the lsp/ directory. vim.lsp.config automatically finds them and merges them with any local lsp/*.lua configs defined by you or a plugin.
- The old configs in lua/lspconfig/ are deprecated and will be removed.

Migration instructions

Upgrade to Nvim 0.11+
(Optional) Use vim.lsp.config('…') (not require'lspconfig'.….setup{}) to customize or define a config.
Use vim.lsp.enable('…') (not require'lspconfig'.….setup{}) to enable a config, so that it activates for its filetypes.

Support

These configs are best-effort and supported by the community (you). See contributions.

Ask questions on GitHub Discussions, not the issue tracker.
If you found a bug in Nvim LSP (:help lsp), report it to Neovim core.
- Do not report it here. Only configuration data lives here.

Install

Requires Nvim 0.11.3+.
- Support for Nvim 0.10 will be removed. Upgrade Nvim and nvim-lspconfig before reporting an issue.

With Nvim 0.12+, you can use the builtin vim.pack plugin manager:

vim.pack.add{
  { src = 'https://github.com/neovim/nvim-lspconfig' },
}

Or install nvim-lspconfig using Vim's "packages" feature:

git clone https://github.com/neovim/nvim-lspconfig ~/.config/nvim/pack/nvim/start/nvim-lspconfig

Or use a 3rd-party plugin manager.

Quickstart

Install a language server, e.g. pyright
```
npm i -g pyright
```
Enable its config in your init.lua (:help lsp-quickstart).
```
vim.lsp.enable('pyright')
```
Ensure your project/workspace contains a root marker as specified in :help lspconfig-all.
Open a code file in Nvim. LSP will attach and provide diagnostics.
```
nvim main.py
```
Run :checkhealth vim.lsp to see the status or to troubleshoot.

See :help lspconfig-all for the full list of server-specific details. For servers not on your $PATH (e.g., jdtls, elixirls), you must manually set the cmd parameter:

vim.lsp.config('jdtls', {
  cmd = { '/path/to/jdtls' },
})

Commands

:LspInfo (alias to :checkhealth vim.lsp) shows the status of active and configured language servers.
:lsp enable [<config_name>] (:LspStart for Nvim 0.11 or older) Start the requested server name. Will only successfully start if the command detects a root directory matching the current config.
:lsp disable [<config_name>] (:LspStop for Nvim 0.11 or older) Stops the given server. Defaults to stopping all servers active on the current buffer. To force stop use :LspStop!
:lsp restart [<client_name>] (:LspRestart for Nvim 0.11 or older) Restarts the given client, and attempts to reattach to all previously attached buffers. Defaults to restarting all active servers.

Configuration

Nvim sets default options and mappings when LSP is active in a buffer:

To customize, see:

Extra settings can be specified for each LSP server. With Nvim 0.11+ you can extend a config by calling vim.lsp.config('…', {…}).

vim.lsp.config('rust_analyzer', {
  -- Server-specific settings. See `:help lsp-quickstart`
  settings = {
    ['rust-analyzer'] = {},
  },
})

Config priority

Configs are sourced in this order:

lsp/ in 'runtimepath'
after/lsp/ in 'runtimepath'
vim.lsp.config()

If you install nvim-lspconfig or similar plugins, the order that configs are applied depends on the load order. To ensure that your own config "wins" and overrides the others, use after/lsp/ and/or vim.lsp.config() to override/extend the defaults.

Creating a config

As code

Run :lua vim.lsp.config('foo', {cmd={'true'}})
Run :lua vim.lsp.enable('foo')
Run :checkhealth vim.lsp, the new config is listed under "Enabled Configurations". 😎

As a file

Create a file after/lsp/foo.lua somewhere on your 'runtimepath'.
```
:exe 'edit' stdpath('config') .. '/after/lsp/foo.lua'
```
Add this code to the file (or copy any of the examples from the lsp/ directory in this repo):
```
return {
  cmd = { 'true' },
}
```
Save the file (with ++p to ensure its parent directory is created).
```
:write ++p
```
Enable the config.
```
:lua vim.lsp.enable('foo')
```
Run :checkhealth vim.lsp, the new config is listed under "Enabled Configurations". 🌈

LSP Settings Type Annotations

nvim-lspconfig generates Lua type definitions for each supported LSP server. By manually adding annotations (e.g., ---@type lspconfig.settings.server_name), you enable auto-completion and diagnostics for your server settings.

Example:

---@type vim.lsp.Config
local config = {
  ---@type lspconfig.settings.lua_ls
  settings = {
    Lua = {
      runtime = {
        version = 'LuaJIT',
      },
      workspace = {
        preloadFileSize = 10000,
        library = {
          vim.env.VIMRUNTIME,
        }
      },
    },
  },
}

vim.lsp.config('lua_ls', config)

Troubleshooting

Start with :checkhealth vim.lsp to troubleshoot. The most common reasons a language server does not start or attach are:

Language server is not installed. nvim-lspconfig does not install language servers for you. You should be able to run the cmd defined in the config from the command line and see that the language server starts. If the cmd is a name instead of an absolute path, ensure it is on your $PATH.
Missing filetype plugins. Some languages are not detected by Nvim because they have not yet been added to the filetype detection system. Ensure :set filetype? shows the filetype and not an empty value.
Not triggering root detection. Some language servers require a "workspace", which is found by looking for an ancestor directory that contains a "root marker". The most common root marker is .git/, but each config defines other "root marker" names. Root markers/directories are listed in :help lspconfig-all.

You can also explicitly set a root instead of relying on automatic detection by enabling 'exrc' and adding an .nvim.lua at the desired root dir with the following code:
```
vim.lsp.config('<client name>', {
  root_dir = vim.fn.fnamemodify(debug.getinfo(1, 'S').source:sub(2), ':p:h'),
})
```
Note that prior to nvim 0.12 exrc file is executed only if it's inside of a cwd where you start nvim.

Bug reports

If you found a bug with LSP functionality, report it to Neovim core.

Before reporting a bug, check your logs and the output of :checkhealth vim.lsp. Add this to your init.lua to enable verbose logging:

vim.lsp.log.set_level('debug')

Attempt to run the language server, then run :LspLog to open the log. Most of the time, the reason for failure is present in the logs.

Contributions

If a language server is missing from configs.md, contributing a new configuration for it helps others, especially if the server requires special setup. Follow these steps:

Read CONTRIBUTING.md.
Create a new file at lsp/<server_name>.lua.
- Copy an existing config to get started. Most configs are simple. For an extensive example see texlab.lua.
Ask questions on GitHub Discussions or in the Neovim Matrix room.

Release process

To publish a release:

Create and push a new tag.
After pushing the tag, a GitHub action will automatically package the plugin and publish the release to LuaRocks.

License

nvim-lspconfig is licensed under the terms of the Apache 2.0 license.

See LICENSE.md

iDvel/rime-ice

Rime 配置：雾凇拼音 | 长期维护的简体词库

雾凇拼音

功能齐全，词库体验良好，长期更新修订。

Rime Input Method Engine / 中州韵输入法引擎是一个跨平台的输入法算法框架。

基于这一框架，Rime 开发者与其他开源社区的参与者在多个平台上创造了不同的输入法前端实现。

这里是 Rime 的一份配置仓库，用户需要下载各平台对应的前端，并将此配置应用到配置目录。

雾凇拼音提供了一套开箱即用的完整配置，包含输入方案（全拼、常见双拼）、长期维护的开源词库及各项扩展功能。

详细介绍 | 常见问题 | 更新日志

在线体验（由 fcitx5-rime.js 支持，感谢 @Mintimate 友情构建）

基本套路

简体 | 全拼 | 双拼
主要功能
- 轻量的英文输入，支持中英混输
- 优化英文输入体验
- 拆字反查（uU+拼音），拆字辅码（拼音+`+拆字辅码）
- 自整理的 Emoji
- 以词定字（左右中括号：[、]）
- 长词优先
- Unicode（U+Unicode 码位）
- 数字、人民币大写（R+数字）
- 日期、时间、星期（详见方案 /date_translator 节点）
- 农历（转写：N+八位数字；获取当前农历：全拼nl，双拼lunar）
- 简易计算器（cC+算式）
- UUID（uuid）
- 常见错音错字提示
- 置顶候选项（详见方案 /pin_cand_filter 节点）
- 所有标点符号直接上屏
- 特殊符号、字符输入（全拼v+首字母缩写；双拼V+首字母缩写）
- 拼音纠错（模糊音）
- 更多默认未启用的功能请参考 lua/ 及方案注释
简体字表、词库
- 通用规范汉字表（by 中华人民共和国教育部）8K 常用汉字
- Unihan 字库（by Unicode lnc | UNICODE LICENSE V3）40K 大字库， 默认未启用
- 现代汉语常用词表（by 中国国家语言文字工作委员会）
- 华宇野风词库（by 野风）
- 简化字八股文（by rime | LGPL）
- 清华大学开源词库（by THUNLP | MIT）
- 腾讯词向量（@Huandeep 整理 | by Tencent AI Lab | CC BY 3.0）
词库修订
- 校对大量异形词、错别字、错误注音
- 全词库完成注音
- 同义多音字注音
- 参考
  - 《现代汉语词典》
  - 《同义词词林》
  - 《新华成语大词典》
  - 校对标准论坛
Rime、Squirrel、Weasel 常用配置项的详尽注释

长期维护词库

因为没有找到一份比较好的词库，干脆自己维护一个。综合了几个不错的词库，精心调教了很多。

词库简介：

字表：
- 8105 常用字表，《通用规范汉字表》+基本的扩充。
- 41448 Unihan 大字表，默认未启用。
词库：
- base 基础词库，含两字词及调频。
- ext 扩展词库，小词库，含多音字注音。
- tencent 扩展词库，大词库，无注音（由 Rime 自动注音），含非多音字、只发一种音的多音字、同义多音字。
纯手搓的 Emoji
英文词库：
- en 20k 左右的常见单词 + 少许补充。
- en_ext 扩展词库，大部分是缩写或互联网相关。

维护内容主要是异形词、错别字的校对，错误注音的修正，缺失的常用词汇的增添，词频的调整。

欢迎在词库方面提 issue #666 ，我会及时更新修正。

使用说明

选择和安装 RIME 前端

要使用雾凇拼音默认提供的所有功能，请保证

您的 RIME 前端提供的 librime 版本 ≥ 1.8.5 且
含有 librime-lua 依赖

以下是主流平台上的一些 RIME 前端安装建议。部分信息具有时效性，请以当下具体情况为准：

系统	RIME 前端	雾凇拼音版本要求	备注
Android	fcitx5-android + plugin.rime（小企鹅输入法）	≥ 0.0.8	暂不支持九宫格
Android	Trime（同文输入法）	≥ 3.2.11
iOS	Hamster（仓输入法）	N/A	闭源；有内购
Linux	ibus + ibus-rime	librime ≥ 1.8.5 且装有 librime-lua	部分发行版需手动安装 librime-lua
Linux	fcitx4 + fcitx-rime	完整模式：librime ≥ 1.8.5 且装有 librime-lua	仅支持 Linux 的 fcitx4 + fcitx-rime；配置目录为 `$HOME/.config/fcitx/rime/`
Linux	fcitx5 + fcitx5-rime	librime ≥ 1.8.5 且装有 librime-lua	部分发行版需手动安装 librime-lua
macOS	Squirrel（鼠须管）	≥ 1.0.0	0.16.0 - 0.18.0 版本请参考🔗
macOS	fcitx5-macos	N/A	支持卷轴模式
Windows	Weasel（小狼毫）	≥ 0.15.0	0.14.3 可手动更新 rime.dll（但不支持彩色 emoji） Weasel 当下有兼容性问题，建议安装其他输入法备用

Linux 依赖问题的具体解释请参考 #840。

Note

本仓库中提供的 fcitx4 兼容（others/fcitx4/）仅支持 Linux + fcitx4 + fcitx-rime。不适用于 fcitx5、ibus、macOS、Windows 等其他前端或平台。

雾凇拼音的部分配置可能要求更高的 librime 或者客户端版本，这些功能已在具体配置文件中注明。

以下安装方式，选择其一：

手动安装

您可以将仓库打包下载，将所有文件复制粘贴到 RIME 前端的配置目录，重新部署。

只需要使用或者更新词库的话，可以手动粘贴覆盖 cn_dicts en_dicts opencc 三个文件夹。

Note

雾凇拼音中多个文件可能与其他方案同名冲突，如果是新手想一键安装，建议备份原先配置，清空配置目录再导入。

Note

单独使用词库注意事项：rime_ice.dict.yaml 下面包含了大写字母，这和配置有些许绑定，可以直接删除，详细说明：#356

您也可以前往 Release 界面，下载特定版本的词典文件（具体描述见 Release 说明），覆盖配置目录的对应文件。

Git 安装

您如果熟悉 git 常用操作，可以使用 git clone 命令将本仓库克隆到对应前端的用户目录。由于本库提交历史较多且更改频繁，添加 --depth 参数可以显著减少传输体积。

git clone https://github.com/iDvel/rime-ice.git Rime --depth 1

# 更新
cd Rime
git pull

通过 checkout 命令，您也可以实现更新部分文件的效果。

东风破 plum

选择配方（others/recipes/*.recipe.yaml）来进行安装或更新。

/plum/ 简易安装教程

安装 plum

# 请先安装 git 和 bash，并加入环境变量
# 请确保和 github.com 的连接稳定
cd ~
git clone https://github.com/rime/plum.git plum
# 卸载 plum 只需要删除 ~/plum 文件夹即可

使用 plum

cd ~/plum
bash rime-install <recipe_name>

部分发行版可能需要手动指定安装位置

# 为 fictx5 安装
rime_frontend=fcitx5-rime bash rime-install <recipe_name>

# 为 fcitx4 安装
rime_frontend=fcitx-rime bash rime-install <recipe_name>

词库配方只是更新具体词库文件，并不更新 rime_ice.dict.yaml 和 melt_eng.dict.yaml，因为用户可能会挂载其他词库。如果更新后部署时报错，可能是增、删、改了文件名，需要检查上面两个文件和词库的对应关系。

℞ 安装或更新全部文件

bash rime-install iDvel/rime-ice:others/recipes/full

℞ 安装或更新所有词库文件（包含下面三个）

bash rime-install iDvel/rime-ice:others/recipes/all_dicts

℞ 安装或更新拼音词库文件（ cn_dicts/ 目录内所有文件）

bash rime-install iDvel/rime-ice:others/recipes/cn_dicts

℞ 安装或更新英文词库文件（ en_dicts/ 目录内所有文件）

bash rime-install iDvel/rime-ice:others/recipes/en_dicts

℞ 安装或更新 opencc （ opencc/ 目录内所有文件）

bash rime-install iDvel/rime-ice:others/recipes/opencc

下面这个配方会在 radical_pinyin.custom.yaml 和 melt_eng.custom.yaml 里将 speller/algebra 修改为对应的双拼拼写，选择一个自己使用的双拼作为参数。

℞ 双拼补丁

bash rime-install iDvel/rime-ice:others/recipes/config:schema=flypy
bash rime-install iDvel/rime-ice:others/recipes/config:schema=double_pinyin
bash rime-install iDvel/rime-ice:others/recipes/config:schema=mspy
bash rime-install iDvel/rime-ice:others/recipes/config:schema=sogou
bash rime-install iDvel/rime-ice:others/recipes/config:schema=abc
bash rime-install iDvel/rime-ice:others/recipes/config:schema=ziguang

℞ 下载特定版本的配置

在仓库后加 @tag 即可，例如：

bash rime-install iDvel/rime-ice@2024.05.21:others/recipes/full

仓输入法 Hamster

参考如何导入"雾凇拼音输入方案"

仓输入法目前已内置雾凇拼音。

使用九宫格，需要同时启用九宫格方案（输入方案设置）和九宫格布局（键盘设置 - 键盘布局 - 中文 9 键）。

自动部署脚本

Mark24Code/rime-auto-deploy 一个自动部署脚本，集成了雾凇拼音，帮助无痛快速安装、部署 Rime 输入法（中州韵、小狼毫，鼠须管）以及部署配置。

Arch Linux

使用 AUR helper 安装 rime-ice-git 包即可。

# paru 默认会每次重新评估 pkgver，所以有新的提交时 paru 会自动更新，
# yay 默认未开启此功能，可以通过此命令开启
# yay -Y --devel --save

paru -S rime-ice-git
# yay -S rime-ice-git

推荐使用补丁的方式启用。

参考下面的配置示例，修改对应输入法框架用户目录（见下）中的 default.custom.yaml 文件

iBus 为 $HOME/.config/ibus/rime/
Fcitx5 为 $HOME/.local/share/fcitx5/rime/

default.custom.yaml

patch:
  # 仅使用「雾凇拼音」的默认配置，配置此行即可
  __include: rime_ice_suggestion:/
  # 以下根据自己所需自行定义，仅做参考。
  # 针对对应处方的定制条目，请使用 <recipe>.custom.yaml 中配置，例如 rime_ice.custom.yaml
  __patch:
    key_binder/bindings/+:
      # 开启逗号句号翻页
      - { when: paging, accept: comma, send: Page_Up }
      - { when: has_menu, accept: period, send: Page_Down }

Linux Fcitx4

如果您使用的是 Linux + Fcitx4，可使用仓库自带脚本自动备份并同步配置：

bash others/fcitx4/install_to_fcitx4.sh

如果系统较旧（例如 librime < 1.8.5 或缺少 librime-lua），可使用兼容模式（禁用 Lua 扩展功能，仅保留基础拼音/词库能力）：

bash others/fcitx4/install_to_fcitx4.sh --legacy-no-lua

说明：默认执行 bash others/fcitx4/install_to_fcitx4.sh 时，脚本会自动检测环境；若版本过旧或缺少 librime-lua，会自动切换到兼容模式。

兼容模式（--legacy-no-lua）会关闭以下 Lua 扩展能力：

以词定字（[、]）
日期、时间、星期
农历
UUID
Unicode 输入（U 前缀）
数字、金额大写（R 前缀）
简易计算器（cC 前缀）
错音错字提示
英文自动大写
v 模式 symbols 优先
置顶候选项
长词优先
英文候选降权
部件拆字辅码（search.lua）

兼容模式仍保留：基础拼音输入、词库、melt_eng 英文输入、中英混输、简繁切换、Emoji、用户短语。

感谢 ❤️

特别感谢上文已经提及的词库、词典的作者、贡献者及整理者；特别感谢以及下列词库、方案、脚本的作者及贡献者（提及的均为 GitHub id）：

@mozillazg 开发的汉字转拼音工具和数据库（MIT）
melt_eng（@tumuyan | Apache 2.0）：提供了部分（约 1000 条）英文词汇以及原始英文方案参考；
部件拆字方案（@mirtlecn | GPL 3.0）：提供的拆字反查和候选筛选插件；
长词优先插件（@tumuyan | Apache 2.0）
Unicode 插件（@shewer | MIT）
数字、人民币大写插件（@98wubi）
农历插件（@boomker | LGPL 3.0）
未能在此处详述的、在本库源码注释中提及的项目及作者给予的帮助和参考

感谢校对标准论坛的存在。

感谢 @Huandeep 整理的多个词库。

感谢 @Mirtle 完善的多个功能。

感谢 @Lithium-7 对词库的大量修订。

感谢所有贡献者。

Thanks to JetBrains for the OSS development license.

赞助 ☕

如果觉得项目不错，可以请 Dvel 吃个煎饼馃子。

amzxyz/rime_wanxiang

万象拼音：基于rime生态打造，全方位对标大厂体验，内置大语料与AI辅助炼制的向量词库和语法模型，全带调编码词库，让输入行云流水，开箱即用。更有PRO版带来辅助码创新体验，支持7种辅助码。集成超级注释、候选反查筛选、快符、手动排序、tips等特色扩展功能，让你保证大厂体验的同时，深度享受 Rime 超强自定义的便利。详见README。Q群：11033572满 / 11631066

万象系列方案

🌌 万象拼音——基于深度优化的词库和语法模型

💎 核心基石： > 万象词库经 AI 与海量语料深度优化(目前已进入手动维护期)，是一款专为“语句流”“类大厂”打造的全方案立体词库。它将带调拼音标注、词组构成与精准词频作为体验基石，以日常与专业词汇为主体，结合语法模型，为您带来精准、流畅的输入体验。

开放生态：支持高度自定义，鼓励通过“词库 + 转写”打造您的专属输入方案。
持续打磨：我们极度重视数据准确与时效，欢迎随时反馈。
📝 万象词库问题收集反馈表

🚀 核心功能亮点

🧪 全能拼音标注

全词库自带音调。独家支持多种带调方案、声调注释，以及整句拼音串上屏。

⚖️ 极致权重与分词

采用“错位构词法”死磕首选权重与分词，能词能句能单，结合语法模型，实现行云流水的输入快感。

🔍 深度反查系统

字库全面，已支持至 Unicode 17 (U17) 标准。提供两分、多分、笔画三种反查方式，轻松搞定生僻字。

🧩 创新 Lua 扩展

支持符号包裹、Tips 扩展显示、输入后辅筛等丰富功能；并带来手动实时排序、无感造词不调频、输入统计等创新交互。

⌨️ 全面辅码兼容

底层支持全拼/双拼转换，以及拼音 + 辅助码的自由组合。内置第三方墨奇码、鹤形、自然码、虎码首末等 8 种主流辅码方案。

🌟 项目愿景

极致变革与追求：万象致力于提升rime输入法音码基础体验，带来由内而外的输入变革，深入影响体验的每一处细节，都持续追求最优、最精！

✨ 效果预览 & 版本对比

万象拼音提供两个主要版本，请根据您的输入习惯选择：

版本差异	🟢 标准版 (Standard)	🔵 增强版 (Pro)
方案文件	`wanxiang.schema.yaml`	`wanxiang_pro.schema.yaml`
支持类型	全拼、任意双拼	仅支持双拼
自动调频	默认开启	默认关闭
用户词记录	自动记录，无差别积累	手动造词 `` 引导，词库可控，或者无感造词
用户词位置	`wanxiang.userdb`	`zc.userdb`
辅助码	仅基于声调的辅助	7种辅助码可选，兼声调辅助
全场景辅筛	`引导支持两分、多分、笔画、声调	`引导支持两分、多分、笔画、声调、辅助码
简码策略	全拼开启转写简码，双拼未开启	自带部分数据但未配置 (推荐自设)
词库格式	你 ➩ `nǐ` ➩ 1000	你 ➩ `nǐ;re` ➩ 1000

🚀 新手快速入门

如果您不了解 Rime 的基础（如用户目录、部署、皮肤等），建议先阅读以下教程了解基础运行特性，后面只说万象怎么用，默认认为你已有基础：

📚 基础教程

Oh My Rime - Rime 安装指南

Rime 参数配置详解

重要⚠️: 一定要学会读配置,yaml语法配置不是编程不是代码,中间的注释足以让你理解功能,README.md只能说是一个抽象后的概念总结,最后的修改还是要去改配置,使用rime绕不开配置文件,如果能遍历一次配置,将很大程度上帮助理解功能设计、参数,在未来有需求的时候想起哪里能配置,所以大可收起我不是程序员我只想使用这种心态。从成本的角度看配置收益会更大，结合readme将配置层与应用层结合起来将能用好rime。

💡 友情提示 如果您是第一次使用万象，请暂时放下过往对 Rime 配置的固有经验。万象拥有一套独特的自动化配置逻辑，建议严格按照以下步骤先将方案“跑起来”，体验功能后再进行深度定制。

1. 📦 快速部署 (通用步骤)

安装：将方案文件解压，直接放入 Rime 的 用户目录 中。

注：您可以手动下载 Release 包，或使用万象工具箱下载,图形化简单高效易于更新见:万象工具箱

部署：点击“重新部署”按钮，等待完成。
切换方案：在输入状态下，输入 / (斜杠) 引导指令切换双拼/全拼方案（如 /flypy）。

切换后请根据提示再次重新部署。

⚙️ 切换指令背后的逻辑 该指令会自动修改 4 个补丁文件的输入类型。若根目录无自定义文件，脚本会自动从 custom 文件夹复制模版并修改；若根目录已存在自定义文件，则只修改输入方案参数，绝不会覆盖您的原有配置。

/flypy    → 小鹤双拼
/mspy     → 微软双拼
/zrm      → 自然码
/sogou    → 搜狗双拼
/znabc    → 智能ABC
/ziguang  → 紫光双拼
/pyjj     → 拼音加加
/gbpy     → 国标双拼
/lxsq     → 乱序17
/pinyin   → 全拼
/wxsp     → 万象双拼
/zrlong   → 自然龙(反查是全拼)
/hxlong   → 汉心龙(反查是全拼)
/jjf      → 间接辅助
/zjf      → 直接辅助

2. 🍎 iOS 平台特殊操作指南

iOS 平台由于沙盒机制限制，需要额外的文件同步操作。

仓输入法 (Hamster) 必须手动将键盘文件覆盖到应用文件才能生效：

下载与设置：仓设置首页 -> 输入方案设置 -> 右上角 + -> 方案下载 -> 下载万象方案（如标准版）。然后再勾选“万象系列方案”并取消之前的方案。
切换输入类型：在体验输入法界面，长按 / (不要上划)，输入切换指令（如 /flypy为小鹤双拼），等待提示“已切换至相应方案···”。
覆盖 (关键步骤)：仓设置首页 -> 文件管理 -> 使用键盘文件覆盖应用文件。（注意⚠️：如果您开启了iCloud同步功能，需要继续执行：仓设置首页 -> iCloud同步 -> 拷贝应用文件至iCloud，如果不执行则会重新部署时会重新部署iCloud中的方案而导致无法使用万象）
部署：仓设置首页 -> RIME -> 重新部署。

元书输入法 (Hamster3) 需要配置正则以实现自动文件复制：

从 RimeSharedSupport 目录中复制 include_keyboard_rime_files.txt 文件到万象方案目录下。
编辑该文件，在底部新增以下正则表达式：

^.*[.]custom.*$

3. 🧠 语法模型安装 (推荐)

为了获得更精准的整句预测体验，建议安装语法模型。

安装步骤：下载语法模型文件，直接放置于 Rime 用户文件夹根目录，无需任何额外配置。
Android 用户特别警告：

⚠️ 关于 Fcitx5 (小企鹅) 等前端的权限问题 部分安卓前端（如 Fcitx5）的数据存储在系统 /data 目录下，受严格的 Linux 权限控制。

错误做法：使用 MT 管理器等工具直接复制文件。这会导致文件所有者/权限组不一致，引发读取失败。

故障表现：输入法部署报错、极其卡顿、提示内存溢出。

正确做法：

使用输入法 App 自带的“导入文件”功能（调用安卓标准存储框架）。

(Root 用户) 手动复制后，务必修正文件的 chown 和 chmod 权限。

💡 性能与资源说明 语法模型是一个用于大数据遍历的静态二进制模块，旨在弥补单纯词库的不足。

资源消耗：主要利用 CPU 算力进行计算，内存占用极低。

非膨胀数据：它与那些“越用越大”的热加载用户数据完全不同，它的大小是固定的，不会导致系统臃肿，请放心使用。

4. 🛠️ 进阶配置：Custom Patch (长期稳定之选)

强烈推荐长期使用者掌握此方法。 custom.yaml 是对方案文件的最后一道补丁，属于您个人的私有配置，永远不会被软件升级所覆盖。

⚙️ 运行机制 在“快速运行”步骤中，通过 / 指令切换方案时，脚本实际上已经帮您完成了 custom 文件的初始化（从 custom 文件夹复制模版到根目录）。 请务必注意： 模版里的内容只是示例！请打开文件详细阅读每一行，保留需要的，删除不需要的，理解每一行代码的含义后再保存。

⚠️ 核心操作原则

文件位置原则：

custom 文件必须位于 用户目录根目录 (与 wanxiang.schema.yaml 同级)。
切勿直接修改 custom/ 文件夹里的文件！那里只是“仓库”，修改那里不会生效。
更多方法参照custom目录携带的patch方法论。

补丁对应关系：

wanxiang.custom.yaml  👉 补丁对象：wanxiang.schema.yaml
default.custom.yaml   👉 补丁对象：全局配置 (通常留给前端控制)
squirrel.custom.yaml  👉 补丁对象：Mac 鼠须管外观
weasel.custom.yaml    👉 补丁对象：Win 小狼毫外观

尽量不要在 default.custom.yaml 里修改输入方案配置**！任何对方案的修改（如模糊音、快捷键）都必须针对具体的 schema 进行 Patch。default 文件请留给输入法前端程序去自动管理。

5. 🧰 万象工具箱 (PC 端神器)

PC 端用户推荐使用 Wanxiang Tools (All-in-one)，内置在线更新器，一站式解决下载、覆盖、部署问题。

智能更新：自动检测 GitHub / CNB 源，自动下载并解压覆盖。
白名单保护 (White-list)：支持受控的文件覆盖。即使下载包里有同名文件，只要您设置了白名单，工具就不会覆盖您的私人文件（需要您配置严密）。
双重重置模式：

构建重置：清空 build 目录，强制重新编译（解决奇怪的缓存 bug）。
纯净重置：仅保留白名单文件，其余全部替换为官方最新版（彻底解决文件改名、弃用残留问题）。

👉 点击下载万象工具箱

6. 📜 第三方更新脚本

如果您偏好轻量级脚本或非 Windows 环境，可以使用社区贡献的更新工具：

Python / PowerShell 脚本： 👉 rime-wanxiang-update-tools
Go 语言更新器： 👉 rime-wanxiang-updater

7. 🌿 东风破 (Plum) 管理器

如果您熟悉命令行操作，推荐使用 Plum (东风破) 进行安装和更新。请确保您已安装小狼毫、鼠须管或 Fcitx5 等前端。

💻 运行环境要求

操作系统	环境要求	备注
macOS / Linux	✅ 无需处理	系统已内置 Bash，直接运行即可。
Windows	🛠️ 需要 Git Bash	通常随 Git for Windows 自动安装。

🚫 Windows 用户注意： Windows 自带的 PowerShell 或 CMD 无法直接运行东风破脚本，必须使用 Git Bash 终端。

🔽 点击展开：万象系列方案安装命令 (完整列表)

先安装plum，这是维护在万象仓库plum分支的版本，去掉了默认方案，修改了默认路径，直接复制2个命令粘贴终端直接执行，打开终端的目录由你决定

git clone -b plum --depth 1 https://github.com/amzxyz/rime_wanxiang.git
cd plum

配置用户目录变量，检查状态是否正常：
对于小狼毫、鼠须管、Fcitx5已经默认配置了变量

export rime_frontend='rime/weasel'
export rime_frontend='rime/squirrel'
export rime_frontend='fcitx5/fcitx5-rime'

但对于Linux、Mac使用ibus、fcitx前端就需要自己设置变量，这个变量可以终端执行，但最好直接写入~/.zshrc

export rime_frontend=rime/ibus-rime
export rime_frontend=fcitx/fcitx-rime

有了上面的工具后你可以切换到刚刚拉取下来的脚本所在目录，执行以下对应的安装目录，即可实现安装和更新

基础版（完整）

bash rime-install amzxyz/rime_wanxiang@wanxiang-base:plum/full

基础版（仅词库）

bash rime-install amzxyz/rime_wanxiang@wanxiang-base:plum/dicts

自然码辅助版（完整）

bash rime-install amzxyz/rime_wanxiang@wanxiang-zrm-fuzhu:plum/full

自然码辅助版（仅词库）

bash rime-install amzxyz/rime_wanxiang@wanxiang-zrm-fuzhu:plum/dicts

墨奇辅助版（完整）

bash rime-install amzxyz/rime_wanxiang@wanxiang-moqi-fuzhu:plum/full

墨奇辅助版（仅词库）

bash rime-install amzxyz/rime_wanxiang@wanxiang-moqi-fuzhu:plum/dicts

小鹤辅助版（完整）

bash rime-install amzxyz/rime_wanxiang@wanxiang-flypy-fuzhu:plum/full

小鹤辅助版（仅词库）

bash rime-install amzxyz/rime_wanxiang@wanxiang-flypy-fuzhu:plum/dicts

虎码辅助版（完整）

bash rime-install amzxyz/rime_wanxiang@wanxiang-tiger-fuzhu:plum/full

虎码辅助版（仅词库）

bash rime-install amzxyz/rime_wanxiang@wanxiang-tiger-fuzhu:plum/dicts

五笔辅助版（完整）

bash rime-install amzxyz/rime_wanxiang@wanxiang-wubi-fuzhu:plum/full

五笔辅助版（仅词库）

bash rime-install amzxyz/rime_wanxiang@wanxiang-wubi-fuzhu:plum/dicts

汉心辅助版（完整）

bash rime-install amzxyz/rime_wanxiang@wanxiang-hanxin-fuzhu:plum/full

汉心辅助版（仅词库）

bash rime-install amzxyz/rime_wanxiang@wanxiang-hanxin-fuzhu:plum/dicts

首右辅助版（完整）

bash rime-install amzxyz/rime_wanxiang@wanxiang-shouyou-fuzhu:plum/full

首右辅助版（仅词库）

bash rime-install amzxyz/rime_wanxiang@wanxiang-shouyou-fuzhu:plum/dicts

8. 📂 自定义扩展-线上数据获取

在线数据源清单与用途：

文件名	用途	安装位置
`renming.dict.yaml`	人名词库，按需下载，pro使用万象工具箱刷新编码即可	下载后复制内容，追加到根目录的 `wanxiang.dict.yaml` 中。
`wuzhong.dict.yaml`	物种词库，含动物植物分类等词条，按需下载，pro使用万象工具箱刷新编码即可	下载后复制内容，追加到根目录的 `wanxiang.dict.yaml` 中。

9. 📂 数据管理

文件名	用途	注意事项
`lua/data/chinese_english.txt`	中文翻译英文数据库	数据库位于lua/replacer.userdb中。
`lua/data/english_chinese.txt`	英文翻译中文数据库	数据库位于lua/replacer.userdb中。
`lua/data/emoji.txt`	emoji数据库	数据库位于lua/replacer.userdb中。
`lua/data/abbrev.txt`	公共简码数据库	数据库位于lua/replacer.userdb中。
`lua/data/t9_abbrev.txt`	t9用公共简码数据库	数据库位于lua/replacer.userdb中。数字为键
`lua/data/*Phrases.txt`	OpenCC简繁转换词组数据库	数据库位于lua/replacer.userdb中。HK香港TW台湾
`lua/data/*Characters.txt`	OpenCC简繁转换单字数据库	数据库位于lua/replacer.userdb中。ST简繁、TS繁简
`tips_show.txt`	Tips 自带数据	数据库位于tips.userdb
`input_statistics.lua`	输入统计lua创建的实时数据	数据库位于lua/stats.userdb
`super_sequence.lua`	手动排序lua创建的实时数据	数据库位于lua/sequence.userdb

答疑

为什么PRO版本默认关闭调频的说明 enable_user_dict: false # 是否开启自动调频，true为开启

功能一览

辅助码系统

万象内置多套辅助码，不同的辅助码规则不同，可前往相应的资源下学习。以自然码举例采用“拼音+部首读音”的自然逻辑，无需记忆字根，在双拼/全拼基础上直接追加部首声母即可筛选。整体套路是三码出字、四码出词。

⚙️直接辅助码 (仅 PRO 版)

基本用法：输入双拼后直接追加部首声母。
- 示例：输入“镇”字，双拼 vf + 金字旁声母 j → vfj。
- 进阶：若未出现，可继续输入主体部件的声母进一步筛选。

重码处理与聚拢：当“双拼+辅码”与现有词组重码时（均为4码），系统优先显示词组以保证整句流畅。此时在编码末尾追加 /，即可强制系统忽略词组，优先展示带辅码的单字。（ps.从与词组重码率的角度来判断辅助码的好坏也是一项重要指标）

⚙️间接辅助码 (仅 PRO 版)

基本用法：使用 / 作为分隔符引导辅助码（格式：拼音/辅码）。
- 示例：ni/re。
特性：若不输入 /，系统将其视为普通拼音，绝不干扰整句切分。相比直接辅助码，此模式更适合新手或轻量级用户，无需担心重码干扰节奏。由于是对当前字的施加，所以必须提前考虑好，这与后面的辅筛，后筛选行程鲜明对比。

⚙️候选筛选 (输入后辅筛)

功能非常强大，主要分为两个大类，注意由于万象支持很多辅助码和输入类型，下面的举例请不要直接套用

1、首句，定点改字（仅pro）辅助码来自词库携带的辅助码

该功能由多个片段组成的句子才生效，因为固定词库的词条有筛选就够了，无需修改，多用于常用字的变异纠正。

输入预期：有没有啥问题，输出结果：又没有啥问题，希望改掉“又”，变成“有”，只需要通过引导符 ` (Tab上方的键)输入“有”的辅助码uo发现把“没”给改了，因为“眉”也是uo，此时我们继续追加uo9声调，就落点到了“ybUO9”自然出“有”，最终得到：有没有啥问题。

输入预期：真的是咯，输出结果：真的失落，这次要改两个字，我直接说结论：`后面输入 or0kk即可，or0定位是，kk定位咯。

2、辅筛，候选词过滤(base、pro均可)

这个功能与上面的功能其实工作在一条线上，怎么用完全看你的怎么想，你想着修改句子那就修改句子，你想筛选候选那就筛选候选，从来不用你使用复杂的方式，一切都工作在`这个符号后面。

当句子命中修改他将会保留下来，如果没命中但命中了辅筛，那么他将消失，呈现出来是辅筛的结果，无需复杂引导。

针对当前输入的候选词，可通过引导符 ` (Tab上方的键) 进行二次筛选：

操作：输入主拼音 -> 按 ` -> 输入部首读音首字母。
示例：输入拼音后，按 ` 再按 j (jin) 筛选金字旁；按 mu (mu) 筛选木字旁。

对于单字：实际上我们同时支持，两分：你(ni`rfer，ni`re)、多分：莫（mu`ckrida）、笔画：你ni`pspzhpd
对于词组，假设 “老实说” 的辅助码序列构造为：tb (老) + gt (实) + yd (说) = tbgtyd

在输入拼音 lkuiuo 后，按下引导符（默认 `），你可以这样筛选：

精准打击：输入 gt —— 匹配到“实”字，筛选出包含“实”的词。
跨字组合：输入 tg —— 匹配 t (老) 和 g (实)。
极致模糊：输入 ty —— 匹配 t (老) 和 y (说)。
任意跳跃：输入 bd —— 匹配 b (老的尾码) 和 d (说的尾码)。

只要你的输入符合 .*t.*b.*g.*t.*y.*d.* 的正则逻辑，都能精准命中！

声调反查支持 我们还支持在反查符号后面任意位置按顺序输入数字声调7890,单字只有第一个输入的数字生效，词组，按字数生效

例如单字：ni`r9e、ni`rf9er 词组：nihk`n9zr9e 为了用户方便声调可随意插入，程序会提取数字应用声调过滤，并将剩余字母编码组成按上面提到的逻辑执行

对于pro版本还可以设置词库中携带的辅助码用于反查，这就类似间接辅助码的功能了，但不同的是间接辅助能够句中任意，而反查只能作用于词库中已有的词组。

注意刻意设计词组匹配不支持笔画这也是为了规避复杂度

在你的方案文件中配置 wanxiang_lookup：

wanxiang_lookup:
  tags: [ abc ]            # 生效的 tag
  key: "`"                 # 反查引导符 (建议使用默认，避免与分词符 ' 冲突)
  lookup: [ wanxiang_reverse ] # 反查数据库
  data_source: [ aux, db ] # 【核心】数据源优先级：写在前面的优先！
                               # aux: 从词库注释(辅助码)提取
                               # db: 从反查数据库(拆字/五笔画等)提取

反查、笔画都必须wanxiang_reverse.custom配置，默认全拼加大写五笔画，你可以根据自己习惯定制五笔画对应的编码转写，反查则切换为对应的双拼全拼，这个文件与主方案类似，都是在根用户目录生效，打开就明白了。

⚙️输入前反查 通过拼音状态下 `〔反查：部件|笔画〕来引导拆字模式举例 震 假设你不认识，你可以通过雨和辰 来合并输入，拼音状态输入后，继续输入其它字符字母 `〔反查：部件|笔画〕会消失如下图，输入 yu if 即雨辰，结果出现了我们要的震字，且给出了辅助码 y 和 i ，y是雨的声母y，i是辰的声母ch，同时兼容通过hspnz代表横竖撇捺折五笔画。功能3是功能4的另一种表现形式,或者叫用法。这个功能依赖wanxiang_reverse.schema.yaml方案,可以通过custom配置成任意全拼双拼以匹配主方案一致的输入方式,因此是不是输入jn=jin需要看你具体的双拼类型。

⚙️声调辅助筛选 句子中间或者单字输入时需要可以使用更精确的聚拢方式"声调辅助"，7890数字按键代表1234声，轻声归并到4声，在功能4中我们可以在双拼两码后面3个编码的位置任意插入声调与两位辅助码混合使用，就是除了不用斜杠了，我们还顺序自由了，下面由两个图片说明问题,其实在键盘上想要安排四个按键是很难得,不是占用这个按键就是占用另外的,还有得朋友觉得离得远,还有得更是不需要声调,要把候选做成9个。这些都是存在的情况,现在的处理也是妥协后的结果,要想完全不占用按键类似的办法可以改成大写字母来代表,像地球拼音则是使用大于小于号这一片的符号来表示,我们的词库有声调这个基础,一定程度上还是要利用起来：

⚙️大写辅助筛选 在输入辅助码的时候可以穿插输入小写、大写、声调来定位，如：你ni/ni9/niRE/niR9E/nirE/niRe/ni9RE/niRE9/nire9/ni9re/nir9e.

⚙️自学习双模式输入预测 支持上屏后弹出预测候选或者输入上文后继续输入下文匹配到数据则置顶，两种模式相辅相成，开关中打开预测即可，最好是在手机上两种模式全开，在PC上面只开上下文调频具体详见：user_predict.lua：Rime 智能联想与语境记忆引擎

⚙️14/18键设定： 在万象的的各主方案的custom示例文件中我们已经预设了相关18jian、14jian的转写段落，位于wanxiang_algebra文件末尾，他的作用就是将方案原来的编码转换成键盘能打出来的字母或者数字，最终相呼应自然就能打出字了，当然这一切都可以自定义在custom文件中归你管理：

18jian:
  __append:
    - xlit/qwertyuiopasdfghjklzxcvbnm/qwwrryuiipassffhjjlzxxvbbm
14jian:
  __append:
    - xlit/qwertyuiopasdfghjklzxcvbnm/qqeettuuooaaddggjjlzzccbbm

开启方式，就是将相应的段落引用到custom头部的拼写运算后面

patch:
  speller/algebra:
    __patch:
      #- wanxiang_algebra:/模糊音
      - wanxiang_algebra:/base/全拼
      - wanxiang_algebra:/18jian    #引用到这里即可，⚠️注意，这一行必须是最后一行，不管前面有什么

⚙️英文方案：

①支持英文整句，支持与万象拼音挂接使用，支持独立使用，能在输入中自动完成句中空格的添加

②尾部~的含义，在输入句子的时候，当最后一个单词还未输入完全，如this is english只输入到了eng~这个时候就会出现~代表了一个不在词库中、未稳定的状态，这能保证你的输入视觉上的完美，也可以随时上屏。其本质是空码补全，因此有时候输入一个如scx~时候你可以空格上屏也可以拍下回车，兼容多种习惯。这里还要提到pro版本在开启字符集过滤的时候，有很多三码为空，比如输入: 你来当编码输入到 nil实际上是一个生僻字，但被字符集过滤删除，变为空码，而这个特性能让“你”依然显示到候选中并注释中显示~，同样代表这是一种派生，不稳定的状态，当nill完整输入完毕一个词汇将呈现出来，这与基础版nil就能打出"你来"是有极大的差异性的。

③输入hello则得到hello，输入首字母大写Hello则得到Hello和一众首字母大写的联想词，输入前两码大写HEllo则得到全为大写的HELLO和一众大写英文。

④ 英文智能加空格

模式选择：支持 off (关闭)、before (总是前加)、after (总是后加) 及 smart (智能模式) 四种策略。
智能连续逻辑：在 smart 模式下，仅从连续输入的第二个单词开始自动前加空格。
状态打断机制：手动输入【空格】或【回车】将立即重置加空格状态，有效避免在行首或手动分词后出现多余空格。
超时自动销毁：支持配置状态有效期（默认 5 秒）。若在非输入中停顿超时，自动清除加空状态，防止光标重新定位（如跳转至行首）后误输出空格，但输入中只要不上屏都能继续保持。
路径/网址优化：输入 \ 或 / 符号后，自动将加空逻辑延后 3 个单词，确保分次输入文件路径或 URL 时内容不被空格截断。

⚙️英文数字字母汉字的混合输入 混合输入:字母、汉字、数字、用于连接的特殊符号等组合，以及英文混输，我们统一放在了wanxiang_mixedcode.schema.yaml混合编码方案里，此功能无需引导，直接输入，不参与组句，类似：1000wclips、AD钙奶、PN结、Type-C以及纯英文，同样可以通过custom来定义你所使用的双拼。

⚙️整合说明 万象方案整合度很高，我们不希望使用户文件夹变得复杂，功能5中我们将两类习惯的五笔画和多分拆字和两分拆字整合到了一起，可以认为是4个挂接方案；在功能6中，我们将英文输入、中英混合编码、以及一些其他混合编码整合到了一起，共享方案转写，两个功能都保证了可配置性，都能与你所使用的双拼契合，对于词库也都整合到了dicts里面，为了能更好的统一更新和分发，仓库中我们支持基础版本词库、携带pro的辅助码版本词库、英文词库、混合词库4个类别，在release中各自归类，最终做到了根目录15个文件、4个文件夹示人，其中的custom目录还携带了用户自定义的法宝秘籍，能称得上简约而不简单。

其他亮点功能

⚙️日期、时间、节日、节气、问候模板： 可以在按键配置的地方定制引导前缀

key_binder/shijian_keys: ["/", "o"] 这样的配置以为你你可以/sj也可以osj，某些方案o有别的作用时候可以去掉o,灵活处理。

输入后N0101四位数模式下,可以输入月日，如果输入完整的八个数字则可以显示年月日，还有他强大的自定义能力，类型、格式、顺序、候选数，每一样都可以自定义，安全的占位逻辑和转译方式，该模式下只要是合法的月日格式、年月日各式都可以在输入完毕后直接用数字上屏，同时也兼容qwerty代表123456等上屏

#shijian:仅支持修改前缀，为了固定习惯，后两码写死，如有需求lua中修改
#时间：osj 或者 /sj
#日期：orq 或者 /rq
#日期差：orc 或者 /rc 
#之所以单独列出是为了保证rq能直接数字上屏，这个功能需要输入数字，所以/rc这一步不能上屏，
#但我们把逻辑后置用来代表结束就能在结束时也使用数字上屏，使用方法：
#/rc26p,/rc26+,/rc26p= 随意一个都是加上这个差值，得到未来日期；
#/rc26-,/rc26o 随意一个都是减去这个差值，得到过去日期
#以此实现了主键盘不用刻意按下shift，-=两个按键直接按，手机上也有op兼容可用，小键盘-+直接用
#农历：onl 或者 /nl
#星期：oxq 或者 /xq
#今年第几周：oww 或者 /ww
#节气：ojq 或者 /jq
#日期+时间：odt 或者 /dt
#时间戳：ott 或者 /tt
#/utc查询热门城市UTC时间
#大写N日期：N20250315 或者N0312不带年
#节日：ojr 或者 /jr
#问候模板：/day 或者 oday
# 通用日期时间格式化函数（供 /rq、/sj、/dt、N0101、N20150101 场景复用）
# 支持转义：
#   \X       —— 转义单个字符 X，按字面量输出（如 \Y \m \H 等）
#   [[...]]  —— 区块整体按字面量输出
#
# 约定占位符：
# 【日期】
#   Y  四位年份           0000-9999  例：2025
#   y  两位年份           00-99      例：25
#   m  月（前导零）        01-12      例：02
#   n  月（不带前导零）     1-12       例：2
#   d  日（前导零）        01-31      例：09
#   j  日（不带前导零）     1-31       例：9
#
# 【时间】
#   H  24小时（前导零）   00-23      例：08
#   G  24小时（不带零）   0-23       例：8
#   I  12小时（前导零）   01-12      例：08
#   l  12小时（不带零）   1-12       例：8   （注意是小写 L）
#   M  分钟（前导零）     00-59      例：05
#   S  秒（前导零）       00-59      例：09
#   p  am/pm（小写）     am / pm
#   P  AM/PM（大写）     AM / PM
# 【时区】
#   O  带冒号格式        +08:00、-04:30、+05:45
#   o  不带冒号格式      +0800、-0430、+0545
date_formats:
  - "Y年m月d日"
  - "Y-m-d"
  - "Y/m/d"
  - "Y.m.d"
  - "Ymd"
  - "Y年n月j日"
  - "y年n月j日"
  - "n月j日"
time_formats:
  - "H:M"
  - "H点M分"
  - "H:M:S"
  - "H时M分S秒"
  - "下午I:M"
  - "I:M P"
datetime_formats:
  - "Y-m-d H:M:S"
  - "Y-m-dTH:M:S O"
  - "YmdHMS"
  - "Y年m月d日 H点M分"
  - "y/m/d I:M p"

⚙️Unicode： 大写 U 开头，如 U62fc 得到「拼」。

⚙️数字、金额大写： 大写 R 开头，如 R1234 得到「一千二百三十四、壹仟贰佰叁拾肆元整」。输入后该模式下可以采用qwerty...依次代表123456上屏，也可以按下方向键上下进行候选的选择。

⚙️ /引导模式： 通过输入 /sx 快捷输入关于“数学”的特殊符号，具体能输入什么可以打开 wanxiang_symbols.yaml学习。以及前述提到的日期、时间等的引导都共用斜杠开头，可以理解为一种命令模式。其中/wx可以查询仓库连接和当前版本

⚙️输入统计Lua： 触发方式：/rtj日统计，/ztj周统计，/ytj月统计，/ntj年统计，/tj生涯。

⚙️计算器： 通过输入大写V引导继续输入如：V3+5 候选框就会有8和3+5=8，基础功能 + - * / % ^ 还支持 sin(x) cos(x) 等众多运算方式，打开super_calculator.lua阅读相关用法。

⚙️自动上屏： 例如：三位、四位简码唯一时，自动上屏如jjkw岌岌可危 zmhu怎么回事 。默认未开启，方案文件中speller:字段下取消注释这两句开启 # auto_select: true # auto_select_pattern: ^[a-z]+/|^[a-df-zA-DF-Z]\w{3}|^e\w{4}

⚙️空码回溯： 当输入的时候前面编码有候选，但继续输入无候选了，此时会将上一次的候选显示到候选中并在注释中显示了一个~作为表示一种不稳固状态，在英文输入句子的时候也会有这个状态的出现。这样的设计省去了回退键，可以直接空格上屏，同时他也能极大的减少三码是为空给用户带来的异常感知。

⚙️数字后自动半角： 当中文状态输入数字的时候后面立即输入,。将自动转换为数字分割符，例如科学记数法1000,000 小数点 3.1415,如果你加入冒号:还可以优雅的输入时间12:30，当然你还可以双击输入的符号恢复全角符号的输出。但若你完全没有场景使用该功能，则可以通过patch，将其修改为commit
punctuator/digit_separators: ",." > punctuator/digit_separators: commit

⚙️错音错字提示： 例如：输入gei yu给予，获得jǐ yǔ提示，此功能与全拼、双拼类型无关全部支持；

⚙️快符Lua： 例如通过 a/ ，快速自动上屏“！”符号或者定义为任意字符，享受26字母的扩展。其中值设置为repeat则意味着按下对应按键能否重复上一次上屏的内容。位于方案中quick_symbol_text段落是可以自定义映射关系的，对于特殊需求用户还可以修改正则表达式让引导策略发生变化，如首字符引导；

⚙️超级tips： 支持将表情、化学式、翻译、简码提示等等你能想到得数据获得提示显示并将通过一个自定义按键直接上屏，默认为“，” 也表现为逗号，避免了这类内容占用候选框，轻量化提示与上屏的能力。如果你设置逗号句号为翻页，逗号翻页如果正好是首选匹配，句号作为下一页则不干扰，当想要回到第一页，此时已经不匹配tips，此时逗号就不被tips占用了，就可以用于翻页。也可以将触发键变更为其他，位于key_binder/tips_key: "comma"。对于加载的类型可以屏蔽某一种，位于tips/disabled_types: []，括号内填入# 可选项为：偏旁，符号，化学式，时间，符号，组字，翻译，表情，货币，车牌, 单位等禁用类型。通过Control+t 进行开关。
⚠️仓输入法、超越输入法设置按键交由rime去处理，没有特殊需求应该一律交给rime，如需关闭将tips开关reset 0即可；
⚠️某些前端开启嵌入与窗口交互有bug，在开启tips的时候可能会造成异常的编码上屏，此时可以关闭tips在这些窗口使用输入法。

化学式：符号：表情：

⚙️短语格式化Lua： 将首页自定义短语中（custom phrase），诸如\n \s \t 等行中标识符转换为实际的换行、空格、制表符等等，支持重复字符声明，使得类似输入jys可以打出一首带格式的《静夜思》，使用\3的形式表示前面的字符重复N次。同时还支持对于动态变量的输入自定义，如时间、日期、时刻等等，打开文件即可看到完整占位说明，这个格式化也不拘泥于custom_phrase.txt，而是任何能产生候选的位置都支持，如super_replace提供的功能txt中都可以自定义，比如我在other.txt写入了此时此刻孪生一个午时八刻这样的候选。

例：静夜思\n\s\3李白\n床前明月光\n疑似地上霜\n举头望明月\n低头思故乡 jys

⚙️成对符号包裹Lua： 将输入中的短语通过输入追加\a 这样的末尾编码，触发相对于a这个字母映射的成对符号，例如： sj mk lq lh ji\k=《三毛流浪记》可以通过custom自定义符号和触发方式。

工作逻辑：输入词汇编码 > 按下锁定按钮\ > 按下映射字符\a > 《候选包裹成对符号》

⚙️输入模式切换Lua： 使用shift+space来进行中文候选词、英文候选词、混合候选词之间切换，默认为混合编码输入模式。这种是通过单一方案过滤得到的，当切换到英文模式的时候也可以用来输入英文整句。你也可以单独启用英文方案，可自定义快捷键在英文方案与中文方案之间切换，也是可以的。

⚙️超级注释Lua： 任意长度候选词的辅助码提示能力，默认开启1个字的辅助码，可以在方案文件中定义更长的长度。Ctrl+a可以实时在开启辅助码提示、开启声调全拼提示、关闭注释三个状态循环，Ctrl+c开启拆分辅助提示，优先级高于普通辅助提示。辅助码、拆分提示仅PRO有。cand_type则能配置候选类型外显标识符号，如∞代表多片段组成的句子，小加号代表记录的用户词，一起一些其他可配置项。

⚙️输入码音调显示Lua： 通过Ctrl+s可以使得输入码实时动态显示全拼并加音调，这是万象特色功能，你可以通过shift+enter上屏当前显示的编码字符串；

⚙️用户按需造词（仅PRO）： 默认通过``引导的方式进入用户词自造词模式，继续输入则``前缀消失，后面打出来的字上屏后完成造词。 pro版本讲究自主可控，由于辅助码的使用在很多时候不熟悉的时候可能会上屏更加异常的词汇或者生僻字，有的用户还不会使用Esc退出输入，而是选择直接敲下空格。按需造词可以有效把控造出的词是有意义的，而且默认靠后，原因简单基本上有意义的高频词万象已经提供，你应该使用辅助码将其前置。重点：在此基础上我们还支持“后触发”当你输入编码后发现没有你要的行业词汇，此时在后面双击`` 就可以在不删除编码的情况下完成造词。还有一个是次选造词，如果次选是你想要的，并且是词库组合成的，上屏就会记录下来。

总结一下，造词功能由：①``起始的主动造词，②``在编码后面的主动造词，③次选造词。三个特性构成

⚙️中文无感造词Lua（仅PRO）： 在关闭调频的情况下，通过逐步选字选词的方式上屏将为你记录整段，且不会产生小碎片，所造词汇与db用户词是一回事，遵循用户词管理的相关逻辑，其中直接上屏不造词。相比按需造词更加不打断输入。

⚙️英文造词Lua： 在任意英文输入编码后面，如：nihao\\末尾输入两个就可以触发英文造词。然后空格上屏他就记录到了en.userdb，导出和同步与用户词逻辑一致。

⚙️用户词删除： 使用Ctrl+del是rime系统删除用户词,就可以将用户词标记为c<=0，这在rime系统中就表现为不使用，假性删除。

⚙️字符集过滤（Lua）： 默认开启过滤，写在charset.dict.yaml的就是可以通过的字表，默认为8105+𰻞𰻞，如果你想什么字在小字集模式可以通过可以写在这里，配套开关【小字集、大字集】，快捷键Ctrl+g ，万象的字符集过滤其实不仅仅是这点，首先我们提供了一个二进制滤镜数据库charset_reverse.bin，内部通过编码层对字做出来标记，也就是除了字符范围，还标记了繁体适用范围.

# a,通用规范汉字表
# b,GB2312,
# g,GBK,
# T,Big5,(台港澳常用)
# j,简体,OpenCC (t2s)
# f,通用繁体,OpenCC (s2t)
# h,香港繁体, OpenCC (s2hk)
# t,台湾繁体, OpenCC (s2tw)
# u,基本区,U+4E00 - U+9FFF
# A-I,扩展 A-I 区,U+3400 及各扩展区 (支持到 Ext-I)
# c,兼容区汉字

我们在配置中还可以联动简繁转换的开关，对不同开关想要显示的范围进行配置，注意字母可以列出多个base: aj，还可以单独定义这个开关下对应的基黑白名单，他可以用来微调预设的范围，比如8105其实没有“囧”但常用我们就可以加入白名单里面，让开启过滤的时候能显示出来
同时不同的option开关之间是求并集，也就是说假设你切换到了s2hk意味着所有香港繁体字都能显示出来，合起来就是8105+香港繁体，这样就不会因为开启了字符集过滤导致某些繁体字丢失显示不出来。这样的设计让你能随意新增开关，定义开关对应的过滤范围，以及对于简繁转换的联动。

charset:
  - option: charset_filter
    base: a  #可以填入多个类别如aj
    addlist:
      - "诶濛硷氽尛躝〇冇吔咗囧屌鲶芶咲畑垅𰻝𰻞龍朙"
    blacklist: []
  - option: s2t
    base: f
    addlist: []
    blacklist: []
  - option: s2hk
    base: h
    addlist: []
    blacklist: []
  - option: s2tw
    base: t
    addlist: []
    blacklist: []

⚙️超级替换(lua): super_replacer.lua一个通过lua创建的用来替代自带OpenCC组件的增强组件，用于实现候选词的动态替换、追加。

🛠️ Super Replacer 参数配置手册

1. 核心全局参数

参数	说明	示例值
`db_name`	数据库/词库加载路径	`lua/replacer`
`delimiter`	多个候选词之间的分隔符	`"\|"`
`comment_format`	注释显示的样式模板（`%s` 为占位符）	`"〔%s〕"`
`chain`	流水线模式：`true` 串行处理（A->B），`false` 并行处理	`true`

2. 任务项配置 (`types`)

每个 - option 代表一个具体的功能模块，其核心参数如下：

参数	说明	可选值 / 示例
`option`	绑定的开关名称（需在 `switches` 中定义）	`emoji`, `s2t`实际的开关名称 `true` (常驻开启)
`mode`	处理模式（决定结果如何呈现）	`append`, `replace`, `comment`, `abbrev`
`comment_mode`	注释继承模式	`none` (空), `append` (继承), `text` (原词变注释)
`sentence`	是否开启句子级别替换（整句转换）	`true`, `false`
`tags`	生效的输入段类型（通常对应拼音）	`[abc]`
`prefix`	数据检索前缀（用于隔离不同功能的数据）	`_em_`, `_en_`, `_abbr_`
`files`	关联的数据源文件列表（支持多个）	`[lua/data/xxx.txt]`

3. 四大模式 (`mode`) 详解

模式	行为描述	典型场景
`append`	新增候选：在原词后面添加新候选词	`哈哈` -> `1.哈哈 2.😄`
`replace`	替换原词：将原始候选词直接修改为目标词	`软件` -> `軟體` (简转繁)
`comment`	仅注释：不改变候选文字，仅在括号内提示	`hello` -> `hello〔你好〕`
`abbrev`	简码模式：匹配输入编码而非文本	`zm` (编码) -> `1.怎么 2.在吗`

4. 数据文件 (`.txt`) 编写规范

数据文件需放置于 files 指定路径，使用 Tab (制表符) 分隔：

匹配内容 [Tab] 替换内容1 | 替换内容2

举例：

火 🔥
apple 苹果
yyds 永远的神

⚙️手动排序（Lua）： ①词典候选类型：对选中的候选词操作，使用Ctrl+j向左一步，Ctrl+k向右一步，Ctrl+l(零)移除选中排序信息，Ctrl+p 置顶选中候选。其作用于当时编码与候选词；②动态生成的Lua候选，很多时候我们对日期、时间等输出格式首选有着自己的追求，复杂的配置又往往提升了使用难度，于是我们基于排序Lua实现了动态内容的按序号索引的排序，也就是说该序号下原本生成的格式整个发生了位置变化，使用方法一致。信息储存于Lua文件夹下排序数据库中sequence.userdb，支持导出导入数据便于多设备共用。

状态标识：按下ctrl键会显示数据库中已经储存的被移动过的候选，圆点-表示移动过但回到了原位，其他±各自代表移动的幅度与趋势。

排序信息同步：

A 先点击同步，多见于右键菜单，保证创建了相应的同步目录，如没有自定义则位于用户目录下/sync

打开用户目录，会有installation.yaml文件，打开后会有如下信息，我们将installation_id认为是设备id，初次会创建自动串号，你也可以将其修改为当前设备名称

distribution_code_name: "fcitx-rime"
distribution_name: Rime
distribution_version: 5.1.9
install_time: "Mon Jun 23 18:47:55 2025"
installation_id: "ff9b2823-8733-44bb-a497-daf382b74ca5"  #这里可以随意编辑，比如修改为windows
rime_version: 1.13.1
update_time: "Sat Sep  6 16:08:56 2025"

得到这个id后我们就可以下一步构建出同步文件的名称sequence_设备id.txt

首先确定一个主要管理设备，在/sync中创建一个描述设备清单的文件 sequence_device_list.txt，这个清单告诉程序要读取同目录下哪些文件进行合并

sequence_deepin.txt
sequence_windows.txt
sequence_iPhone.txt

按「部署」，会进行以下几步：

①、自动导出数据到 sequence_deepin.txt 文件(假设为当前设备)，因此这个当前设备文件会被覆盖，请不要手动修改避免丢失；

②、读取列表中列出的文件，按时序以保留最新动作为依据进行去重合并，合并后数据将会回写到 sequence_deepin.txt 文件；

③、将合并后的文件导入db数据库，完成数据合并，注意p=0的重置后的编码不会导入数据库，如数据库原本有对应的词汇，将删除对应的键。

通过云同步将/sync完成同步到windows设备，同步后，编辑 sequence_device_list.txt将sequence_windows.txt写入文件，让同步程序再次完成多端同步

此时目录中已经存在如下文件，此时重新部署，稍作等待将会完成sequence_windows.txt的输出

sequence_device_list.txt

sequence_deepin.txt

sequence_windows.txt #同步后新增

再次手动完成手动云同步，及时让文件对齐。

B 重复以上操作完成更多设备的添加和同步

由于此流程为模拟rime同步的方式，rime的同步本质上就是多端的数据合并的过程，可靠性可能相较于原生较弱一些，尤其是iPhone可能遇到更多问题。

⚙️声调辅助回退（Lua）： 万象是将7890用来代表1234声，轻声归并到了4，我们支持在例如输入ni9后发现我可能要4声，ni0，此时我们无需删除数字9而是直接输入对的0，类似手动在7890之间轮巡，能有效快速提升声调辅助的效率，减少使用负担，也是万象独创功能。

⚙️固定已经输入的语句（Lua）： 万象支持在输入中，通过按下F1锁定当前输入的候选，双击F1锁定上一个N-1句子长度记忆的句子，翻译成现实逻辑就是，我输入了四五个字了我发后面发生变化，我立马锁定，这样后续继续输入前面几乎不会跟着变了。如果我输入错了一个音节发现前面变了，此时双击F1相当于回溯了一个音节。，其原理实际上就是利用自动补齐每个字的双大写辅助码，起到定词定字的效果，为了避免编码区长度太长，我将连续的两个大写字母转换成一个向右趋势的视觉符号"›"该功能在输入中占用F1,用户自行修改位于force_upper_aux:下。

⚙️小键盘有妙用（Lua）： auto模式：可配置输入中数字跟在字母后面不上屏。compose模式：可配置数字持续不上屏，不用区分先后。select模式：小键盘行为对齐主键盘。

⚙️删除键限制（Lua）： 可以在输入中当持续按下删除编码为0时会卡住，抬起重新按下才能继续删除已经上屏内容，避免误删除上屏内容。目前仅PC可用，也是万象独创功能。

⚙️输入长度限制（Lua）： 对两类场景进行限制，避免数据并发卡顿：1、重复输入8个连续相同的字母，aaaaaaaa会提示:已超最大重复声母。因为连续多个的重复字母会造成严重的卡顿；2、分词片段限制在30个，也就是30个字，过长的语句价值不大还会造成卡顿。

⚙️Tab循环切换音节： 当输入多个字词时想要给前面补充辅助码，可以多次按下tab循环切换，这种可能比那些复杂的快捷键好用一些，同样逻辑的按键还包含ctrl+tab相当于逐字确认，错了可以补充编码，对了继续按下直到全部上屏；

⚙️**“候选切割机”（Lua）：** 这个功能是有候选的时候，通过按下ctrl+1~0中的10组组合键直接上屏首选前N个字，编码按现有音节分割后续编码保留，一般来说在输入句子的时候由于读音和构词的相似性，以及模型数据的偏差可能会出现错误的连续，这个时候恰当的切割让前面正确的直接上屏，残留的编码一般自动变为首选正确的选项了，此时上屏或继续切割或者使用tab补充编码。这个功能在base双拼中具备更高的确定性，而在pro版本中如果遇到直接辅助码的聚拢，那么此时候选估计与你初心不一致，此时可以考虑借助多次按下单引号来循环分词或许能得到你要的候选，如未得到直接esc重新输入更为高效。更为激进的用法直接上屏正确的部分，后面的编码直接遗弃，现在没有写进去，或许可以作为一个选项，如果你也像这样可以issue告诉我，我们可以改造成布尔选项；

⚙️翻译模式： 输入状态按下Ctrl+E快捷键进入翻译模式，原理是opencc查表进行中英文互译，能否翻译取决于词表的丰富度；

⚙️万能键斜杠/：

符号扩展输入： rime(大部分前端)是一种最小化ui的输入法，除了输入界面几乎看不到ui设置界面及符号表情面板的组件，因此我们在想要输入一些符号表情等特殊内容的时候会根据类型，设计一个触发条件，这个条件类似以什么编码开始作为标识、或者是某种tag状态。万象又是一个兼容多种输入类型的方案，我们无法找到一个绝对的空码字母作为触发条件，或多或少会冲突，因此我们选择了斜杠作为引导条件，例如/sx可以打出加减乘除等等，/yd可以打出圆点集合等等；
辅助码聚拢：我们在转写中将四个字母+/作为高权重的编码，意思就是侧重输入单字，而四个字母则采用abbrev，这种情况有词的情况有限出词，没词才会变成单字，毕竟我们是一个语句流方案，核心还是想输入多长就输入多长的类大厂习惯的输入法，因此单字就不能像字词音形方案那样四码定位一个字；
间接辅助码引导：直接辅助码我们是在四个编码末尾追加斜杠/，而间接辅助是在两个编码即双拼后面加斜杠，意思就是后面继续输入编码就能用辅助码对这个单字进行筛选，如果不加斜杠，就与正常的双拼无异，这时vs g=中国就能被打出来，不习惯直接辅助的可以选用这种方式；
短码英文前置：对于英文词典中我们常常遇到us以及United States这种缩写，那么在你水平一般的情况下输入两个字母前面可能是一大堆重要的中文词汇和单字，那么这个例子就显得不恰当了，不重要，这个时候输入us/就可以让us编码相关的英文词条前置，此时次选就是United States，有的时候是能输出对应大写，支持1-3个字母，因为但凡输入四个字母以上基本上会获得直接的前置了；
快符：输入一个单字母+/完成对应映射上屏，a/这样，还能定义某个按键是用来重复上屏之前的内容例如q/最终形成自己的习惯，原本分号引导包括数字都能用，但是分号太过珍贵，方案层面就不占用了；
上屏斜杠自己：通过双击斜杠直接上屏他自己；

⚙️按键设置思考：

我们说有舍有得，如何合理安排这些按键是一个重要课题，很多新手上来就要遵循自己以前的习惯，但那些习惯又何尝不是其他软件灌输给你的，我们何曾思考过合理性，对于rime不思考就定义不好，定义不好不如继续用大厂。对于万象斜杠/是不可能被挪作他用的，因此莫要针对这件事提问，修改的地方过多没有精力教学。反斜杠是顿号、分号有次选需求、引号要分词，中括号要以词定字，逗号句号在没有tips的时候更倾向于随语句一起上屏，节约按键，在有tips的时候句号在手机电脑上任何键盘大概率都能直接按，因此默认-=作为翻页，这与老祖宗ABC时期用法一样，某种程度7890代表的1234声调与-=凑在一起构成了一个筛选区，在重新选择rime作为输入法的时候我还是建议重新思考一下自己所谓的习惯

⚙️自定义短语： 将根目录中的custom_phrase.txt文本以表导入到rime，实现实际的编码对应你想要的输出，床前明月光\tcqm，其中\t代表制表符，不能输入的复制前面的行修改可见字符，尽量不要使用记事本编辑，换一个更高级的文本编辑器。这个功能主要用来短编码输入长短语、符号数字串等等各种需要置顶的内容，一定要根据万象的初始化在wanxiang.custom中修改名称避免更新被覆盖丢失数据。

⚙️自定义词库： 自定义词库首先要利用工具将你自己的词库刷成与万象同类型的声调、或者声调+辅助码的形态，因为主词库要参与转写。对于custom_phrase则需要手动编辑编码为实际输入的编码。

要保证每个字编码与chars完全一致，这是基础，不再赘述。

固定词库：

#packs法，要保证外部名称userxx.dict.yaml与里面name: userxx一致，

patch:
  translator/packs/+:
    - userxx

#重命名法，重命名用户根目录wanxiang.dict.yaml为wanxianguser.dict.yaml，避免更新被覆盖

#所有主方案文件中使用了这个固定词库的位置都要变更

patch:
  translator/dictionary: wanxianguser
  user_dict_set/dictionary: wanxianguser
  add_user_dict/dictionary: wanxianguser

用户词库迁移：

一个前置知识：同步是将用户词按时序合并导入导出的本地操作。

⚠️请不要将这个rime文件夹部署到同步软件下面，这将造成数据库被同步锁定无法正常工作，同步的最高级目录为/sync

确认你的同步目录，默认用户目录下面的/sync，如果自定义在installation.yaml文件中写入

linux\mac\android这样写：

sync_dir: "/home/amz/sync"

windows这样写：

sync_dir: "D:\\home\\amz\\sync"  #双引号
sync_dir: 'D:\home\amz\sync'     #单引号

你还可以将installation_id字段改成一个可辨识的名称如按系统命名

知道了这些以后你可以创建以下文件夹，他们的名称来自installation_id字段

xxx/sync/windows
xxx/sync/linux
xxx/sync/ios

你完全可以在用户目录看到wanxiang.userdb，他就是你实时工作的数据库PRO版本是zc.userdb，当你点击右键菜单，同步用户数据时

系统将会将用户词库以txt方式释放到xxx/sync/windows/wanxiang.userdb.txt

每一个wanxiang.userdb.txt表头都有一个表头

# Rime user dictionary
#@/db_name	zc
#@/db_type	userdb
#@/rime_version	1.13.1
#@/tick	793
#@/user_id	ff9b2823-8733-44bb-a497-daf382b74ca5

关注db_name必须与用户词典文件名一致，且不管多个设备不同设备文件夹下面的文件名称都应该一致，看起来都是wanxiang.userdb.txt

关注user_id=windows(设备文件夹名称)=installation_id字段必须保持一致

如果只有一个设备，你完全可以在同步后删除用户目录的userdb，手动编辑xxx/sync/windows/wanxiang.userdb.txt

注意这里的编辑必须是经过预处理格式与万象编码完全一致的情形下，万象提供的工具就可以完成声调标注和辅助码标注

编辑好文件，确保放入设备目录，点击同步即可导入数据库

你还可以将你迁移的数据txt内部设备名称都修改成linux，并将文件放入xxx/sync/linux

此时点击同步也能将用户词与windows文件夹下面的合并一起导入数据库，模拟多设备同步，这也是未来真正的多设备同步逻辑

词库刷拼音辅助码工具

⚙️万象双拼：

参考万象拼音得由来

生态

薄荷拼音 :使用万象词库的综合性方案，特别是其修改的地球拼音能够继承万象的词库声调编码。

鸢鸣万象 :一个基于万象拼音生态融合李氏三拼与辅助码能力的手机用方案。

万象虎 : 一个基于万象生态的虎码整句方案。

鸣谢

感谢网友的热情提报问题，使得模型和词库体验进一步提升。

赞赏

如果觉得项目好用，可以请AMZ喝咖啡

nvim-telescope/telescope.nvim

Find, Filter, Preview, Pick. All lua, all the time.

telescope.nvim

Gaze deeply into unknown regions using the power of the moon.

What Is Telescope?

telescope.nvim is a highly extendable fuzzy finder over lists. Built on the latest awesome features from neovim core. Telescope is centered around modularity, allowing for easy customization.

Community driven builtin pickers, sorters and previewers.

_{For more showcases of Telescope, please visit the Showcase section in the Telescope Wiki}

Telescope Table of Contents

Getting Started

This section should guide you to run your first builtin pickers.

Requirements

Neovim >=v0.11.7 built with LuaJIT (check :version).
nvim-lua/plenary.nvim.

Important

Only the latest version (stable) and the latest commit of HEAD (nightly) are tested and supported; before opening an issue, download the latest available release and confirm that the problem persists.

Recommended dependencies

BurntSushi/ripgrep is required for live_grep and grep_string and is the first priority for find_files.
sharkdp/fd (finder)
devicons (icons)

We also strongly suggest installing a native telescope sorter to significantly improve sorting performance:

telescope-fzf-native.nvim or
telescope-fzy-native.nvim. For more information and a performance benchmark take a look at the Extensions wiki.

Installation

We recommend pinning to the latest release tag, e.g. using lazy.nvim

{
    'nvim-telescope/telescope.nvim', version = '*',
    dependencies = {
        'nvim-lua/plenary.nvim',
        -- optional but recommended
        { 'nvim-telescope/telescope-fzf-native.nvim', build = 'make' },
    }
}

Checkhealth

Make sure you call :checkhealth telescope after installing telescope to ensure everything is set up correctly.

After this setup you can continue reading here or switch to :help telescope to get an understanding of how to use Telescope and how to configure it.

Usage

Try the command :Telescope find_files to see if telescope.nvim is installed correctly.

local builtin = require('telescope.builtin')
vim.keymap.set('n', '<leader>ff', builtin.find_files, { desc = 'Telescope find files' })
vim.keymap.set('n', '<leader>fg', builtin.live_grep, { desc = 'Telescope live grep' })
vim.keymap.set('n', '<leader>fb', builtin.buffers, { desc = 'Telescope buffers' })
vim.keymap.set('n', '<leader>fh', builtin.help_tags, { desc = 'Telescope help tags' })

See builtin pickers for a list of all builtin functions.

Customization

This section should help you explore available options to configure and customize your telescope.nvim.

Unlike most vim plugins, telescope.nvim can be customized by either applying customizations globally, or individually per picker.

Global Customization affecting all pickers can be done through the main setup() method (see defaults below)
Individual Customization affecting a single picker by passing opts to builtin pickers (e.g. builtin.find_files(opts)) see Configuration recipes wiki page for ideas.

Telescope setup structure

require('telescope').setup{
  defaults = {
    -- Default configuration for telescope goes here:
    -- config_key = value,
    mappings = {
      i = {
        -- map actions.which_key to <C-h> (default: <C-/>)
        -- actions.which_key shows the mappings for your picker,
        -- e.g. git_{create, delete, ...}_branch for the git_branches picker
        ["<C-h>"] = "which_key"
      }
    }
  },
  pickers = {
    -- Default configuration for builtin pickers goes here:
    -- picker_name = {
    --   picker_config_key = value,
    --   ...
    -- }
    -- Now the picker_config_key will be applied every time you call this
    -- builtin picker
  },
  extensions = {
    -- Your extension configuration goes here:
    -- extension_name = {
    --   extension_config_key = value,
    -- }
    -- please take a look at the readme of the extension you want to configure
  }
}

To look at what default configuration options exist please read: :help telescope.setup(). For picker specific opts please read: :help telescope.builtin.

To embed the above code snippet in a .vim file (for example in after/plugin/telescope.nvim.vim), wrap it in lua << EOF code-snippet EOF:

lua << EOF
require('telescope').setup{
  -- ...
}
EOF

Default Mappings

Mappings are fully customizable. Many familiar mapping patterns are set up as defaults.

Mappings	Action
`<C-n>/<Down>`	Next item
`<C-p>/<Up>`	Previous item
`j/k`	Next/previous (in normal mode)
`H/M/L`	Select High/Middle/Low (in normal mode)
`gg/G`	Select the first/last item (in normal mode)
`<CR>`	Confirm selection
`<C-x>`	Go to file selection as a split
`<C-v>`	Go to file selection as a vsplit
`<C-t>`	Go to a file in a new tab
`<C-u>`	Scroll up in preview window
`<C-d>`	Scroll down in preview window
`<C-f>`	Scroll left in preview window
`<C-k>`	Scroll right in preview window
`<M-f>`	Scroll left in results window
`<M-k>`	Scroll right in results window
`<C-/>`	Show mappings for picker actions (insert mode)
`?`	Show mappings for picker actions (normal mode)
`<C-c>`	Close telescope (insert mode)
`<Esc>`	Close telescope (in normal mode)
`<Tab>`	Toggle selection and move to next selection
`<S-Tab>`	Toggle selection and move to prev selection
`<C-q>`	Send all items not filtered to quickfixlist (qflist)
`<M-q>`	Send all selected items to qflist
`<C-r><C-w>`	Insert cword in original window into prompt (insert mode)
`<C-r><C-a>`	Insert cWORD in original window into prompt (insert mode)
`<C-r><C-f>`	Insert cfile in original window into prompt (insert mode)
`<C-r><C-l>`	Insert cline in original window into prompt (insert mode)

To see the full list of mappings, check out lua/telescope/mappings.lua and the default_mappings table.

Tip: you can use <C-/> and ? in insert and normal mode, respectively, to show the actions mapped to your picker.

Much like builtin pickers, there are a number of actions you can pick from to remap your telescope buffer mappings, or create a new custom action:

-- Built-in actions
local transform_mod = require('telescope.actions.mt').transform_mod

-- or create your custom action
local my_cool_custom_action = transform_mod({
  x = function(prompt_bufnr)
    print("This function ran after another action. Prompt_bufnr: " .. prompt_bufnr)
    -- Enter your function logic here. You can take inspiration from lua/telescope/actions.lua
  end,
})

To remap telescope mappings, please read :help telescope.defaults.mappings. To do picker specific mappings, its suggested to do this with the pickers table in telescope.setup. Each picker accepts a mappings table like its explained in :help telescope.defaults.mappings.

Pickers

Built-in functions. Ready to be bound to any key you like.

File Pickers

Functions	Description
`builtin.find_files`	Lists files in your current working directory, respects .gitignore
`builtin.git_files`	Fuzzy search through the output of `git ls-files` command, respects .gitignore
`builtin.grep_string`	Searches for the string under your cursor or selection in your current working directory
`builtin.live_grep`	Search for a string in your current working directory and get results live as you type, respects .gitignore. (Requires ripgrep)

Vim Pickers

Functions	Description
`builtin.buffers`	Lists open buffers in current neovim instance
`builtin.oldfiles`	Lists previously open files
`builtin.commands`	Lists available plugin/user commands and runs them on `<cr>`
`builtin.tags`	Lists tags in current directory with tag location file preview (users are required to run ctags -R to generate tags or update when introducing new changes)
`builtin.command_history`	Lists commands that were executed recently, and reruns them on `<cr>`
`builtin.search_history`	Lists searches that were executed recently, and reruns them on `<cr>`
`builtin.help_tags`	Lists available help tags and opens a new window with the relevant help info on `<cr>`
`builtin.man_pages`	Lists manpage entries, opens them in a help window on `<cr>`
`builtin.marks`	Lists vim marks and their value
`builtin.colorscheme`	Lists available colorschemes and applies them on `<cr>`
`builtin.quickfix`	Lists items in the quickfix list
`builtin.quickfixhistory`	Lists all quickfix lists in your history and open them with `builtin.quickfix` or quickfix window
`builtin.loclist`	Lists items from the current window's location list
`builtin.jumplist`	Lists Jump List entries
`builtin.vim_options`	Lists vim options, allows you to edit the current value on `<cr>`
`builtin.registers`	Lists vim registers, pastes the contents of the register on `<cr>`
`builtin.autocommands`	Lists vim autocommands and goes to their declaration on `<cr>`
`builtin.spell_suggest`	Lists spelling suggestions for the current word under the cursor, replaces word with selected suggestion on `<cr>`
`builtin.keymaps`	Lists normal mode keymappings
`builtin.filetypes`	Lists all available filetypes
`builtin.highlights`	Lists all available highlights
`builtin.current_buffer_fuzzy_find`	Live fuzzy search inside of the currently open buffer
`builtin.current_buffer_tags`	Lists all of the tags for the currently open buffer, with a preview
`builtin.resume`	Lists the results incl. multi-selections of the previous picker
`builtin.pickers`	Lists the previous pickers incl. multi-selections (see `:h telescope.defaults.cache_picker`)

Neovim LSP Pickers

Functions	Description
`builtin.lsp_references`	Lists LSP references for word under the cursor
`builtin.lsp_incoming_calls`	Lists LSP incoming calls for word under the cursor
`builtin.lsp_outgoing_calls`	Lists LSP outgoing calls for word under the cursor
`builtin.lsp_document_symbols`	Lists LSP document symbols in the current buffer
`builtin.lsp_workspace_symbols`	Lists LSP document symbols in the current workspace
`builtin.lsp_dynamic_workspace_symbols`	Dynamically Lists LSP for all workspace symbols
`builtin.diagnostics`	Lists Diagnostics for all open buffers or a specific buffer. Use option `bufnr=0` for current buffer.
`builtin.lsp_implementations`	Goto the implementation of the word under the cursor if there's only one, otherwise show all options in Telescope
`builtin.lsp_definitions`	Goto the definition of the word under the cursor, if there's only one, otherwise show all options in Telescope
`builtin.lsp_type_definitions`	Goto the definition of the type of the word under the cursor, if there's only one, otherwise show all options in Telescope

Git Pickers

Functions	Description
`builtin.git_commits`	Lists git commits with diff preview, checkout action `<cr>`, reset mixed `<C-r>m`, reset soft `<C-r>s` and reset hard `<C-r>h`
`builtin.git_bcommits`	Lists buffer's git commits with diff preview and checks them out on `<cr>`
`builtin.git_bcommits_range`	Lists buffer's git commits in a range of lines. Use options `from` and `to` to specify the range. In visual mode, lists commits for the selected lines
`builtin.git_branches`	Lists all branches with log preview, checkout action `<cr>`, track action `<C-t>`, rebase action`<C-r>`, create action `<C-a>`, switch action `<C-s>`, delete action `<C-d>` and merge action `<C-y>`
`builtin.git_status`	Lists current changes per file with diff preview and add action. (Multi-selection still WIP)
`builtin.git_stash`	Lists stash items in current repository with ability to apply them on `<cr>`

Treesitter Picker

Functions	Description
`builtin.treesitter`	Lists Function names, variables, ... using treesitter `locals` queries

Lists Picker

Functions	Description
`builtin.planets`	Use the telescope...
`builtin.builtin`	Lists Built-in pickers and run them on `<cr>`.
`builtin.reloader`	Lists Lua modules and reload them on `<cr>`.
`builtin.symbols`	Lists symbols inside a file `data/telescope-sources/*.json` found in your rtp. More info and symbol sources can be found here

Previewers

Previewers	Description
`previewers.vim_buffer_cat.new`	Default previewer for files. Uses vim buffers
`previewers.vim_buffer_vimgrep.new`	Default previewer for grep and similar. Uses vim buffers
`previewers.vim_buffer_qflist.new`	Default previewer for qflist. Uses vim buffers
`previewers.cat.new`	Terminal previewer for files. Uses `cat`/`bat`
`previewers.vimgrep.new`	Terminal previewer for grep and similar. Uses `cat`/`bat`
`previewers.qflist.new`	Terminal previewer for qflist. Uses `cat`/`bat`

The default previewers are from now on vim_buffer_ previewers. They use vim buffers for displaying files and use tree-sitter or regex for file highlighting.

These previewers are using vim.filetype to guess the filetype for the selected file. The guessing is done by inspecting the filename, the head of the file(shebang) and the tail of the file (modeline). If you have trouble with filetype detection you should read :help vim.filetype.

We need to do it manually because we can't determine the filetype in the traditional way: We don't do bufload and instead read the file asynchronously with vim.uv.fs_ and attach only a highlighter; otherwise the speed of the previewer would slow down considerably.

If you want to configure the vim_buffer_ previewer (e.g. you want the line to wrap), do this:

vim.api.nvim_create_autocmd("User", {
  pattern = "TelescopePreviewerLoaded",
  callback = function(args)
    if args.data.filetype ~= "help" then
      vim.wo.number = true
    elseif args.data.bufname:match("*.csv") then
      vim.wo.wrap = false
    end
  end,
})

A data field is passed to the callback, which contains the filetype and the buffer name.

{
  title: string, # preview window title
  filetype: string,
  bufname: string,
}

Sorters

Sorters	Description
`sorters.get_fuzzy_file`	Telescope's default sorter for files
`sorters.get_generic_fuzzy_sorter`	Telescope's default sorter for everything else
`sorters.get_levenshtein_sorter`	Using Levenshtein distance algorithm (don't use 😄)
`sorters.get_fzy_sorter`	Using fzy algorithm
`sorters.fuzzy_with_index_bias`	Used to list stuff with consideration to when the item is added

A Sorter is called by the Picker on each item returned by the Finder. It returns a number, which is equivalent to the "distance" between the current prompt and the entry returned by a finder.

Layout (display)

Layout can be configured by choosing a specific layout_strategy and specifying a particular layout_config for that strategy. For more details on available strategies and configuration options, see :help telescope.layout.

Some options for configuring sizes in layouts are "resolvable". This means that they can take different forms, and will be interpreted differently according to which form they take. For example, if we wanted to set the width of a picker using the vertical layout strategy to 50% of the screen width, we would specify that width as 0.5, but if we wanted to specify the width to be exactly 80 characters wide, we would specify it as 80. For more details on resolving sizes, see :help telescope.resolve.

As an example, if we wanted to specify the layout strategy and width, but only for this instance, we could do something like:

require('telescope.builtin').find_files({layout_strategy='vertical',layout_config={width=0.5}})

If we wanted to change the width for every time we use the vertical layout strategy, we could add the following to our setup() call:

require('telescope').setup({
  defaults = {
    layout_config = {
      vertical = { width = 0.5 }
      -- other layout configuration here
    },
    -- other defaults configuration here
  },
  -- other configuration values here
})

Themes

Common groups of settings can be set up to allow for themes. We have some built in themes but are looking for more cool options.

Themes	Description
`themes.get_dropdown`	A list like centered list. dropdown
`themes.get_cursor`	A cursor relative list.
`themes.get_ivy`	Bottom panel overlay. Ivy #771

To use a theme, simply append it to a builtin function:

nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({}))<cr>
" Change an option
nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({ winblend = 10 }))<cr>

Or use with a command:

Telescope find_files theme=dropdown

Or you can configure it in the pickers table in telescope.setup:

require('telescope').setup{
  defaults = {
    -- ...
  },
  pickers = {
    find_files = {
      theme = "dropdown",
    }
  },
  extensions = {
    -- ...
  }
}

Themes should work with every telescope.builtin function. If you wish to make a theme, check out lua/telescope/themes.lua.

Vim Commands

All telescope.nvim functions are wrapped in vim commands for easy access, tab completions and setting options.

" Show all builtin pickers
:Telescope

" Tab completion
:Telescope |<tab>
:Telescope find_files

" Setting options
:Telescope find_files prompt_prefix=🔍

" If the option accepts a Lua table as its value, you can use, to connect each
" command string, e.g.: find_command, vimgrep_arguments are both options that
" accept a Lua table as a value. So, you can configure them on the command line
"like so:
:Telescope find_files find_command=rg,--ignore,--hidden,--files prompt_prefix=🔍

for more information and how to realize more complex commands please read :help telescope.command.

Autocmds

Telescope user autocmds:

Event	Description
`User TelescopeFindPre`	Do it before Telescope creates all the floating windows
`User TelescopePreviewerLoaded`	Do it after Telescope previewer window is created
`User TelescopeResumePost`	Do it after Telescope resume action is fully completed

Extensions

Telescope provides the capabilities to create & register extensions, which improves telescope in a variety of ways.

Some extensions provide integration with external tools, outside of the scope of builtins. Others provide performance enhancements by using compiled C and interfacing directly with Lua over LuaJIT's FFI library.

A list of community extensions can be found in the Extensions wiki. Always read the README of the extension you want to install, but here is a general overview of how most extensions work.

Loading extensions

To load an extension, use the load_extension function as shown in the example below:

-- This will load fzy_native and have it override the default file sorter
require('telescope').load_extension('fzy_native')

You may skip explicitly loading extensions (they will then be lazy-loaded), but tab completions will not be available right away.

Accessing pickers from extensions

Pickers from extensions are added to the :Telescope command under their respective name. For example:

" Run the `configurations` picker from nvim-dap
Telescope dap configurations

They can also be called directly from Lua:

-- Run the `configurations` picker from nvim-dap
require('telescope').extensions.dap.configurations()

API

For writing your own picker and for information about the API please read the Developers Documentation.

Media

Contributing

All contributions are welcome! Just open a pull request. Please read CONTRIBUTING.md

Related Projects

nvim-lua/plenary.nvim

plenary: full; complete; entire; absolute; unqualified. All the lua functions I don't want to write twice.

plenary.nvim

Important Notice

This repository is no longer actively maintained and will be officially archived soon.

Critical bugs may still be addressed until 2026-06-30
No new features will be added
Ongoing support should not be expected

All the lua functions I don't want to write twice.

plenary:

full; complete; entire; absolute; unqualified.

Note that this library is useless outside of Neovim since it requires Neovim functions. It should be usable with any recent version of Neovim though.

At the moment, it is very much in pre-alpha 😄 Expect changes to the way some functions are structured. I'm hoping to finish some document generators to provide better documentation for people to use and consume and then at some point we'll stabilize on a few more stable APIs.

Installation

Using plug:

Plug 'nvim-lua/plenary.nvim'

Using packer:

use "nvim-lua/plenary.nvim"

Modules

plenary.async

A Lua module for asynchronous programming using coroutines. This library is built on native lua coroutines and libuv. Coroutines make it easy to avoid callback hell and allow for easy cooperative concurrency and cancellation. Apart from allowing users to perform asynchronous io easily, this library also functions as an abstraction for coroutines.

Getting started

You can do

local async = require "plenary.async"

All other modules are automatically required and can be accessed by indexing async. You needn't worry about performance as this will require all the submodules lazily.

A quick example

Libuv luv provides this example of reading a file.

local uv = vim.loop

local read_file = function(path, callback)
  uv.fs_open(path, "r", 438, function(err, fd)
    assert(not err, err)
    uv.fs_fstat(fd, function(err, stat)
      assert(not err, err)
      uv.fs_read(fd, stat.size, 0, function(err, data)
        assert(not err, err)
        uv.fs_close(fd, function(err)
          assert(not err, err)
          callback(data)
        end)
      end)
    end)
  end)
end

We can write it using the library like this:

local a = require "plenary.async"

local read_file = function(path)
  local err, fd = a.uv.fs_open(path, "r", 438)
  assert(not err, err)

  local err, stat = a.uv.fs_fstat(fd)
  assert(not err, err)

  local err, data = a.uv.fs_read(fd, stat.size, 0)
  assert(not err, err)

  local err = a.uv.fs_close(fd)
  assert(not err, err)

  return data
end

Plugins using this

plenary.async_lib

Please use plenary.async instead. This was version 1 and is just here for compatibility reasons.

plenary.async.control.channel.oneshot

Creates a oneshot channel. It can only send data one time.

The sender is not async while the receiver is.

Example:

local a = require'plenary.async'
local tx, rx = a.control.channel.oneshot()

a.run(function()
    local ret = long_running_fn()
    tx(ret)
end)

local ret = rx()

plenary.async.control.channel.mpsc

Creates a multiple producer single consumer channel.

Example:

local a = require'plenary.async'
local sender, receiver = a.control.channel.mpsc()

a.run(function()
  sender.send(10)
  sender.send(20)
end)

a.run(function()
  sender.send(30)
  sender.send(40)
end)

for _ = 1, 4 do
  local value = receiver.recv()
  print('received:', value)
end

plenary.job

A Lua module to interact with system processes. Pass in your command, the desired args, env and cwd. Define optional callbacks for on_stdout, on_stderr and on_exit and start your Job.

Note: Each job has an empty environment.

local Job = require'plenary.job'

Job:new({
  command = 'rg',
  args = { '--files' },
  cwd = '/usr/bin',
  env = { ['a'] = 'b' },
  on_exit = function(j, return_val)
    print(return_val)
    print(j:result())
  end,
}):sync() -- or start()

plenary.path

A Lua module that implements a bunch of the things from pathlib from Python, so that paths are easy to work with.

plenary.scandir

plenary.scandir is fast recursive file operations. It is similar to unix find or fd in that it can do recursive scans over a given directory, or a set of directories.

It offers a wide range of opts for limiting the depth, show hidden and more. plenary.scan_dir can be ran synchronously and asynchronously and offers on_insert(file, typ) and on_exit(files) callbacks. on_insert(file, typ) is available for both while on_exit(files) is only available for async.

local scan = require'plenary.scandir'
scan.scan_dir('.', { hidden = true, depth = 2 })

This module also offers ls -la sync and async functions that will return a formated string for all files in the directory. Why? Just for fun

plenary.context_manager

Implements with and open just like in Python. For example:

local with = context_manager.with
local open = context_manager.open

local result = with(open("README.md"), function(reader)
  return reader:read()
end)

assert(result == "# plenary.nvim")

plenary.test_harness

:help plenary-test

Supports (simple) busted-style testing. It implements a mock-ed busted interface, that will allow you to run simple busted style tests in separate neovim instances.

To run the current spec file in a floating window, you can use the keymap <Plug>PlenaryTestFile. For example:

nmap <leader>t <Plug>PlenaryTestFile

In this case, the test is run with a minimal configuration, that includes in its runtimepath only plenary.nvim and the current working directory.

To run a whole directory from the command line, you could do something like:

nvim --headless -c "PlenaryBustedDirectory tests/plenary/ {options}"

Where the first argument is the directory you'd like to test. It will search for files with the pattern *_spec.lua and execute them in separate neovim instances.

Without second argument, PlenaryBustedDirectory is also run with a minimal configuration. Otherwise it is a Lua option table with the following fields:

nvim_cmd: specify the command to launch this neovim instance (defaults to vim.v.progpath)
init: specify an init.vim to use for this instance
minimal_init: as for init, but also run the neovim instance with --noplugin
sequential: whether to run tests sequentially (default is to run in parallel)
keep_going: if sequential, whether to continue on test failure (default true)
timeout: controls the maximum time allotted to each job in parallel or sequential operation (defaults to 50,000 milliseconds)

The exit code is 0 when success and 1 when fail, so you can use it easily in a Makefile!

NOTE:

So far, the only supported busted items are:

describe
it
pending
before_each
after_each
clear
assert.* etc. (from luassert, which is bundled)

OTHER NOTE:

We used to support luaunit and original busted but it turns out it was way too hard and not worthwhile for the difficulty of getting them setup, particularly on other platforms or in CI. Now, we have a dep free (or at least, no other installation steps necessary) busted implementation that can be used more easily.

Please take a look at the new APIs and make any issues for things that aren't clear. I am happy to fix them and make it work well 😃

OTHER OTHER NOTE: Take a look at some test examples here.

Colors

You no longer need nvim-terminal to get this to work. We use nvim_open_term now.

plenary.filetype

Will detect the filetype based on extension/special filename/shebang or modeline

require'plenary.filetype'.detect(filepath, opts) is a function that does all of above and exits as soon as a filetype is found
require'plenary.filetype'.detect_from_extension(filepath)
require'plenary.filetype'.detect_from_name(filepath)
require'plenary.filetype'.detect_from_modeline(filepath)
require'plenary.filetype'.detect_from_shebang(filepath)

Add filetypes by creating a new file named ~/.config/nvim/data/plenary/filetypes/foo.lua and register that file with :lua require'plenary.filetype'.add_file('foo'). Content of the file should look like that:

return {
  extension = {
    -- extension = filetype
    -- example:
    ['jl'] = 'julia',
  },
  file_name = {
    -- special filenames, likes .bashrc
    -- we provide a decent amount
    -- name = filetype
    -- example:
    ['.bashrc'] = 'bash',
  },
  shebang = {
    -- Shebangs are supported as well. Currently we provide
    -- sh, bash, zsh, python, perl with different prefixes like
    -- /usr/bin, /bin/, /usr/bin/env, /bin/env
    -- shebang = filetype
    -- example:
    ['/usr/bin/node'] = 'javascript',
  }
}

plenary.strings

Re-implement VimL funcs to use them in Lua loop.

strings.strdisplaywidth
strings.strcharpart

And some other funcs are here to deal with common problems.

strings.truncate
strings.align_str
strings.dedent

plenary.profile

Thin wrapper around LuaJIT's jit.p profiler.

require'plenary.profile'.start("profile.log")

-- code to be profiled

require'plenary.profile'.stop()

You can use start("profile.log", {flame = true}) to output the log in a flamegraph-compatible format. A flamegraph can be created from this using https://github.com/jonhoo/inferno via

inferno-flamegraph profile.log > flame.svg

The resulting interactive SVG file can be viewed in any browser.

Status: WIP

plenary.popup

See popup documentation for both progress tracking and implemented APIs.

plenary.window

Window helper functions to wrap some of the more difficult cases. Particularly for floating windows.

Status: WIP

plenary.collections

Contains pure lua implementations for various standard collections.

local List = require 'plenary.collections.py_list'

local myList = List { 9, 14, 32, 5 }

for i, v in myList:iter() do
    print(i, v)
end

Status: WIP

Troubleshooting

If you're having trouble / things are hanging / other problems:

$ export DEBUG_PLENARY=true

This will enable debugging for the plugin.

plenary.neorocks

DELETED: Please use packer.nvim or other lua-rocks wrapper instead. This no longer exists.

FAQ

Error: Too many open files

*nix systems have a setting to configure the maximum amount of open file handles. It can occur that the default value is pretty low and that you end up getting this error after opening a couple of files. On Linux you can see the current limit with ulimit -n and set it with ulimit -n 4096. If you're on macOS the command is sudo launchctl limit maxfiles 4096 4096.

MeanderingProgrammer/render-markdown.nvim

Plugin to improve viewing Markdown files in Neovim

render-markdown.nvim

Plugin to improve viewing Markdown files in Neovim

Screenshot	Video

Features

Contained: runs entirely inside Neovim with no external windows
Configurable: all components, padding, icons, and colors can be modified
File type agnostic: can render markdown injected into any file
- Automatically runs on lazy load file types defined in lazy.nvim ft
Injections: can directly manipulate treesitter to add logical markdown sections
Modal rendering: changes between rendered and raw view based on mode
Anti-conceal: hides virtual text added by this plugin on cursor line
Window options: changes option values between rendered and raw view
Large files: only renders visible range, can be entirely disabled based on size
Custom rendering: provides extension point where user can add anything
Renders the following markdown components out of the box:
- Headings: icon, color, border, padding ^[1], width
- Code blocks: background, language icon ^[1:1] ^[2], border, padding ^[1:2], width
- Code inline: background
- Horizontal breaks: icon, color, width
- List bullets: icon, color, padding ^[1:3]
- Checkboxes: icon, color, user defined states
- Block quotes: icon, color, line breaks ^[1:4]
- Callouts: icon, color, user defined values, Github & Obsidian defaults
- Tables: border, color, alignment indicator, auto align cells ^[1:5]
- Links ^[1:6]: icon, color, user defined destinations
- Latex blocks ^[3]: renders formulas
- Org indent mode ^[1:7]: per level padding

Requirements

Neovim >= 0.9.0 (minimum) >= 0.10.0 (recommended)
Nerd font symbols: more details
treesitter parsers:
- markdown & markdown_inline: Used to parse markdown files
- html (Optional): Used to conceal HTML comments
- latex (Optional): Used to get latex blocks from markdown files
- yaml (Optional): Used to render elements in frontmatter metadata
Icon provider plugin (Optional): Used for icon above code blocks
- mini.icons
- nvim-web-devicons
System dependencies:
- libtexprintf (Optional): Used to transform latex strings to appropriate unicode using utftex
- pylatexenc (Optional): Used to transform latex strings to appropriate unicode using latex2text

Install

vim.pack

vim.pack.add({
    'https://github.com/nvim-treesitter/nvim-treesitter',
    'https://github.com/nvim-mini/mini.nvim',            -- if you use the mini.nvim suite
    -- 'https://github.com/nvim-mini/mini.icons',        -- if you use standalone mini plugins
    -- 'https://github.com/nvim-tree/nvim-web-devicons', -- if you prefer nvim-web-devicons
    'https://github.com/MeanderingProgrammer/render-markdown.nvim',
})
require('render-markdown').setup({}) -- only mandatory if you want to set custom options

lazy.nvim

{
    'MeanderingProgrammer/render-markdown.nvim',
    dependencies = { 'nvim-treesitter/nvim-treesitter', 'nvim-mini/mini.nvim' },            -- if you use the mini.nvim suite
    -- dependencies = { 'nvim-treesitter/nvim-treesitter', 'nvim-mini/mini.icons' },        -- if you use standalone mini plugins
    -- dependencies = { 'nvim-treesitter/nvim-treesitter', 'nvim-tree/nvim-web-devicons' }, -- if you prefer nvim-web-devicons
    ---@module 'render-markdown'
    ---@type render.md.UserConfig
    opts = {},
}

rocks.nvim

This plugin is available on LuaRocks

:Rocks install render-markdown.nvim

packer.nvim

use({
    'MeanderingProgrammer/render-markdown.nvim',
    after = { 'nvim-treesitter' },
    requires = { 'nvim-mini/mini.nvim', opt = true },            -- if you use the mini.nvim suite
    -- requires = { 'nvim-mini/mini.icons', opt = true },        -- if you use standalone mini plugins
    -- requires = { 'nvim-tree/nvim-web-devicons', opt = true }, -- if you prefer nvim-web-devicons
    config = function()
        require('render-markdown').setup({})
    end,
})

Commands

Command	Lua Function	Description
`:RenderMarkdown`	`require('render-markdown').enable()`	Alias for `enable`
`:RenderMarkdown enable`	`require('render-markdown').enable()`	Alias for `set(true)`
`:RenderMarkdown buf_enable`	`require('render-markdown').buf_enable()`	Alias for `set_buf(true)`
`:RenderMarkdown disable`	`require('render-markdown').disable()`	Alias for `set(false)`
`:RenderMarkdown buf_disable`	`require('render-markdown').buf_disable()`	Alias for `set_buf(false)`
`:RenderMarkdown toggle`	`require('render-markdown').toggle()`	Alias for `set()`
`:RenderMarkdown buf_toggle`	`require('render-markdown').buf_toggle()`	Alias for `set_buf()`
`:RenderMarkdown get`	`require('render-markdown').get()`	Return current state
`:RenderMarkdown set bool?`	`require('render-markdown').set(bool?)`	Sets state, `nil` to toggle
`:RenderMarkdown set_buf bool?`	`require('render-markdown').set_buf(bool?)`	Sets state for current buffer, `nil` to toggle
`:RenderMarkdown preview`	`require('render-markdown').preview()`	Show rendered buffer to the side
`:RenderMarkdown log`	`require('render-markdown').log()`	Opens the log file for this plugin
`:RenderMarkdown expand`	`require('render-markdown').expand()`	Increase anti-conceal margin above and below by 1
`:RenderMarkdown contract`	`require('render-markdown').contract()`	Decrease anti-conceal margin above and below by 1
`:RenderMarkdown debug`	`require('render-markdown').debug()`	Prints information about marks on current line
`:RenderMarkdown config`	`require('render-markdown').config()`	Prints difference between config and default

Completions

This plugin provides completions for both checkboxes and callouts provided you follow the relevant setup.

in-process lsp

The recommended way of getting completions from this plugin. Only requires being enabled with no additional configuration, assuming you have general LSP completions.

Works automatically with nvim-cmp and blink.cmp.

require('render-markdown').setup({
    completions = { lsp = { enabled = true } },
})

coq_nvim

require('render-markdown').setup({
    completions = { coq = { enabled = true } },
})

Setup

Checkout the Wiki for examples and images associated with different configuration options.

The full default configuration is provided below for reference.

Any part of it can be modified however for many fields this does not make much sense.

Some of the more useful fields are discussed further down.

Default Configuration

require('render-markdown').setup({
    -- Whether markdown should be rendered by default.
    enabled = true,
    -- Vim modes that will show a rendered view of the markdown file, :h mode(), for all enabled
    -- components. Individual components can be enabled for other modes. Remaining modes will be
    -- unaffected by this plugin.
    render_modes = { 'n', 'c', 't' },
    -- Milliseconds that must pass before updating marks, updates occur.
    -- within the context of the visible window, not the entire buffer.
    debounce = 100,
    -- Pre configured settings that will attempt to mimic various target user experiences.
    -- User provided settings will take precedence.
    -- | obsidian | mimic Obsidian UI                                          |
    -- | lazy     | will attempt to stay up to date with LazyVim configuration |
    -- | none     | does nothing                                               |
    preset = 'none',
    -- The level of logs to write to file: vim.fn.stdpath('state') .. '/render-markdown.log'.
    -- Only intended to be used for plugin development / debugging.
    log_level = 'error',
    -- Print runtime of main update method.
    -- Only intended to be used for plugin development / debugging.
    log_runtime = false,
    -- Filetypes this plugin will run on.
    file_types = { 'markdown' },
    -- Maximum file size (in MB) that this plugin will attempt to render.
    -- File larger than this will effectively be ignored.
    max_file_size = 10.0,
    -- Takes buffer as input, if it returns true this plugin will not attach to the buffer.
    ignore = function()
        return false
    end,
    -- Whether markdown should be rendered when nested inside markdown, i.e. markdown code block
    -- inside markdown file.
    nested = true,
    -- Additional events that will trigger this plugin's render loop.
    change_events = {},
    -- Whether the treesitter highlighter should be restarted after this plugin attaches to its
    -- first buffer for the first time. May be necessary if this plugin is lazy loaded to clear
    -- highlights that have been dynamically disabled.
    restart_highlighter = false,
    injections = {
        -- Out of the box language injections for known filetypes that allow markdown to be interpreted
        -- in specified locations, see :h treesitter-language-injections.
        -- Set enabled to false in order to disable.

        gitcommit = {
            enabled = true,
            query = [[
                ((message) @injection.content
                    (#set! injection.combined)
                    (#set! injection.include-children)
                    (#set! injection.language "markdown"))
            ]],
        },
    },
    patterns = {
        -- Highlight patterns to disable for filetypes, i.e. lines concealed around code blocks

        markdown = {
            disable = true,
            directives = {
                { id = 17, name = 'conceal_lines' },
                { id = 18, name = 'conceal_lines' },
            },
        },
    },
    anti_conceal = {
        -- This enables hiding added text on the line the cursor is on.
        enabled = true,
        -- Modes to disable anti conceal feature.
        disabled_modes = false,
        -- Number of lines above cursor to show.
        above = 0,
        -- Number of lines below cursor to show.
        below = 0,
        -- Which elements to always show, ignoring anti conceal behavior. Values can either be
        -- booleans to fix the behavior or string lists representing modes where anti conceal
        -- behavior will be ignored. Valid values are:
        --   bullet
        --   callout
        --   check_icon, check_scope
        --   code_background, code_border, code_language
        --   dash
        --   head_background, head_border, head_icon
        --   indent
        --   latex
        --   link
        --   quote
        --   sign
        --   table_border
        --   virtual_lines
        ignore = {
            code_background = true,
            indent = true,
            sign = true,
            virtual_lines = true,
        },
    },
    padding = {
        -- Highlight to use when adding whitespace, should match background.
        highlight = 'Normal',
    },
    latex = {
        -- Turn on / off latex rendering.
        enabled = true,
        -- Additional modes to render latex.
        render_modes = false,
        -- Executable used to convert latex formula to rendered unicode.
        -- If a list is provided the commands run in order until the first success.
        converter = { 'utftex', 'latex2text' },
        -- Highlight for latex blocks.
        highlight = 'RenderMarkdownMath',
        -- Determines where latex formula is rendered relative to block.
        -- | above  | above latex block                               |
        -- | below  | below latex block                               |
        -- | center | centered with latex block (must be single line) |
        position = 'center',
        -- Number of empty lines above latex blocks.
        top_pad = 0,
        -- Number of empty lines below latex blocks.
        bottom_pad = 0,
    },
    on = {
        -- Called when plugin initially attaches to a buffer.
        attach = function() end,
        -- Called before adding marks to the buffer for the first time.
        initial = function() end,
        -- Called after plugin renders a buffer.
        render = function() end,
        -- Called after plugin clears a buffer.
        clear = function() end,
    },
    completions = {
        -- Settings for blink.cmp completions source
        blink = { enabled = false },
        -- Settings for coq_nvim completions source
        coq = { enabled = false },
        -- Settings for in-process language server completions
        lsp = { enabled = false },
        filter = {
            callout = function()
                -- example to exclude obsidian callouts
                -- return value.category ~= 'obsidian'
                return true
            end,
            checkbox = function()
                return true
            end,
        },
    },
    heading = {
        -- Useful context to have when evaluating values.
        -- | level    | the number of '#' in the heading marker         |
        -- | sections | for each level how deeply nested the heading is |

        -- Turn on / off heading icon & background rendering.
        enabled = true,
        -- Additional modes to render headings.
        render_modes = false,
        -- Turn on / off atx heading rendering.
        atx = true,
        -- Turn on / off setext heading rendering.
        setext = true,
        -- Turn on / off sign column related rendering.
        sign = true,
        -- Replaces '#+' of 'atx_h._marker'.
        -- Output is evaluated depending on the type.
        -- | function | `value(context)`              |
        -- | string[] | `cycle(value, context.level)` |
        icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
        -- Determines how icons fill the available space.
        -- | eol     | '#'s are concealed and icon is placed at right most column   |
        -- | right   | '#'s are concealed and icon is appended to right side        |
        -- | inline  | '#'s are concealed and icon is inlined on left side          |
        -- | overlay | icon is left padded with spaces and overlayed hiding all '#' |
        position = 'overlay',
        -- Added to the sign column if enabled.
        -- Output is evaluated by `cycle(value, context.level)`.
        signs = { '󰫎 ' },
        -- Width of the heading background.
        -- | block | width of the heading text |
        -- | full  | full width of the window  |
        -- Can also be a list of the above values evaluated by `clamp(value, context.level)`.
        width = 'full',
        -- Amount of margin to add to the left of headings.
        -- Margin available space is computed after accounting for padding.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        -- Can also be a list of numbers evaluated by `clamp(value, context.level)`.
        left_margin = 0,
        -- Amount of padding to add to the left of headings.
        -- Output is evaluated using the same logic as 'left_margin'.
        left_pad = 0,
        -- Amount of padding to add to the right of headings when width is 'block'.
        -- Output is evaluated using the same logic as 'left_margin'.
        right_pad = 0,
        -- Minimum width to use for headings when width is 'block'.
        -- Can also be a list of integers evaluated by `clamp(value, context.level)`.
        min_width = 0,
        -- Determines if a border is added above and below headings.
        -- Can also be a list of booleans evaluated by `clamp(value, context.level)`.
        border = false,
        -- Always use virtual lines for heading borders instead of attempting to use empty lines.
        border_virtual = false,
        -- Highlight the start of the border using the foreground highlight.
        border_prefix = false,
        -- Used above heading for border.
        above = '▄',
        -- Used below heading for border.
        below = '▀',
        -- Highlight for the heading icon and extends through the entire line.
        -- Output is evaluated by `clamp(value, context.level)`.
        backgrounds = {
            'RenderMarkdownH1Bg',
            'RenderMarkdownH2Bg',
            'RenderMarkdownH3Bg',
            'RenderMarkdownH4Bg',
            'RenderMarkdownH5Bg',
            'RenderMarkdownH6Bg',
        },
        -- Highlight for the heading and sign icons.
        -- Output is evaluated using the same logic as 'backgrounds'.
        foregrounds = {
            'RenderMarkdownH1',
            'RenderMarkdownH2',
            'RenderMarkdownH3',
            'RenderMarkdownH4',
            'RenderMarkdownH5',
            'RenderMarkdownH6',
        },
        -- Define custom heading patterns which allow you to override various properties based on
        -- the contents of a heading.
        -- The key is for healthcheck and to allow users to change its values, value type below.
        -- | pattern    | matched against the heading text @see :h lua-patterns |
        -- | icon       | optional override for the icon                        |
        -- | background | optional override for the background                  |
        -- | foreground | optional override for the foreground                  |
        custom = {},
    },
    paragraph = {
        -- Useful context to have when evaluating values.
        -- | text | text value of the node |

        -- Turn on / off paragraph rendering.
        enabled = true,
        -- Additional modes to render paragraphs.
        render_modes = false,
        -- Amount of margin to add to the left of paragraphs.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        -- Output is evaluated depending on the type.
        -- | function | `value(context)` |
        -- | number   | `value`          |
        left_margin = 0,
        -- Amount of padding to add to the first line of each paragraph.
        -- Output is evaluated using the same logic as 'left_margin'.
        indent = 0,
        -- Minimum width to use for paragraphs.
        min_width = 0,
    },
    code = {
        -- Turn on / off code block & inline code rendering.
        enabled = true,
        -- Additional modes to render code blocks.
        render_modes = false,
        -- Turn on / off sign column related rendering.
        sign = true,
        -- Whether to conceal nodes at the top and bottom of code blocks.
        conceal_delimiters = true,
        -- Turn on / off language heading related rendering.
        language = true,
        -- Determines where language icon is rendered.
        -- | center | center of code block |
        -- | right  | right of code block  |
        -- | left   | left of code block   |
        position = 'left',
        -- Whether to include the language icon above code blocks.
        language_icon = true,
        -- Whether to include the language name above code blocks.
        language_name = true,
        -- Whether to include the language info above code blocks.
        language_info = true,
        -- Amount of padding to add around the language.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        language_pad = 0,
        -- A list of language names for which rendering will be disabled.
        disable = {},
        -- A list of language names for which background highlighting will be disabled.
        -- Likely because that language has background highlights itself.
        -- Use a boolean to make behavior apply to all languages.
        -- Borders above & below blocks will continue to be rendered.
        disable_background = { 'diff' },
        -- Width of the code block background.
        -- | block | width of the code block  |
        -- | full  | full width of the window |
        width = 'full',
        -- Amount of margin to add to the left of code blocks.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        -- Margin available space is computed after accounting for padding.
        left_margin = 0,
        -- Amount of padding to add to the left of code blocks.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        left_pad = 0,
        -- Amount of padding to add to the right of code blocks when width is 'block'.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        right_pad = 0,
        -- Minimum width to use for code blocks when width is 'block'.
        min_width = 0,
        -- Determines how the top / bottom of code block are rendered.
        -- | none  | do not render a border                               |
        -- | thick | use the same highlight as the code body              |
        -- | thin  | when lines are empty overlay the above & below icons |
        -- | hide  | conceal lines unless language name or icon is added  |
        border = 'hide',
        -- Used above code blocks to fill remaining space around language.
        language_border = '█',
        -- Added to the left of language.
        language_left = '',
        -- Added to the right of language.
        language_right = '',
        -- Used above code blocks for thin border.
        above = '▄',
        -- Used below code blocks for thin border.
        below = '▀',
        -- Turn on / off inline code related rendering.
        inline = true,
        -- Icon to add to the left of inline code.
        inline_left = '',
        -- Icon to add to the right of inline code.
        inline_right = '',
        -- Padding to add to the left & right of inline code.
        inline_pad = 0,
        -- Priority to assign to code background highlight.
        priority = 140,
        -- Highlight for code blocks.
        highlight = 'RenderMarkdownCode',
        -- Highlight for code info section, after the language.
        highlight_info = 'RenderMarkdownCodeInfo',
        -- Highlight for language, overrides icon provider value.
        highlight_language = nil,
        -- Highlight for border, use false to add no highlight.
        highlight_border = 'RenderMarkdownCodeBorder',
        -- Highlight for language, used if icon provider does not have a value.
        highlight_fallback = 'RenderMarkdownCodeFallback',
        -- Highlight for inline code.
        highlight_inline = 'RenderMarkdownCodeInline',
        -- Highlight for inline code left icon, default to reverse of highlight_inline.
        highlight_inline_left = nil,
        -- Highlight for inline code right icon, default to reverse of highlight_inline.
        highlight_inline_right = nil,
        -- Determines how code blocks & inline code are rendered.
        -- | none     | { enabled = false }                           |
        -- | normal   | { language = false }                          |
        -- | language | { disable_background = true, inline = false } |
        -- | full     | uses all default values                       |
        style = 'full',
    },
    dash = {
        -- Useful context to have when evaluating values.
        -- | width | width of the current window |

        -- Turn on / off thematic break rendering.
        enabled = true,
        -- Additional modes to render dash.
        render_modes = false,
        -- Replaces '---'|'***'|'___'|'* * *' of 'thematic_break'.
        -- The icon gets repeated across the window's width.
        icon = '─',
        -- Width of the generated line.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        -- Output is evaluated depending on the type.
        -- | function | `value(context)`    |
        -- | number   | `value`             |
        -- | full     | width of the window |
        width = 'full',
        -- Amount of margin to add to the left of dash.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        left_margin = 0,
        -- Priority to assign to dash.
        priority = nil,
        -- Highlight for the whole line generated from the icon.
        highlight = 'RenderMarkdownDash',
    },
    document = {
        -- Turn on / off document rendering.
        enabled = true,
        -- Additional modes to render document.
        render_modes = false,
        -- Ability to conceal arbitrary ranges of text based on lua patterns, @see :h lua-patterns.
        -- Relies entirely on user to set patterns that handle their edge cases.
        conceal = {
            -- Matched ranges will be concealed using character level conceal.
            char_patterns = {},
            -- Matched ranges will be concealed using line level conceal.
            line_patterns = {},
        },
    },
    bullet = {
        -- Useful context to have when evaluating values.
        -- | level | how deeply nested the list is, 1-indexed          |
        -- | index | how far down the item is at that level, 1-indexed |
        -- | value | text value of the marker node                     |

        -- Turn on / off list bullet rendering
        enabled = true,
        -- Additional modes to render list bullets
        render_modes = false,
        -- Replaces '-'|'+'|'*' of 'list_item'.
        -- If the item is a 'checkbox' a conceal is used to hide the bullet instead.
        -- Output is evaluated depending on the type.
        -- | function   | `value(context)`                                    |
        -- | string     | `value`                                             |
        -- | string[]   | `cycle(value, context.level)`                       |
        -- | string[][] | `clamp(cycle(value, context.level), context.index)` |
        icons = { '●', '○', '◆', '◇' },
        -- Replaces 'n.'|'n)' of 'list_item'.
        -- Output is evaluated using the same logic as 'icons'.
        ordered_icons = function(ctx)
            local value = vim.trim(ctx.value)
            local index = tonumber(value:sub(1, #value - 1))
            return ('%d.'):format(index > 1 and index or ctx.index)
        end,
        -- Padding to add to the left of bullet point.
        -- Output is evaluated depending on the type.
        -- | function | `value(context)` |
        -- | integer  | `value`          |
        left_pad = 0,
        -- Padding to add to the right of bullet point.
        -- Output is evaluated using the same logic as 'left_pad'.
        right_pad = 0,
        -- Highlight for the bullet icon.
        -- Output is evaluated using the same logic as 'icons'.
        highlight = 'RenderMarkdownBullet',
        -- Highlight for item associated with the bullet point.
        -- Output is evaluated using the same logic as 'icons'.
        scope_highlight = {},
        -- Priority to assign to scope highlight.
        scope_priority = nil,
    },
    checkbox = {
        -- Checkboxes are a special instance of a 'list_item' that start with a 'shortcut_link'.
        -- There are two special states for unchecked & checked defined in the markdown grammar.

        -- Turn on / off checkbox state rendering.
        enabled = true,
        -- Additional modes to render checkboxes.
        render_modes = false,
        -- Render the bullet point before the checkbox.
        bullet = false,
        -- Padding to add to the left of checkboxes.
        left_pad = 0,
        -- Padding to add to the right of checkboxes.
        right_pad = 1,
        unchecked = {
            -- Replaces '[ ]' of 'task_list_marker_unchecked'.
            icon = '󰄱 ',
            -- Highlight for the unchecked icon.
            highlight = 'RenderMarkdownUnchecked',
            -- Highlight for item associated with unchecked checkbox.
            scope_highlight = nil,
        },
        checked = {
            -- Replaces '[x]' of 'task_list_marker_checked'.
            icon = '󰱒 ',
            -- Highlight for the checked icon.
            highlight = 'RenderMarkdownChecked',
            -- Highlight for item associated with checked checkbox.
            scope_highlight = nil,
        },
        -- Define custom checkbox states, more involved, not part of the markdown grammar.
        -- As a result this requires neovim >= 0.10.0 since it relies on 'inline' extmarks.
        -- The key is for healthcheck and to allow users to change its values, value type below.
        -- | raw             | matched against the raw text of a 'shortcut_link'           |
        -- | rendered        | replaces the 'raw' value when rendering                     |
        -- | highlight       | highlight for the 'rendered' icon                           |
        -- | scope_highlight | optional highlight for item associated with custom checkbox |
        -- stylua: ignore
        custom = {
            todo = { raw = '[-]', rendered = '󰥔 ', highlight = 'RenderMarkdownTodo', scope_highlight = nil },
        },
        -- Priority to assign to scope highlight.
        scope_priority = nil,
    },
    quote = {
        -- Turn on / off block quote & callout rendering.
        enabled = true,
        -- Additional modes to render quotes.
        render_modes = false,
        -- Replaces '>' of 'block_quote'.
        icon = '▋',
        -- Whether to repeat icon on wrapped lines. Requires neovim >= 0.10. This will obscure text
        -- if incorrectly configured with :h 'showbreak', :h 'breakindent' and :h 'breakindentopt'.
        -- A combination of these that is likely to work follows.
        -- | showbreak      | '  ' (2 spaces)   |
        -- | breakindent    | true              |
        -- | breakindentopt | '' (empty string) |
        -- These are not validated by this plugin. If you want to avoid adding these to your main
        -- configuration then set them in win_options for this plugin.
        repeat_linebreak = false,
        -- Highlight for the quote icon.
        -- If a list is provided output is evaluated by `cycle(value, level)`.
        highlight = {
            'RenderMarkdownQuote1',
            'RenderMarkdownQuote2',
            'RenderMarkdownQuote3',
            'RenderMarkdownQuote4',
            'RenderMarkdownQuote5',
            'RenderMarkdownQuote6',
        },
    },
    pipe_table = {
        -- Turn on / off pipe table rendering.
        enabled = true,
        -- Additional modes to render pipe tables.
        render_modes = false,
        -- Pre configured settings largely for setting table border easier.
        -- | heavy  | use thicker border characters     |
        -- | double | use double line border characters |
        -- | round  | use round border corners          |
        -- | none   | does nothing                      |
        preset = 'none',
        -- Determines how individual cells of a table are rendered.
        -- | overlay | writes completely over the table, removing conceal behavior and highlights |
        -- | raw     | replaces only the '|' characters in each row, leaving the cells unmodified |
        -- | padded  | raw + cells are padded to maximum visual width for each column             |
        -- | trimmed | padded except empty space is subtracted from visual width calculation      |
        cell = 'padded',
        -- Adjust the computed width of table cells using custom logic.
        cell_offset = function()
            return 0
        end,
        -- Amount of space to put between cell contents and border.
        padding = 1,
        -- Minimum column width to use for padded or trimmed cell.
        min_width = 0,
        -- Characters used to replace table border.
        -- Correspond to top(3), delimiter(3), bottom(3), vertical, & horizontal.
        -- stylua: ignore
        border = {
            '┌', '┬', '┐',
            '├', '┼', '┤',
            '└', '┴', '┘',
            '│', '─',
        },
        -- Turn on / off top & bottom lines.
        border_enabled = true,
        -- Always use virtual lines for table borders instead of attempting to use empty lines.
        -- Will be automatically enabled if indentation module is enabled.
        border_virtual = false,
        -- Gets placed in delimiter row for each column, position is based on alignment.
        alignment_indicator = '━',
        -- Highlight for table heading, delimiter, and the line above.
        head = 'RenderMarkdownTableHead',
        -- Highlight for everything else, main table rows and the line below.
        row = 'RenderMarkdownTableRow',
        -- Determines how the table as a whole is rendered.
        -- | none   | { enabled = false }        |
        -- | normal | { border_enabled = false } |
        -- | full   | uses all default values    |
        style = 'full',
    },
    callout = {
        -- Callouts are a special instance of a 'block_quote' that start with a 'shortcut_link'.
        -- The key is for healthcheck and to allow users to change its values, value type below.
        -- | raw        | matched against the raw text of a 'shortcut_link', case insensitive |
        -- | rendered   | replaces the 'raw' value when rendering                             |
        -- | highlight  | highlight for the 'rendered' text and quote markers                 |
        -- | quote_icon | optional override for quote.icon value for individual callout       |
        -- | category   | optional metadata useful for filtering                              |

        note      = { raw = '[!NOTE]',      rendered = '󰋽 Note',      highlight = 'RenderMarkdownInfo',    category = 'github'   },
        tip       = { raw = '[!TIP]',       rendered = '󰌶 Tip',       highlight = 'RenderMarkdownSuccess', category = 'github'   },
        important = { raw = '[!IMPORTANT]', rendered = '󰅾 Important', highlight = 'RenderMarkdownHint',    category = 'github'   },
        warning   = { raw = '[!WARNING]',   rendered = '󰀪 Warning',   highlight = 'RenderMarkdownWarn',    category = 'github'   },
        caution   = { raw = '[!CAUTION]',   rendered = '󰳦 Caution',   highlight = 'RenderMarkdownError',   category = 'github'   },
        -- Obsidian: https://help.obsidian.md/Editing+and+formatting/Callouts
        abstract  = { raw = '[!ABSTRACT]',  rendered = '󰨸 Abstract',  highlight = 'RenderMarkdownInfo',    category = 'obsidian' },
        summary   = { raw = '[!SUMMARY]',   rendered = '󰨸 Summary',   highlight = 'RenderMarkdownInfo',    category = 'obsidian' },
        tldr      = { raw = '[!TLDR]',      rendered = '󰨸 Tldr',      highlight = 'RenderMarkdownInfo',    category = 'obsidian' },
        info      = { raw = '[!INFO]',      rendered = '󰋽 Info',      highlight = 'RenderMarkdownInfo',    category = 'obsidian' },
        todo      = { raw = '[!TODO]',      rendered = '󰗡 Todo',      highlight = 'RenderMarkdownInfo',    category = 'obsidian' },
        hint      = { raw = '[!HINT]',      rendered = '󰌶 Hint',      highlight = 'RenderMarkdownSuccess', category = 'obsidian' },
        success   = { raw = '[!SUCCESS]',   rendered = '󰄬 Success',   highlight = 'RenderMarkdownSuccess', category = 'obsidian' },
        check     = { raw = '[!CHECK]',     rendered = '󰄬 Check',     highlight = 'RenderMarkdownSuccess', category = 'obsidian' },
        done      = { raw = '[!DONE]',      rendered = '󰄬 Done',      highlight = 'RenderMarkdownSuccess', category = 'obsidian' },
        question  = { raw = '[!QUESTION]',  rendered = '󰘥 Question',  highlight = 'RenderMarkdownWarn',    category = 'obsidian' },
        help      = { raw = '[!HELP]',      rendered = '󰘥 Help',      highlight = 'RenderMarkdownWarn',    category = 'obsidian' },
        faq       = { raw = '[!FAQ]',       rendered = '󰘥 Faq',       highlight = 'RenderMarkdownWarn',    category = 'obsidian' },
        attention = { raw = '[!ATTENTION]', rendered = '󰀪 Attention', highlight = 'RenderMarkdownWarn',    category = 'obsidian' },
        failure   = { raw = '[!FAILURE]',   rendered = '󰅖 Failure',   highlight = 'RenderMarkdownError',   category = 'obsidian' },
        fail      = { raw = '[!FAIL]',      rendered = '󰅖 Fail',      highlight = 'RenderMarkdownError',   category = 'obsidian' },
        missing   = { raw = '[!MISSING]',   rendered = '󰅖 Missing',   highlight = 'RenderMarkdownError',   category = 'obsidian' },
        danger    = { raw = '[!DANGER]',    rendered = '󱐌 Danger',    highlight = 'RenderMarkdownError',   category = 'obsidian' },
        error     = { raw = '[!ERROR]',     rendered = '󱐌 Error',     highlight = 'RenderMarkdownError',   category = 'obsidian' },
        bug       = { raw = '[!BUG]',       rendered = '󰨰 Bug',       highlight = 'RenderMarkdownError',   category = 'obsidian' },
        example   = { raw = '[!EXAMPLE]',   rendered = '󰉹 Example',   highlight = 'RenderMarkdownHint' ,   category = 'obsidian' },
        quote     = { raw = '[!QUOTE]',     rendered = '󱆨 Quote',     highlight = 'RenderMarkdownQuote',   category = 'obsidian' },
        cite      = { raw = '[!CITE]',      rendered = '󱆨 Cite',      highlight = 'RenderMarkdownQuote',   category = 'obsidian' },
    },
    link = {
        -- Turn on / off inline link icon rendering.
        enabled = true,
        -- Additional modes to render links.
        render_modes = false,
        -- How to handle footnote links, start with a '^'.
        footnote = {
            -- Turn on / off footnote rendering.
            enabled = true,
            -- Inlined with content.
            icon = '󰯔 ',
            -- Custom processing for footnote body to show.
            -- Runs before prefix / suffix are added and superscript processing.
            body = function(ctx)
                return ctx.text
            end,
            -- Replace value with superscript equivalent.
            superscript = true,
            -- Added before link content.
            prefix = '',
            -- Added after link content.
            suffix = '',
        },
        -- Inlined with 'image' elements.
        image = '󰥶 ',
        -- Check custom for 'image' elements.
        image_custom = true,
        -- Inlined with 'email_autolink' elements.
        email = '󰀓 ',
        -- Fallback icon for 'inline_link' and 'uri_autolink' elements.
        hyperlink = '󰌹 ',
        -- Applies to the inlined icon as a fallback.
        highlight = 'RenderMarkdownLink',
        -- Applies to the link title.
        highlight_title = 'RenderMarkdownLinkTitle',
        -- Applies to WikiLink elements.
        wiki = {
            -- Turn on / off WikiLink rendering.
            enabled = true,
            -- Inlined with content.
            icon = '󱗖 ',
            -- Custom processing for WikiLink body to show.
            body = function()
                return nil
            end,
            -- Applies to the inlined icon.
            highlight = 'RenderMarkdownWikiLink',
            -- Highlight for item associated with the WikiLink.
            scope_highlight = nil,
        },
        -- Define custom destination patterns so icons can quickly inform you of what a link
        -- contains. Applies to 'image', 'inline_link', 'uri_autolink', and WikiLink nodes.
        -- When multiple patterns match a link the one with the longer pattern is used.
        -- The key is for healthcheck and to allow users to change its values, value type below.
        -- | pattern   | matched against the destination text                            |
        -- | icon      | gets inlined before the link text                               |
        -- | kind      | optional determines how pattern is checked                      |
        -- |           | pattern | @see :h lua-patterns, is the default if not set       |
        -- |           | suffix  | @see :h vim.endswith()                                |
        -- | priority  | optional used when multiple match, uses pattern length if empty |
        -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
        custom = {
            web = { pattern = '^http', icon = '󰖟 ' },
            apple = { pattern = 'apple%.com', icon = ' ' },
            discord = { pattern = 'discord%.com', icon = '󰙯 ' },
            github = { pattern = 'github%.com', icon = '󰊤 ' },
            gitlab = { pattern = 'gitlab%.com', icon = '󰮠 ' },
            google = { pattern = 'google%.com', icon = '󰊭 ' },
            hackernews = { pattern = 'ycombinator%.com', icon = ' ' },
            linkedin = { pattern = 'linkedin%.com', icon = '󰌻 ' },
            microsoft = { pattern = 'microsoft%.com', icon = ' ' },
            neovim = { pattern = 'neovim%.io', icon = ' ' },
            reddit = { pattern = 'reddit%.com', icon = '󰑍 ' },
            slack = { pattern = 'slack%.com', icon = '󰒱 ' },
            stackoverflow = { pattern = 'stackoverflow%.com', icon = '󰓌 ' },
            steam = { pattern = 'steampowered%.com', icon = ' ' },
            twitter = { pattern = 'twitter%.com', icon = ' ' },
            wikipedia = { pattern = 'wikipedia%.org', icon = '󰖬 ' },
            x = { pattern = 'x%.com', icon = ' ' },
            youtube = { pattern = 'youtube[^.]*%.com', icon = '󰗃 ' },
            youtube_short = { pattern = 'youtu%.be', icon = '󰗃 ' },
        },
    },
    sign = {
        -- Turn on / off sign rendering.
        enabled = true,
        -- Priority to assign to sign.
        priority = nil,
        -- Applies to background of sign text.
        highlight = 'RenderMarkdownSign',
    },
    inline_highlight = {
        -- Mimics Obsidian inline highlights when content is surrounded by double equals.
        -- The equals on both ends are concealed and the inner content is highlighted.

        -- Turn on / off inline highlight rendering.
        enabled = true,
        -- Additional modes to render inline highlights.
        render_modes = false,
        -- Applies to background of surrounded text.
        highlight = 'RenderMarkdownInlineHighlight',
        -- Define custom highlights based on text prefix.
        -- The key is for healthcheck and to allow users to change its values, value type below.
        -- | prefix    | matched against text body, @see :h vim.startswith() |
        -- | highlight | highlight for text body                             |
        custom = {},
    },
    indent = {
        -- Mimic org-indent-mode behavior by indenting everything under a heading based on the
        -- level of the heading. Indenting starts from level 2 headings onward by default.

        -- Turn on / off org-indent-mode.
        enabled = false,
        -- Additional modes to render indents.
        render_modes = false,
        -- Amount of additional padding added for each heading level.
        per_level = 2,
        -- Heading levels <= this value will not be indented.
        -- Use 0 to begin indenting from the very first level.
        skip_level = 1,
        -- Do not indent heading titles, only the body.
        skip_heading = false,
        -- Prefix added when indenting, one per level.
        icon = '▎',
        -- Priority to assign to extmarks.
        priority = 0,
        -- Applied to icon.
        highlight = 'RenderMarkdownIndent',
    },
    html = {
        -- Turn on / off all HTML rendering.
        enabled = true,
        -- Additional modes to render HTML.
        render_modes = false,
        comment = {
            -- Useful context to have when evaluating values.
            -- | text | text value of the comment node |

            -- Turn on / off HTML comment concealing.
            conceal = true,
            -- Text to inline before the concealed comment.
            -- Output is evaluated depending on the type.
            -- | function | `value(context)` |
            -- | string   | `value`          |
            -- | nil      | nothing          |
            text = nil,
            -- Highlight for the inlined text.
            highlight = 'RenderMarkdownHtmlComment',
        },
        -- HTML tags whose start and end will be hidden and icon shown.
        -- The key is matched against the tag name, value type below.
        -- | icon            | optional icon inlined at start of tag           |
        -- | highlight       | optional highlight for the icon                 |
        -- | scope_highlight | optional highlight for item associated with tag |
        tag = {},
    },
    win_options = {
        -- Window options to use that change between rendered and raw view.

        -- @see :h 'conceallevel'
        conceallevel = {
            -- Used when not being rendered, get user setting.
            default = vim.o.conceallevel,
            -- Used when being rendered, concealed text is completely hidden.
            rendered = 3,
        },
        -- @see :h 'concealcursor'
        concealcursor = {
            -- Used when not being rendered, get user setting.
            default = vim.o.concealcursor,
            -- Used when being rendered, show concealed text in all modes.
            rendered = '',
        },
    },
    overrides = {
        -- More granular configuration mechanism, allows different aspects of buffers to have their own
        -- behavior. Values default to the top level configuration if no override is provided. Supports
        -- the following fields:
        --   enabled, render_modes, debounce, anti_conceal, bullet, callout, checkbox, code, dash,
        --   document, heading, html, indent, inline_highlight, latex, link, padding, paragraph,
        --   pipe_table, quote, sign, win_options, yaml

        -- Override for different buflisted values, @see :h 'buflisted'.
        buflisted = {},
        -- Override for different buftype values, @see :h 'buftype'.
        buftype = {
            nofile = {
                render_modes = true,
                padding = { highlight = 'NormalFloat' },
                sign = { enabled = false },
            },
        },
        -- Override for different filetype values, @see :h 'filetype'.
        filetype = {},
        -- Override for preview buffer.
        preview = {
            render_modes = true,
        },
    },
    custom_handlers = {
        -- Mapping from treesitter language to user defined handlers.
        -- @see [Custom Handlers](doc/custom-handlers.md)
    },
    yaml = {
        -- Turn on / off all yaml rendering.
        enabled = true,
        -- Additional modes to render yaml.
        render_modes = false,
    },
})

We use the following definitions when discussing indexing into lists:

Cycle: Indexed mod the length. Example: { 1, 2, 3 } @ 4 = 1.
Clamp: Indexed normally but larger values use the last value in the list. Example: { 1, 2, 3 } @ 4 = 3.

Headings

Wiki Page

Heading Configuration

require('render-markdown').setup({
    heading = {
        -- Useful context to have when evaluating values.
        -- | level    | the number of '#' in the heading marker         |
        -- | sections | for each level how deeply nested the heading is |

        -- Turn on / off heading icon & background rendering.
        enabled = true,
        -- Additional modes to render headings.
        render_modes = false,
        -- Turn on / off atx heading rendering.
        atx = true,
        -- Turn on / off setext heading rendering.
        setext = true,
        -- Turn on / off sign column related rendering.
        sign = true,
        -- Replaces '#+' of 'atx_h._marker'.
        -- Output is evaluated depending on the type.
        -- | function | `value(context)`              |
        -- | string[] | `cycle(value, context.level)` |
        icons = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
        -- Determines how icons fill the available space.
        -- | eol     | '#'s are concealed and icon is placed at right most column   |
        -- | right   | '#'s are concealed and icon is appended to right side        |
        -- | inline  | '#'s are concealed and icon is inlined on left side          |
        -- | overlay | icon is left padded with spaces and overlayed hiding all '#' |
        position = 'overlay',
        -- Added to the sign column if enabled.
        -- Output is evaluated by `cycle(value, context.level)`.
        signs = { '󰫎 ' },
        -- Width of the heading background.
        -- | block | width of the heading text |
        -- | full  | full width of the window  |
        -- Can also be a list of the above values evaluated by `clamp(value, context.level)`.
        width = 'full',
        -- Amount of margin to add to the left of headings.
        -- Margin available space is computed after accounting for padding.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        -- Can also be a list of numbers evaluated by `clamp(value, context.level)`.
        left_margin = 0,
        -- Amount of padding to add to the left of headings.
        -- Output is evaluated using the same logic as 'left_margin'.
        left_pad = 0,
        -- Amount of padding to add to the right of headings when width is 'block'.
        -- Output is evaluated using the same logic as 'left_margin'.
        right_pad = 0,
        -- Minimum width to use for headings when width is 'block'.
        -- Can also be a list of integers evaluated by `clamp(value, context.level)`.
        min_width = 0,
        -- Determines if a border is added above and below headings.
        -- Can also be a list of booleans evaluated by `clamp(value, context.level)`.
        border = false,
        -- Always use virtual lines for heading borders instead of attempting to use empty lines.
        border_virtual = false,
        -- Highlight the start of the border using the foreground highlight.
        border_prefix = false,
        -- Used above heading for border.
        above = '▄',
        -- Used below heading for border.
        below = '▀',
        -- Highlight for the heading icon and extends through the entire line.
        -- Output is evaluated by `clamp(value, context.level)`.
        backgrounds = {
            'RenderMarkdownH1Bg',
            'RenderMarkdownH2Bg',
            'RenderMarkdownH3Bg',
            'RenderMarkdownH4Bg',
            'RenderMarkdownH5Bg',
            'RenderMarkdownH6Bg',
        },
        -- Highlight for the heading and sign icons.
        -- Output is evaluated using the same logic as 'backgrounds'.
        foregrounds = {
            'RenderMarkdownH1',
            'RenderMarkdownH2',
            'RenderMarkdownH3',
            'RenderMarkdownH4',
            'RenderMarkdownH5',
            'RenderMarkdownH6',
        },
        -- Define custom heading patterns which allow you to override various properties based on
        -- the contents of a heading.
        -- The key is for healthcheck and to allow users to change its values, value type below.
        -- | pattern    | matched against the heading text @see :h lua-patterns |
        -- | icon       | optional override for the icon                        |
        -- | background | optional override for the background                  |
        -- | foreground | optional override for the foreground                  |
        custom = {},
    },
})

Paragraphs

Wiki Page

Paragraph Configuration

require('render-markdown').setup({
    paragraph = {
        -- Useful context to have when evaluating values.
        -- | text | text value of the node |

        -- Turn on / off paragraph rendering.
        enabled = true,
        -- Additional modes to render paragraphs.
        render_modes = false,
        -- Amount of margin to add to the left of paragraphs.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        -- Output is evaluated depending on the type.
        -- | function | `value(context)` |
        -- | number   | `value`          |
        left_margin = 0,
        -- Amount of padding to add to the first line of each paragraph.
        -- Output is evaluated using the same logic as 'left_margin'.
        indent = 0,
        -- Minimum width to use for paragraphs.
        min_width = 0,
    },
})

Code Blocks

Wiki Page

Code Block Configuration

require('render-markdown').setup({
    code = {
        -- Turn on / off code block & inline code rendering.
        enabled = true,
        -- Additional modes to render code blocks.
        render_modes = false,
        -- Turn on / off sign column related rendering.
        sign = true,
        -- Whether to conceal nodes at the top and bottom of code blocks.
        conceal_delimiters = true,
        -- Turn on / off language heading related rendering.
        language = true,
        -- Determines where language icon is rendered.
        -- | center | center of code block |
        -- | right  | right of code block  |
        -- | left   | left of code block   |
        position = 'left',
        -- Whether to include the language icon above code blocks.
        language_icon = true,
        -- Whether to include the language name above code blocks.
        language_name = true,
        -- Whether to include the language info above code blocks.
        language_info = true,
        -- Amount of padding to add around the language.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        language_pad = 0,
        -- A list of language names for which rendering will be disabled.
        disable = {},
        -- A list of language names for which background highlighting will be disabled.
        -- Likely because that language has background highlights itself.
        -- Use a boolean to make behavior apply to all languages.
        -- Borders above & below blocks will continue to be rendered.
        disable_background = { 'diff' },
        -- Width of the code block background.
        -- | block | width of the code block  |
        -- | full  | full width of the window |
        width = 'full',
        -- Amount of margin to add to the left of code blocks.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        -- Margin available space is computed after accounting for padding.
        left_margin = 0,
        -- Amount of padding to add to the left of code blocks.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        left_pad = 0,
        -- Amount of padding to add to the right of code blocks when width is 'block'.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        right_pad = 0,
        -- Minimum width to use for code blocks when width is 'block'.
        min_width = 0,
        -- Determines how the top / bottom of code block are rendered.
        -- | none  | do not render a border                               |
        -- | thick | use the same highlight as the code body              |
        -- | thin  | when lines are empty overlay the above & below icons |
        -- | hide  | conceal lines unless language name or icon is added  |
        border = 'hide',
        -- Used above code blocks to fill remaining space around language.
        language_border = '█',
        -- Added to the left of language.
        language_left = '',
        -- Added to the right of language.
        language_right = '',
        -- Used above code blocks for thin border.
        above = '▄',
        -- Used below code blocks for thin border.
        below = '▀',
        -- Turn on / off inline code related rendering.
        inline = true,
        -- Icon to add to the left of inline code.
        inline_left = '',
        -- Icon to add to the right of inline code.
        inline_right = '',
        -- Padding to add to the left & right of inline code.
        inline_pad = 0,
        -- Priority to assign to code background highlight.
        priority = 140,
        -- Highlight for code blocks.
        highlight = 'RenderMarkdownCode',
        -- Highlight for code info section, after the language.
        highlight_info = 'RenderMarkdownCodeInfo',
        -- Highlight for language, overrides icon provider value.
        highlight_language = nil,
        -- Highlight for border, use false to add no highlight.
        highlight_border = 'RenderMarkdownCodeBorder',
        -- Highlight for language, used if icon provider does not have a value.
        highlight_fallback = 'RenderMarkdownCodeFallback',
        -- Highlight for inline code.
        highlight_inline = 'RenderMarkdownCodeInline',
        -- Highlight for inline code left icon, default to reverse of highlight_inline.
        highlight_inline_left = nil,
        -- Highlight for inline code right icon, default to reverse of highlight_inline.
        highlight_inline_right = nil,
        -- Determines how code blocks & inline code are rendered.
        -- | none     | { enabled = false }                           |
        -- | normal   | { language = false }                          |
        -- | language | { disable_background = true, inline = false } |
        -- | full     | uses all default values                       |
        style = 'full',
    },
})

Dashed Line

Wiki Page

Dashed Line Configuration

require('render-markdown').setup({
    dash = {
        -- Useful context to have when evaluating values.
        -- | width | width of the current window |

        -- Turn on / off thematic break rendering.
        enabled = true,
        -- Additional modes to render dash.
        render_modes = false,
        -- Replaces '---'|'***'|'___'|'* * *' of 'thematic_break'.
        -- The icon gets repeated across the window's width.
        icon = '─',
        -- Width of the generated line.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        -- Output is evaluated depending on the type.
        -- | function | `value(context)`    |
        -- | number   | `value`             |
        -- | full     | width of the window |
        width = 'full',
        -- Amount of margin to add to the left of dash.
        -- If a float < 1 is provided it is treated as a percentage of available window space.
        left_margin = 0,
        -- Priority to assign to dash.
        priority = nil,
        -- Highlight for the whole line generated from the icon.
        highlight = 'RenderMarkdownDash',
    },
})

List Bullets

Wiki Page

Bullet Point Configuration

require('render-markdown').setup({
    bullet = {
        -- Useful context to have when evaluating values.
        -- | level | how deeply nested the list is, 1-indexed          |
        -- | index | how far down the item is at that level, 1-indexed |
        -- | value | text value of the marker node                     |

        -- Turn on / off list bullet rendering
        enabled = true,
        -- Additional modes to render list bullets
        render_modes = false,
        -- Replaces '-'|'+'|'*' of 'list_item'.
        -- If the item is a 'checkbox' a conceal is used to hide the bullet instead.
        -- Output is evaluated depending on the type.
        -- | function   | `value(context)`                                    |
        -- | string     | `value`                                             |
        -- | string[]   | `cycle(value, context.level)`                       |
        -- | string[][] | `clamp(cycle(value, context.level), context.index)` |
        icons = { '●', '○', '◆', '◇' },
        -- Replaces 'n.'|'n)' of 'list_item'.
        -- Output is evaluated using the same logic as 'icons'.
        ordered_icons = function(ctx)
            local value = vim.trim(ctx.value)
            local index = tonumber(value:sub(1, #value - 1))
            return ('%d.'):format(index > 1 and index or ctx.index)
        end,
        -- Padding to add to the left of bullet point.
        -- Output is evaluated depending on the type.
        -- | function | `value(context)` |
        -- | integer  | `value`          |
        left_pad = 0,
        -- Padding to add to the right of bullet point.
        -- Output is evaluated using the same logic as 'left_pad'.
        right_pad = 0,
        -- Highlight for the bullet icon.
        -- Output is evaluated using the same logic as 'icons'.
        highlight = 'RenderMarkdownBullet',
        -- Highlight for item associated with the bullet point.
        -- Output is evaluated using the same logic as 'icons'.
        scope_highlight = {},
        -- Priority to assign to scope highlight.
        scope_priority = nil,
    },
})

Checkboxes

Wiki Page

Checkbox Configuration

require('render-markdown').setup({
    checkbox = {
        -- Checkboxes are a special instance of a 'list_item' that start with a 'shortcut_link'.
        -- There are two special states for unchecked & checked defined in the markdown grammar.

        -- Turn on / off checkbox state rendering.
        enabled = true,
        -- Additional modes to render checkboxes.
        render_modes = false,
        -- Render the bullet point before the checkbox.
        bullet = false,
        -- Padding to add to the left of checkboxes.
        left_pad = 0,
        -- Padding to add to the right of checkboxes.
        right_pad = 1,
        unchecked = {
            -- Replaces '[ ]' of 'task_list_marker_unchecked'.
            icon = '󰄱 ',
            -- Highlight for the unchecked icon.
            highlight = 'RenderMarkdownUnchecked',
            -- Highlight for item associated with unchecked checkbox.
            scope_highlight = nil,
        },
        checked = {
            -- Replaces '[x]' of 'task_list_marker_checked'.
            icon = '󰱒 ',
            -- Highlight for the checked icon.
            highlight = 'RenderMarkdownChecked',
            -- Highlight for item associated with checked checkbox.
            scope_highlight = nil,
        },
        -- Define custom checkbox states, more involved, not part of the markdown grammar.
        -- As a result this requires neovim >= 0.10.0 since it relies on 'inline' extmarks.
        -- The key is for healthcheck and to allow users to change its values, value type below.
        -- | raw             | matched against the raw text of a 'shortcut_link'           |
        -- | rendered        | replaces the 'raw' value when rendering                     |
        -- | highlight       | highlight for the 'rendered' icon                           |
        -- | scope_highlight | optional highlight for item associated with custom checkbox |
        -- stylua: ignore
        custom = {
            todo = { raw = '[-]', rendered = '󰥔 ', highlight = 'RenderMarkdownTodo', scope_highlight = nil },
        },
        -- Priority to assign to scope highlight.
        scope_priority = nil,
    },
})

Block Quotes

Wiki Page

Block Quote Configuration

require('render-markdown').setup({
    quote = {
        -- Turn on / off block quote & callout rendering.
        enabled = true,
        -- Additional modes to render quotes.
        render_modes = false,
        -- Replaces '>' of 'block_quote'.
        icon = '▋',
        -- Whether to repeat icon on wrapped lines. Requires neovim >= 0.10. This will obscure text
        -- if incorrectly configured with :h 'showbreak', :h 'breakindent' and :h 'breakindentopt'.
        -- A combination of these that is likely to work follows.
        -- | showbreak      | '  ' (2 spaces)   |
        -- | breakindent    | true              |
        -- | breakindentopt | '' (empty string) |
        -- These are not validated by this plugin. If you want to avoid adding these to your main
        -- configuration then set them in win_options for this plugin.
        repeat_linebreak = false,
        -- Highlight for the quote icon.
        -- If a list is provided output is evaluated by `cycle(value, level)`.
        highlight = {
            'RenderMarkdownQuote1',
            'RenderMarkdownQuote2',
            'RenderMarkdownQuote3',
            'RenderMarkdownQuote4',
            'RenderMarkdownQuote5',
            'RenderMarkdownQuote6',
        },
    },
})

Tables

Wiki Page

Table Configuration

require('render-markdown').setup({
    pipe_table = {
        -- Turn on / off pipe table rendering.
        enabled = true,
        -- Additional modes to render pipe tables.
        render_modes = false,
        -- Pre configured settings largely for setting table border easier.
        -- | heavy  | use thicker border characters     |
        -- | double | use double line border characters |
        -- | round  | use round border corners          |
        -- | none   | does nothing                      |
        preset = 'none',
        -- Determines how individual cells of a table are rendered.
        -- | overlay | writes completely over the table, removing conceal behavior and highlights |
        -- | raw     | replaces only the '|' characters in each row, leaving the cells unmodified |
        -- | padded  | raw + cells are padded to maximum visual width for each column             |
        -- | trimmed | padded except empty space is subtracted from visual width calculation      |
        cell = 'padded',
        -- Adjust the computed width of table cells using custom logic.
        cell_offset = function()
            return 0
        end,
        -- Amount of space to put between cell contents and border.
        padding = 1,
        -- Minimum column width to use for padded or trimmed cell.
        min_width = 0,
        -- Characters used to replace table border.
        -- Correspond to top(3), delimiter(3), bottom(3), vertical, & horizontal.
        -- stylua: ignore
        border = {
            '┌', '┬', '┐',
            '├', '┼', '┤',
            '└', '┴', '┘',
            '│', '─',
        },
        -- Turn on / off top & bottom lines.
        border_enabled = true,
        -- Always use virtual lines for table borders instead of attempting to use empty lines.
        -- Will be automatically enabled if indentation module is enabled.
        border_virtual = false,
        -- Gets placed in delimiter row for each column, position is based on alignment.
        alignment_indicator = '━',
        -- Highlight for table heading, delimiter, and the line above.
        head = 'RenderMarkdownTableHead',
        -- Highlight for everything else, main table rows and the line below.
        row = 'RenderMarkdownTableRow',
        -- Determines how the table as a whole is rendered.
        -- | none   | { enabled = false }        |
        -- | normal | { border_enabled = false } |
        -- | full   | uses all default values    |
        style = 'full',
    },
})

Callouts

Wiki Page

Callout Configuration

require('render-markdown').setup({
    callout = {
        -- Callouts are a special instance of a 'block_quote' that start with a 'shortcut_link'.
        -- The key is for healthcheck and to allow users to change its values, value type below.
        -- | raw        | matched against the raw text of a 'shortcut_link', case insensitive |
        -- | rendered   | replaces the 'raw' value when rendering                             |
        -- | highlight  | highlight for the 'rendered' text and quote markers                 |
        -- | quote_icon | optional override for quote.icon value for individual callout       |
        -- | category   | optional metadata useful for filtering                              |

        note      = { raw = '[!NOTE]',      rendered = '󰋽 Note',      highlight = 'RenderMarkdownInfo',    category = 'github'   },
        tip       = { raw = '[!TIP]',       rendered = '󰌶 Tip',       highlight = 'RenderMarkdownSuccess', category = 'github'   },
        important = { raw = '[!IMPORTANT]', rendered = '󰅾 Important', highlight = 'RenderMarkdownHint',    category = 'github'   },
        warning   = { raw = '[!WARNING]',   rendered = '󰀪 Warning',   highlight = 'RenderMarkdownWarn',    category = 'github'   },
        caution   = { raw = '[!CAUTION]',   rendered = '󰳦 Caution',   highlight = 'RenderMarkdownError',   category = 'github'   },
        -- Obsidian: https://help.obsidian.md/Editing+and+formatting/Callouts
        abstract  = { raw = '[!ABSTRACT]',  rendered = '󰨸 Abstract',  highlight = 'RenderMarkdownInfo',    category = 'obsidian' },
        summary   = { raw = '[!SUMMARY]',   rendered = '󰨸 Summary',   highlight = 'RenderMarkdownInfo',    category = 'obsidian' },
        tldr      = { raw = '[!TLDR]',      rendered = '󰨸 Tldr',      highlight = 'RenderMarkdownInfo',    category = 'obsidian' },
        info      = { raw = '[!INFO]',      rendered = '󰋽 Info',      highlight = 'RenderMarkdownInfo',    category = 'obsidian' },
        todo      = { raw = '[!TODO]',      rendered = '󰗡 Todo',      highlight = 'RenderMarkdownInfo',    category = 'obsidian' },
        hint      = { raw = '[!HINT]',      rendered = '󰌶 Hint',      highlight = 'RenderMarkdownSuccess', category = 'obsidian' },
        success   = { raw = '[!SUCCESS]',   rendered = '󰄬 Success',   highlight = 'RenderMarkdownSuccess', category = 'obsidian' },
        check     = { raw = '[!CHECK]',     rendered = '󰄬 Check',     highlight = 'RenderMarkdownSuccess', category = 'obsidian' },
        done      = { raw = '[!DONE]',      rendered = '󰄬 Done',      highlight = 'RenderMarkdownSuccess', category = 'obsidian' },
        question  = { raw = '[!QUESTION]',  rendered = '󰘥 Question',  highlight = 'RenderMarkdownWarn',    category = 'obsidian' },
        help      = { raw = '[!HELP]',      rendered = '󰘥 Help',      highlight = 'RenderMarkdownWarn',    category = 'obsidian' },
        faq       = { raw = '[!FAQ]',       rendered = '󰘥 Faq',       highlight = 'RenderMarkdownWarn',    category = 'obsidian' },
        attention = { raw = '[!ATTENTION]', rendered = '󰀪 Attention', highlight = 'RenderMarkdownWarn',    category = 'obsidian' },
        failure   = { raw = '[!FAILURE]',   rendered = '󰅖 Failure',   highlight = 'RenderMarkdownError',   category = 'obsidian' },
        fail      = { raw = '[!FAIL]',      rendered = '󰅖 Fail',      highlight = 'RenderMarkdownError',   category = 'obsidian' },
        missing   = { raw = '[!MISSING]',   rendered = '󰅖 Missing',   highlight = 'RenderMarkdownError',   category = 'obsidian' },
        danger    = { raw = '[!DANGER]',    rendered = '󱐌 Danger',    highlight = 'RenderMarkdownError',   category = 'obsidian' },
        error     = { raw = '[!ERROR]',     rendered = '󱐌 Error',     highlight = 'RenderMarkdownError',   category = 'obsidian' },
        bug       = { raw = '[!BUG]',       rendered = '󰨰 Bug',       highlight = 'RenderMarkdownError',   category = 'obsidian' },
        example   = { raw = '[!EXAMPLE]',   rendered = '󰉹 Example',   highlight = 'RenderMarkdownHint' ,   category = 'obsidian' },
        quote     = { raw = '[!QUOTE]',     rendered = '󱆨 Quote',     highlight = 'RenderMarkdownQuote',   category = 'obsidian' },
        cite      = { raw = '[!CITE]',      rendered = '󱆨 Cite',      highlight = 'RenderMarkdownQuote',   category = 'obsidian' },
    },
})

Links

Wiki Page

Link Configuration

require('render-markdown').setup({
    link = {
        -- Turn on / off inline link icon rendering.
        enabled = true,
        -- Additional modes to render links.
        render_modes = false,
        -- How to handle footnote links, start with a '^'.
        footnote = {
            -- Turn on / off footnote rendering.
            enabled = true,
            -- Inlined with content.
            icon = '󰯔 ',
            -- Custom processing for footnote body to show.
            -- Runs before prefix / suffix are added and superscript processing.
            body = function(ctx)
                return ctx.text
            end,
            -- Replace value with superscript equivalent.
            superscript = true,
            -- Added before link content.
            prefix = '',
            -- Added after link content.
            suffix = '',
        },
        -- Inlined with 'image' elements.
        image = '󰥶 ',
        -- Check custom for 'image' elements.
        image_custom = true,
        -- Inlined with 'email_autolink' elements.
        email = '󰀓 ',
        -- Fallback icon for 'inline_link' and 'uri_autolink' elements.
        hyperlink = '󰌹 ',
        -- Applies to the inlined icon as a fallback.
        highlight = 'RenderMarkdownLink',
        -- Applies to the link title.
        highlight_title = 'RenderMarkdownLinkTitle',
        -- Applies to WikiLink elements.
        wiki = {
            -- Turn on / off WikiLink rendering.
            enabled = true,
            -- Inlined with content.
            icon = '󱗖 ',
            -- Custom processing for WikiLink body to show.
            body = function()
                return nil
            end,
            -- Applies to the inlined icon.
            highlight = 'RenderMarkdownWikiLink',
            -- Highlight for item associated with the WikiLink.
            scope_highlight = nil,
        },
        -- Define custom destination patterns so icons can quickly inform you of what a link
        -- contains. Applies to 'image', 'inline_link', 'uri_autolink', and WikiLink nodes.
        -- When multiple patterns match a link the one with the longer pattern is used.
        -- The key is for healthcheck and to allow users to change its values, value type below.
        -- | pattern   | matched against the destination text                            |
        -- | icon      | gets inlined before the link text                               |
        -- | kind      | optional determines how pattern is checked                      |
        -- |           | pattern | @see :h lua-patterns, is the default if not set       |
        -- |           | suffix  | @see :h vim.endswith()                                |
        -- | priority  | optional used when multiple match, uses pattern length if empty |
        -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
        custom = {
            web = { pattern = '^http', icon = '󰖟 ' },
            apple = { pattern = 'apple%.com', icon = ' ' },
            discord = { pattern = 'discord%.com', icon = '󰙯 ' },
            github = { pattern = 'github%.com', icon = '󰊤 ' },
            gitlab = { pattern = 'gitlab%.com', icon = '󰮠 ' },
            google = { pattern = 'google%.com', icon = '󰊭 ' },
            hackernews = { pattern = 'ycombinator%.com', icon = ' ' },
            linkedin = { pattern = 'linkedin%.com', icon = '󰌻 ' },
            microsoft = { pattern = 'microsoft%.com', icon = ' ' },
            neovim = { pattern = 'neovim%.io', icon = ' ' },
            reddit = { pattern = 'reddit%.com', icon = '󰑍 ' },
            slack = { pattern = 'slack%.com', icon = '󰒱 ' },
            stackoverflow = { pattern = 'stackoverflow%.com', icon = '󰓌 ' },
            steam = { pattern = 'steampowered%.com', icon = ' ' },
            twitter = { pattern = 'twitter%.com', icon = ' ' },
            wikipedia = { pattern = 'wikipedia%.org', icon = '󰖬 ' },
            x = { pattern = 'x%.com', icon = ' ' },
            youtube = { pattern = 'youtube[^.]*%.com', icon = '󰗃 ' },
            youtube_short = { pattern = 'youtu%.be', icon = '󰗃 ' },
        },
    },
})

Signs

Wiki Page

Sign Configuration

require('render-markdown').setup({
    sign = {
        -- Turn on / off sign rendering.
        enabled = true,
        -- Priority to assign to sign.
        priority = nil,
        -- Applies to background of sign text.
        highlight = 'RenderMarkdownSign',
    },
})

Indent

Wiki Page

Indent Configuration

require('render-markdown').setup({
    indent = {
        -- Mimic org-indent-mode behavior by indenting everything under a heading based on the
        -- level of the heading. Indenting starts from level 2 headings onward by default.

        -- Turn on / off org-indent-mode.
        enabled = false,
        -- Additional modes to render indents.
        render_modes = false,
        -- Amount of additional padding added for each heading level.
        per_level = 2,
        -- Heading levels <= this value will not be indented.
        -- Use 0 to begin indenting from the very first level.
        skip_level = 1,
        -- Do not indent heading titles, only the body.
        skip_heading = false,
        -- Prefix added when indenting, one per level.
        icon = '▎',
        -- Priority to assign to extmarks.
        priority = 0,
        -- Applied to icon.
        highlight = 'RenderMarkdownIndent',
    },
})

Colors

The table below shows all the highlight groups with their default link

Highlight Group	Default Group	Description
RenderMarkdownH1	@markup.heading.1.markdown	H1 icons
RenderMarkdownH2	@markup.heading.2.markdown	H2 icons
RenderMarkdownH3	@markup.heading.3.markdown	H3 icons
RenderMarkdownH4	@markup.heading.4.markdown	H4 icons
RenderMarkdownH5	@markup.heading.5.markdown	H5 icons
RenderMarkdownH6	@markup.heading.6.markdown	H6 icons
RenderMarkdownH1Bg	DiffText	H1 background line
RenderMarkdownH2Bg	DiffAdd	H2 background line
RenderMarkdownH3Bg	DiffChange	H3 background line
RenderMarkdownH4Bg	DiffDelete	H4 background line
RenderMarkdownH5Bg	Visual	H5 background line
RenderMarkdownH6Bg	CursorColumn	H6 background line
RenderMarkdownCode	ColorColumn	Code block background
RenderMarkdownCodeInfo	@label	Code info, after language
RenderMarkdownCodeBorder	RenderMarkdownCode	Code border background
RenderMarkdownCodeFallback	Normal	Fallback for code language
RenderMarkdownCodeInline	RenderMarkdownCode	Inline code background
RenderMarkdownQuote	@markup.quote	Default for block quote
RenderMarkdownQuote1	RenderMarkdownQuote	Level 1 block quote marker
RenderMarkdownQuote2	RenderMarkdownQuote	Level 2 block quote marker
RenderMarkdownQuote3	RenderMarkdownQuote	Level 3 block quote marker
RenderMarkdownQuote4	RenderMarkdownQuote	Level 4 block quote marker
RenderMarkdownQuote5	RenderMarkdownQuote	Level 5 block quote marker
RenderMarkdownQuote6	RenderMarkdownQuote	Level 6 block quote marker
RenderMarkdownInlineHighlight	RenderMarkdownCodeInline	Inline highlights contents
RenderMarkdownBullet	Normal	List item bullet points
RenderMarkdownDash	LineNr	Thematic break line
RenderMarkdownSign	SignColumn	Sign column background
RenderMarkdownMath	@markup.math	Latex lines
RenderMarkdownIndent	Whitespace	Indent icon
RenderMarkdownHtmlComment	@comment	HTML comment inline text
RenderMarkdownLink	@markup.link.label.markdown_inline	Link icon
RenderMarkdownLinkTitle	@markup.link.markdown_inline	Link title
RenderMarkdownWikiLink	RenderMarkdownLink	WikiLink icon
RenderMarkdownUnchecked	@markup.list.unchecked	Unchecked checkbox
RenderMarkdownChecked	@markup.list.checked	Checked checkbox
RenderMarkdownTodo	@markup.raw	Todo custom checkbox
RenderMarkdownTableHead	@markup.heading	Pipe table heading rows
RenderMarkdownTableRow	Normal	Pipe table body rows
RenderMarkdownSuccess	DiagnosticOk	Success related callouts
RenderMarkdownInfo	DiagnosticInfo	Info related callouts
RenderMarkdownHint	DiagnosticHint	Hint related callouts
RenderMarkdownWarn	DiagnosticWarn	Warning related callouts
RenderMarkdownError	DiagnosticError	Error related callouts

Info

vimwiki

Note

vimwiki overrides the filetype of markdown files, as such there are additional setup steps.

Add vimwiki to the file_types configuration of this plugin

require('render-markdown').setup({
    file_types = { 'markdown', 'vimwiki' },
})

vim.treesitter.language.register('markdown', 'vimwiki')

obsidian.nvim

Note

obsidian.nvim provides UI functionality that is enabled by default. While there may be a way to have the 2 work together, for the foreseeable future only one of these plugins should be used for the UI. If you choose this plugin disable the obsidian.nvim UI with:

require('obsidian').setup({
    ui = { enable = false },
})

You can also do something more custom like lazy loading this plugin via a command and adding logic to the config method to disable obsidian.nvim as suggested in #116, though things like this can break at any time given the reliance on internal logic.

Images

Note

Images are only supported so far as this plugin will not interfere with others like image.nvim, however nothing is done natively by this plugin. It is recommended to enable the only_render_image_at_cursor option.

Additional

Limitations: Known limitations of this plugin
Custom Handlers: Allow users to integrate custom rendering for either unsupported languages or to override / extend builtin implementations
Troubleshooting Guide
Purpose: Why this plugin exists
Markdown Ecosystem: Information about other markdown related plugins and how they co-exist

Acknowledgments

headlines.nvim: The plugin that inspired me to create this one and whose implementation I used as a reference for the original version
crates.nvim: Used the in-process lsp implementation as an awesome reference lsp.lua

Donate

I enjoy working on these projects and will continue to do so with the time I can find. Any support is appreciated including starring the repo and reporting issues. Money is also nice: Donate via Stripe.

Requires neovim >= 0.10.0 ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎
Requires icon provider, mini.icons or nvim-web-devicons ↩︎
Requires latex parser and pylatexenc ↩︎

nvim-lualine/lualine.nvim

A blazing fast and easy to configure neovim statusline plugin written in pure lua.

lualine.nvim

A blazing fast and easy to configure Neovim statusline written in Lua.

lualine.nvim requires Neovim >= 0.7.

For previous versions of neovim please use compatability tags for example compat-nvim-0.5

Contributing

Feel free to create an issue/PR if you want to see anything else implemented. If you have some question or need help with configuration, start a discussion.

Please read CONTRIBUTING.md before opening a PR. You can also help with documentation in the wiki.

Screenshots

Here is a preview of what lualine can look like.

Screenshots of all available themes are listed in THEMES.md

For those who want to break the norms, you can create custom looks for lualine.

Example :

Performance compared to other plugins

Unlike other statusline plugins, lualine loads only the components you specify, and nothing else.

Startup time performance measured with an amazing plugin dstein64/vim-startuptime

Times are measured with a clean init.vim with only vim-startuptime, vim-plug and given statusline plugin installed. In control just vim-startuptime andvim-plug is installed. And measured time is complete startuptime of vim not time spent on specific plugin. These numbers are the average of 20 runs.

control	lualine	lightline	airline
17.2 ms	24.8 ms	25.5 ms	79.9 ms

Last Updated On: 18-04-2022

Installation

vim.pack (Only for neovim 0.12)

vim.pack.add({
    'https://github.com/nvim-tree/nvim-web-devicons',
    'https://github.com/nvim-lualine/lualine.nvim'
})

vim-plug

Plug 'nvim-lualine/lualine.nvim'
" If you want to have icons in your statusline choose one of these
Plug 'nvim-tree/nvim-web-devicons'

packer.nvim

use {
  'nvim-lualine/lualine.nvim',
  requires = { 'nvim-tree/nvim-web-devicons', opt = true }
}

lazy.nvim

{
    'nvim-lualine/lualine.nvim',
    dependencies = { 'nvim-tree/nvim-web-devicons' }
}

You'll also need to have a patched font if you want icons.

Usage and customization

Lualine has sections as shown below.

+-------------------------------------------------+
| A | B | C                             X | Y | Z |
+-------------------------------------------------+

Each sections holds its components e.g. Vim's current mode.

Configuring lualine in init.vim

All the examples below are in lua. You can use the same examples in .vim files by wrapping them in lua heredoc like this:

lua << END
require('lualine').setup()
END

For more information, check out :help lua-heredoc.

Default configuration

require('lualine').setup {
  options = {
    icons_enabled = true,
    theme = 'auto',
    component_separators = { left = '', right = ''},
    section_separators = { left = '', right = ''},
    disabled_filetypes = {
      statusline = {},
      winbar = {},
    },
    ignore_focus = {},
    always_divide_middle = true,
    always_show_tabline = true,
    globalstatus = false,
    refresh = {
      statusline = 1000,
      tabline = 1000,
      winbar = 1000,
      refresh_time = 16, -- ~60fps
      events = {
        'WinEnter',
        'BufEnter',
        'BufWritePost',
        'SessionLoadPost',
        'FileChangedShellPost',
        'VimResized',
        'Filetype',
        'CursorMoved',
        'CursorMovedI',
        'ModeChanged',
      },
    }
  },
  sections = {
    lualine_a = {'mode'},
    lualine_b = {'branch', 'diff', 'diagnostics'},
    lualine_c = {'filename'},
    lualine_x = {'encoding', 'fileformat', 'filetype'},
    lualine_y = {'progress'},
    lualine_z = {'location'}
  },
  inactive_sections = {
    lualine_a = {},
    lualine_b = {},
    lualine_c = {'filename'},
    lualine_x = {'location'},
    lualine_y = {},
    lualine_z = {}
  },
  tabline = {},
  winbar = {},
  inactive_winbar = {},
  extensions = {}
}

If you want to get your current lualine config, you can do so with:

require('lualine').get_config()

Starting lualine

require('lualine').setup()

Setting a theme

options = { theme = 'gruvbox' }

All available themes are listed in THEMES.md.

Please create a PR if you managed to port a popular theme before us, here is how to do it.

Customizing themes

local custom_gruvbox = require'lualine.themes.gruvbox'

-- Change the background of lualine_c section for normal mode
custom_gruvbox.normal.c.bg = '#112233'

require('lualine').setup {
  options = { theme  = custom_gruvbox },
  ...
}

Theme structure is available here.

Separators

lualine defines two kinds of separators:

section_separators - separators between sections
component_separators - separators between the different components in sections

Note: if viewing this README in a browser, chances are the characters below will not be visible.

options = {
  section_separators = { left = '', right = '' },
  component_separators = { left = '', right = '' }
}

Here, left refers to the left-most sections (a, b, c), and right refers to the right-most sections (x, y, z).

Disabling separators

options = { section_separators = '', component_separators = '' }

Changing components in lualine sections

sections = {lualine_a = {'mode'}}

Available components

branch (git branch)
buffers (shows currently available buffers)
diagnostics (diagnostics count from your preferred source)
diff (git diff status)
encoding (file encoding)
fileformat (file format)
filename
filesize
filetype
hostname
location (location in file in line:column format)
mode (vim mode)
progress (%progress in file)
searchcount (number of search matches when hlsearch is active)
selectioncount (number of selected characters or lines)
tabs (shows currently available tabs)
windows (shows currently available windows)
lsp_status (shows active LSPs in the current buffer and a progress spinner)

Custom components

Lua functions as lualine component

local function hello()
  return [[hello world]]
end
sections = { lualine_a = { hello } }

Vim functions as lualine component

sections = { lualine_a = {'FugitiveHead'} }

Vim's statusline items as lualine component

sections = { lualine_c = {'%=', '%t%m', '%3p'} }

Vim variables as lualine component

Variables from g:, v:, t:, w:, b:, o:, to:, wo:, bo: scopes can be used.

See :h lua-vim-variables and :h lua-vim-options if you are not sure what to use.

sections = { lualine_a = { 'g:coc_status', 'bo:filetype' } }

Lua expressions as lualine component

You can use any valid lua expression as a component including:

oneliners
global variables
require statements

sections = { lualine_c = { "os.date('%a')", 'data', "require'lsp-status'.status()" } }

data is a global variable in this example.

Component options

Component options can change the way a component behave. There are two kinds of options:

global options affecting all components
local options affecting specific

Global options can be used as local options (can be applied to specific components) but you cannot use local options as global. Global option used locally overwrites the global, for example:

    require('lualine').setup {
      options = { fmt = string.lower },
      sections = { lualine_a = {
        { 'mode', fmt = function(str) return str:sub(1,1) end } },
                  lualine_b = {'branch'} }
    }

mode will be formatted with the passed function so only first char will be shown . On the other hand branch will be formatted with global formatter string.lower so it will be showed in lower case.

Available options

Global options

These are options that are used in options table. They set behavior of lualine.

Values set here are treated as default for other options that work in component level.

For example even though icons_enabled is a general component option. You can set icons_enabled to false and icons will be disabled on all component. You can still overwrite defaults set in option table by specifying the option value in component.

options = {
  theme = 'auto', -- lualine theme
  component_separators = { left = '', right = '' },
  section_separators = { left = '', right = '' },
  disabled_filetypes = {     -- Filetypes to disable lualine for.
      statusline = {},       -- only ignores the ft for statusline.
      winbar = {},           -- only ignores the ft for winbar.
  },

  ignore_focus = {},         -- If current filetype is in this list it'll
                             -- always be drawn as inactive statusline
                             -- and the last window will be drawn as active statusline.
                             -- for example if you don't want statusline of
                             -- your file tree / sidebar window to have active
                             -- statusline you can add their filetypes here.
                             --
                             -- Can also be set to a function that takes the
                             -- currently focused window as its only argument
                             -- and returns a boolean representing whether the
                             -- window's statusline should be drawn as inactive.

  always_divide_middle = true, -- When set to true, left sections i.e. 'a','b' and 'c'
                               -- can't take over the entire statusline even
                               -- if neither of 'x', 'y' or 'z' are present.

  always_show_tabline = true -- When set to true, if you have configured lualine for displaying tabline
                          -- then tabline will always show. If set to false, then tabline will be displayed
                          -- only when there are more than 1 tab. (see :h showtabline)

  globalstatus = false,        -- enable global statusline (have a single statusline
                               -- at bottom of neovim instead of one for  every window).
                               -- This feature is only available in neovim 0.7 and higher.

  refresh = {                  -- sets how often lualine should refresh it's contents (in ms)
    statusline = 100,         -- The refresh option sets minimum time that lualine tries
    tabline = 100,            -- to maintain between refresh. It's not guarantied if situation
    winbar = 100              -- arises that lualine needs to refresh itself before this time
                              -- it'll do it.
    refresh_time = 16,        -- ~60fps the time after which refresh queue is processed. Mininum refreshtime for lualine
    events = {                -- The auto command events at which lualine refreshes
      'WinEnter',
      'BufEnter',
      'BufWritePost',
      'SessionLoadPost',
      'FileChangedShellPost',
      'VimResized',
      'Filetype',
      'CursorMoved',
      'CursorMovedI',
      'ModeChanged',
    },
                               -- Also you can force lualine's refresh by calling refresh function
                               -- like require('lualine').refresh()
  }
}

General component options

These are options that control behavior at component level and are available for all components.

sections = {
  lualine_a = {
    {
      'mode',
      icons_enabled = true, -- Enables the display of icons alongside the component.
      -- Defines the icon to be displayed in front of the component.
      -- Can be string|table
      -- As table it must contain the icon as first entry and can use
      -- color option to custom color the icon. Example:
      -- {'branch', icon = ''} / {'branch', icon = {'', color={fg='green'}}}

      -- icon position can also be set to the right side from table. Example:
      -- {'branch', icon = {'', align='right', color={fg='green'}}}
      icon = nil,

      separator = nil,      -- Determines what separator to use for the component.
                            -- Note:
                            --  When a string is provided it's treated as component_separator.
                            --  When a table is provided it's treated as section_separator.
                            --  Passing an empty string disables the separator.
                            --
                            -- These options can be used to set colored separators
                            -- around a component.
                            --
                            -- The options need to be set as such:
                            --   separator = { left = '', right = ''}
                            --
                            -- Where left will be placed on left side of component,
                            -- and right will be placed on its right.
                            --

      cond = nil,           -- Condition function, the component is loaded when the function returns `true`.

      draw_empty = false,   -- Whether to draw component even if it's empty.
                            -- Might be useful if you want just the separator.

      -- Defines a custom color for the component:
      --
      -- 'highlight_group_name' | { fg = '#rrggbb'|cterm_value(0-255)|'color_name(red)', bg= '#rrggbb', gui='style' } | function
      -- Note:
      --  '|' is synonymous with 'or', meaning a different acceptable format for that placeholder.
      -- color function has to return one of other color types ('highlight_group_name' | { fg = '#rrggbb'|cterm_value(0-255)|'color_name(red)', bg= '#rrggbb', gui='style' })
      -- color functions can be used to have different colors based on state as shown below.
      --
      -- Examples:
      --   color = { fg = '#ffaa88', bg = 'grey', gui='italic,bold' },
      --   color = { fg = 204 }   -- When fg/bg are omitted, they default to the your theme's fg/bg.
      --   color = 'WarningMsg'   -- Highlight groups can also be used.
      --   color = function(section)
      --      return { fg = vim.bo.modified and '#aa3355' or '#33aa88' }
      --   end,
      color = nil, -- The default is your theme's color for that section and mode.

      -- Specify what type a component is, if omitted, lualine will guess it for you.
      --
      -- Available types are:
      --   [format: type_name(example)], mod(branch/filename),
      --   stl(%f/%m), var(g:coc_status/bo:modifiable),
      --   lua_expr(lua expressions), vim_fun(viml function name)
      --
      -- Note:
      -- lua_expr is short for lua-expression and vim_fun is short for vim-function.
      type = nil,

      padding = 1, -- Adds padding to the left and right of components.
                   -- Padding can be specified to left or right independently, e.g.:
                   --   padding = { left = left_padding, right = right_padding }

      fmt = nil,   -- Format function, formats the component's output.
                   -- This function receives two arguments:
                   -- - string that is going to be displayed and
                   --   that can be changed, enhanced and etc.
                   -- - context object with information you might
                   --   need. E.g. tabnr if used with tabs.
      on_click = nil, -- takes a function that is called when component is clicked with mouse.
                   -- the function receives several arguments
                   -- - number of clicks in case of multiple clicks
                   -- - mouse button used (l(left)/r(right)/m(middle)/...)
                   -- - modifiers pressed (s(shift)/c(ctrl)/a(alt)/m(meta)...)
    }
  }
}

Component specific options

These are options that are available on specific components. For example, you have option on diagnostics component to specify what your diagnostic sources will be.

buffers component options

sections = {
  lualine_a = {
    {
      'buffers',
      show_filename_only = true,   -- Shows shortened relative path when set to false.
      hide_filename_extension = false,   -- Hide filename extension when set to true.
      show_modified_status = true, -- Shows indicator when the buffer is modified.

      mode = 0, -- 0: Shows buffer name
                -- 1: Shows buffer index
                -- 2: Shows buffer name + buffer index
                -- 3: Shows buffer number
                -- 4: Shows buffer name + buffer number

      max_length = vim.o.columns * 2 / 3, -- Maximum width of buffers component,
                                          -- it can also be a function that returns
                                          -- the value of `max_length` dynamically.
      filetype_names = {
        TelescopePrompt = 'Telescope',
        dashboard = 'Dashboard',
        packer = 'Packer',
        fzf = 'FZF',
        alpha = 'Alpha'
      }, -- Shows specific buffer name for that filetype ( { `filetype` = `buffer_name`, ... } )

      -- Automatically updates active buffer color to match color of other components (will be overidden if buffers_color is set)
      use_mode_colors = false,

      buffers_color = {
        -- Same values as the general color option can be used here.
        active = 'lualine_{section}_normal',     -- Color for active buffer.
        inactive = 'lualine_{section}_inactive', -- Color for inactive buffer.
      },

      symbols = {
        modified = ' ●',      -- Text to show when the buffer is modified
        alternate_file = '#', -- Text to show to identify the alternate file
        directory =  '',     -- Text to show when the buffer is a directory
      },
    }
  }
}

datetime component options

sections = {
  lualine_a = {
    {
      'datetime',
      -- options: default, us, uk, iso, or your own format string ("%H:%M", etc..)
      style = 'default'
    }
  }
}

diagnostics component options

sections = {
  lualine_a = {
    {
      'diagnostics',

      -- Table of diagnostic sources, available sources are:
      --   'nvim_lsp', 'nvim_diagnostic', 'nvim_workspace_diagnostic', 'coc', 'ale', 'vim_lsp'.
      -- or a function that returns a table as such:
      --   { error=error_cnt, warn=warn_cnt, info=info_cnt, hint=hint_cnt }
      sources = { 'nvim_diagnostic', 'coc' },

      -- Displays diagnostics for the defined severity types
      sections = { 'error', 'warn', 'info', 'hint' },

      diagnostics_color = {
        -- Same values as the general color option can be used here.
        error = 'DiagnosticError', -- Changes diagnostics' error color.
        warn  = 'DiagnosticWarn',  -- Changes diagnostics' warn color.
        info  = 'DiagnosticInfo',  -- Changes diagnostics' info color.
        hint  = 'DiagnosticHint',  -- Changes diagnostics' hint color.
      },
      symbols = {error = 'E', warn = 'W', info = 'I', hint = 'H'},
      colored = true,           -- Displays diagnostics status in color if set to true.
      update_in_insert = false, -- Update diagnostics in insert mode.
      always_visible = false,   -- Show diagnostics even if there are none.
    }
  }
}

diff component options

sections = {
  lualine_a = {
    {
      'diff',
      colored = true, -- Displays a colored diff status if set to true
      diff_color = {
        -- Same color values as the general color option can be used here.
        added    = 'LuaLineDiffAdd',    -- Changes the diff's added color
        modified = 'LuaLineDiffChange', -- Changes the diff's modified color
        removed  = 'LuaLineDiffDelete', -- Changes the diff's removed color you
      },
      symbols = {added = '+', modified = '~', removed = '-'}, -- Changes the symbols used by the diff.
      source = nil, -- A function that works as a data source for diff.
                    -- It must return a table as such:
                    --   { added = add_count, modified = modified_count, removed = removed_count }
                    -- or nil on failure. count <= 0 won't be displayed.
    }
  }
}

fileformat component options

sections = {
  lualine_a = {
    {
      'fileformat',
      symbols = {
        unix = '', -- e712
        dos = '',  -- e70f
        mac = '',  -- e711
      }
    }
  }
}

filename component options

sections = {
  lualine_a = {
    {
      'filename',
      file_status = true,      -- Displays file status (readonly status, modified status)
      newfile_status = false,  -- Display new file status (new file means no write after created)
      path = 0,                -- 0: Just the filename
                               -- 1: Relative path
                               -- 2: Absolute path
                               -- 3: Absolute path, with tilde as the home directory
                               -- 4: Filename and parent dir, with tilde as the home directory

      shorting_target = 40,    -- Shortens path to leave 40 spaces in the window
                               -- for other components. (terrible name, any suggestions?)
                               -- It can also be a function that returns
                               -- the value of `shorting_target` dynamically.
      symbols = {
        modified = '[+]',      -- Text to show when the file is modified.
        readonly = '[-]',      -- Text to show when the file is non-modifiable or readonly.
        unnamed = '[No Name]', -- Text to show for unnamed buffers.
        newfile = '[New]',     -- Text to show for newly created file before first write
      }
    }
  }
}

filetype component options

sections = {
  lualine_a = {
    {
      'filetype',
      colored = true,   -- Displays filetype icon in color if set to true
      icon_only = false, -- Display only an icon for filetype
      icon = { align = 'right' }, -- Display filetype icon on the right hand side
      -- icon =    {'X', align='right'}
      -- Icon string ^ in table is ignored in filetype component
    }
  }
}

encoding component options

sections = {
  lualine_a = {
    {
      'encoding',
      -- Show '[BOM]' when the file has a byte-order mark
        show_bomb = false,
    }
  }
}

searchcount component options

sections = {
  lualine_a = {
    {
      'searchcount',
      maxcount = 999,
      timeout = 500,
    }
  }
}

tabs component options

sections = {
  lualine_a = {
    {
      'tabs',
      tab_max_length = 40,  -- Maximum width of each tab. The content will be shorten dynamically (example: apple/orange -> a/orange)
      max_length = vim.o.columns / 3, -- Maximum width of tabs component.
                                      -- Note:
                                      -- It can also be a function that returns
                                      -- the value of `max_length` dynamically.
      mode = 0, -- 0: Shows tab_nr
                -- 1: Shows tab_name
                -- 2: Shows tab_nr + tab_name

      path = 0, -- 0: just shows the filename
                -- 1: shows the relative path and shorten $HOME to ~
                -- 2: shows the full path
                -- 3: shows the full path and shorten $HOME to ~

      -- Automatically updates active tab color to match color of other components (will be overidden if buffers_color is set)
      use_mode_colors = false,

      tabs_color = {
        -- Same values as the general color option can be used here.
        active = 'lualine_{section}_normal',     -- Color for active tab.
        inactive = 'lualine_{section}_inactive', -- Color for inactive tab.
      },

      show_modified_status = true,  -- Shows a symbol next to the tab name if the file has been modified.
      symbols = {
        modified = '[+]',  -- Text to show when the file is modified.
      },

      fmt = function(name, context)
        -- Show + if buffer is modified in tab
        local buflist = vim.fn.tabpagebuflist(context.tabnr)
        local winnr = vim.fn.tabpagewinnr(context.tabnr)
        local bufnr = buflist[winnr]
        local mod = vim.fn.getbufvar(bufnr, '&mod')

        return name .. (mod == 1 and ' +' or '')
      end
    }
  }
}

windows component options

sections = {
  lualine_a = {
    {
      'windows',
      show_filename_only = true,   -- Shows shortened relative path when set to false.
      show_modified_status = true, -- Shows indicator when the window is modified.

      mode = 0, -- 0: Shows window name
                -- 1: Shows window index
                -- 2: Shows window name + window index

      max_length = vim.o.columns * 2 / 3, -- Maximum width of windows component,
                                          -- it can also be a function that returns
                                          -- the value of `max_length` dynamically.
      filetype_names = {
        TelescopePrompt = 'Telescope',
        dashboard = 'Dashboard',
        packer = 'Packer',
        fzf = 'FZF',
        alpha = 'Alpha'
      }, -- Shows specific window name for that filetype ( { `filetype` = `window_name`, ... } )

      disabled_buftypes = { 'quickfix', 'prompt' }, -- Hide a window if its buffer's type is disabled

      -- Automatically updates active window color to match color of other components (will be overidden if buffers_color is set)
      use_mode_colors = false,

      windows_color = {
        -- Same values as the general color option can be used here.
        active = 'lualine_{section}_normal',     -- Color for active window.
        inactive = 'lualine_{section}_inactive', -- Color for inactive window.
      },
    }
  }
}

lsp status component options

sections = {
  lualine_a = {
    {
      'lsp_status',
      icon = '', -- f013
      symbols = {
        -- Standard unicode symbols to cycle through for LSP progress:
        spinner = { '⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏' },
        -- Standard unicode symbol for when LSP is done:
        done = '✓',
        -- Delimiter inserted between LSP names:
        separator = ' ',
      },
      -- List of LSP names to ignore (e.g., `null-ls`):
      ignore_lsp = {},
      -- Display the LSP name
      show_name = true,
    }
  }
}

Tabline

You can use lualine to display components in tabline. The configuration for tabline sections is exactly the same as that of the statusline.

tabline = {
  lualine_a = {},
  lualine_b = {'branch'},
  lualine_c = {'filename'},
  lualine_x = {},
  lualine_y = {},
  lualine_z = {}
}

This will show the branch and filename components on top of neovim inside tabline.

lualine also provides 2 components, buffers and tabs, that you can use to get a more traditional tabline/bufferline.

tabline = {
  lualine_a = {'buffers'},
  lualine_b = {'branch'},
  lualine_c = {'filename'},
  lualine_x = {},
  lualine_y = {},
  lualine_z = {'tabs'}
}

Winbar

From neovim-0.8 you can customize your winbar with lualine. Winbar configuration is similar to statusline.

winbar = {
  lualine_a = {},
  lualine_b = {},
  lualine_c = {'filename'},
  lualine_x = {},
  lualine_y = {},
  lualine_z = {}
}

inactive_winbar = {
  lualine_a = {},
  lualine_b = {},
  lualine_c = {'filename'},
  lualine_x = {},
  lualine_y = {},
  lualine_z = {}
}

Just like statusline you can separately specify winbar for active and inactive windows. Any lualine component can be placed in winbar. All kinds of custom components supported in statusline are also supported for winbar too. In general You can treat winbar as another lualine statusline that just appears on top of windows instead of at bottom.

Buffers

Shows currently open buffers. Like bufferline . See buffers options for all builtin behaviors of buffers component. You can use :LualineBuffersJump to jump to buffer based on index of buffer in buffers component. Jumping to non-existent buffer indices generates an error. To avoid these errors LualineBuffersJump provides <bang> support, meaning that you can call :LualineBufferJump! to ignore these errors.

  :LualineBuffersJump 2  " Jumps to 2nd buffer in buffers component.
  :LualineBuffersJump $  " Jumps to last buffer in buffers component.
  :LualineBuffersJump! 3  " Attempts to jump to 3rd buffer, if it exists.

Tabs

Shows currently open tab. Like usual tabline. See tabs options for all builtin behaviors of tabs component. You can also use :LualineRenameTab to set a name for a tabpage. For example:

:LualineRenameTab Project_K

It's useful when you're using rendering mode 2/3 in tabs. To unname a tabpage run :LualineRenameTab without argument.

Tabline as statusline

You can also completely move your statusline to a tabline by configuring lualine.tabline and disabling lualine.sections and lualine.inactive_sections:

tabline = {
......
  },
sections = {},
inactive_sections = {},

If you want a more sophisticated tabline you can use other tabline plugins with lualine too, for example:

tabline.nvim even uses lualine's theme by default 🙌 You can find a bigger list here.

Extensions

lualine extensions change statusline appearance for a window/buffer with specified filetypes.

By default no extensions are loaded to improve performance. You can load extensions with:

extensions = {'quickfix'}

Available extensions

aerial
assistant
avante
chadtree
ctrlspace
fern
fugitive
fzf
lazy
man
mason
mundo
neo-tree
nerdtree
nvim-dap-ui
nvim-tree
oil
overseer
quickfix
symbols-outline
toggleterm
trouble

Custom extensions

You can define your own extensions. If you believe an extension may be useful to others, then please submit a PR.

local my_extension = { sections = { lualine_a = {'mode'} }, filetypes = {'lua'} }
require('lualine').setup { extensions = { my_extension } }

Refreshing lualine

By default lualine refreshes itself based on timer and some events. You can set the interval of the timer with refresh option. However you can also force lualine to refresh at any time by calling lualine.refresh function.

require('lualine').refresh({
  scope = 'tabpage',  -- scope of refresh all/tabpage/window
  place = { 'statusline', 'winbar', 'tabline' },  -- lualine segment ro refresh.
})

The arguments shown here are default values. So not passing any of them will be treated as if a default value was passed.

So you can simply do

require('lualine').refresh()

Also, note by default when you call refresh a refresh event is queued in lualine. It desn't refresh event immidiately. It'll refresh on next refresh check pass. By default this time is set to 16ms to match 60fps. This duration can be configured with options.refresh.refresh_time option. If you want to bypass the refresh queue and want lualine to process the refresh immmidiately call refresh with force=true parameter set like this.

require('lualine').refresh({
  force = true,       -- do an immidiate refresh
  scope = 'tabpage',  -- scope of refresh all/tabpage/window
  place = { 'statusline', 'winbar', 'tabline' },  -- lualine segment ro refresh.
})

Practically, speaking this is almost never needed. Also you should avoid calling lualine.refresh with force inside components. Since components are evaluated during refresh, calling refresh while refreshing can have undesirable effects.

Disabling lualine

You can disable lualine for specific filetypes:

options = { disabled_filetypes = {'lua'} }

You can also disable lualine completely. Note that you need to call this after the setup

  require('lualine').hide({
    place = {'statusline', 'tabline', 'winbar'}, -- The segment this change applies to.
    unhide = false,  -- whether to re-enable lualine again/
  })

The arguments show for hide above are default values. Which means even if the hide function is called without arguments it'll work as if these were passed.

So in short to disable lualine completely you can do

require('lualine').hide()

To enable it again you can do

require('lualine').hide({unhide=true})

Contributors

Thanks to these wonderful people, we enjoy this awesome plugin.

Wiki

Check out the wiki for more info.

You can find some useful configuration snippets here. You can also share your awesome snippets with others.

If you want to extend lualine with plugins or want to know which ones already do, wiki/plugins is for you.

koreader/koreader

An ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Cervantes, Kindle, Kobo, PocketBook and Android devices

KOReader is a document viewer primarily aimed at e-ink readers.

Download • User guide • Wiki • Developer docs

Main features

portable: runs on embedded devices (Cervantes, Kindle, Kobo, PocketBook, reMarkable), Android and Linux computers. Developers can run a KOReader emulator in Linux and MacOS.
multi-format documents: supports fixed page formats (PDF, DjVu, CBT, CBZ) and reflowable e-book formats (EPUB, FB2, Mobi, DOC, RTF, HTML, CHM, TXT). Scanned PDF/DjVu documents can also be reflowed with the built-in K2pdfopt library. ZIP files are also supported for some formats.
full-featured reading: multi-lingual user interface with a highly customizable reader view and many typesetting options. You can set arbitrary page margins, override line spacing and choose external fonts and styles. It has multi-lingual hyphenation dictionaries bundled into the application.
integrated with calibre (search metadata, receive ebooks wirelessly, browse library via OPDS), Wallabag, Wikipedia, Google Translate and other content providers.
optimized for e-ink devices: custom UI without animation, with paginated menus, adjustable text contrast, and easy zoom to fit content or page in paged media.
extensible: via plugins
fast: on some older devices, it has been measured to have less than half the page-turn delay as the built in reading software.
and much more: look up words with StarDict dictionaries / Wikipedia, add your own online OPDS catalogs and RSS feeds, over-the-air software updates, an FTP client, an SSH server, …

Please check the user guide and the wiki to discover more features and to help us document them.

Screenshots

Installation

Please follow the model specific steps for your device:

Android • Cervantes • Kindle • Kobo • Linux • Pocketbook • reMarkable

Development

Setting up a build environment • Collaborating with Git • Building targets • Porting • Developer docs

Support

KOReader is developed and supported by volunteers all around the world. There are many ways you can help:

fix bugs and implement new features
translate the program into your language or improve an existing translation
document lesser-known features on the wiki
help others with your knowledge on the forum

Right now we only support liberapay donations.

Contributors

igorlfs/nvim-dap-view

Visualize debugging sessions in neovim

nvim-dap-view

Modern debugging UI for neovim

https://github.com/user-attachments/assets/357bb05d-5645-4cfc-9975-97313c57e770

Introduction

A UI for nvim-dap (the quasi canonical neovim implementation of DAP; the protocol that enhances text editors with IDE-like debugging capabilities).

Installation

Warning

Requires neovim 0.11+

Via lazy.nvim

return {
    {
        "igorlfs/nvim-dap-view",
        -- let the plugin lazy load itself
        lazy = false,
        version = "1.*",
        ---@module 'dap-view'
        ---@type dapview.Config
        opts = {},
    },
}

Features

Watch expressions

Navigate in the call stack

Manipulate breakpoints

Inspect and modify variables in scope

REPL

Inline virtual text variables

" alt="image" />

And more!

Getting Started

Start a regular debugging session. When desired, you can use :DapViewOpen to start the plugin. You can switch to another section using the letter outlined in the 'winbar' (e.g., B for "Breakpoints"). Explore what you can do in each section by using g? to inspect the keymaps.

Once you're done debugging, you can close the plugin with :DapViewClose and then terminate your session as usual.

There's a lot more you can do: nvim-dap-view is highly customizable. To learn all the options, commands, tips and tricks, visit the full documentation on the website.

Contributing

You can contribute in many ways:

If you have any questions, create a discussion.
If something isn't working, create a bug report.
If you have an idea, file a feature request. You can also go ahead and implement it yourself with a PR.
If you have some spare bucks, consider becoming a sponsor.

ibhagwan/fzf-lua

Improved fzf.vim written in lua

fzf ❤️ lua

Quickstart • Installation • Usage • Commands • Customization • Wiki

“because you can and you love fzf” - @junegunn

"fzf changed my command life, it can change yours too, if you allow it" - @ibhagwan

Quickstart

To quickly test this plugin without changing your configuration run (will run in its own sandbox with the default keybinds below):

Note

it's good practice to first read the script before running sh -c directly from the web

sh -c "$(curl -s https://raw.githubusercontent.com/ibhagwan/fzf-lua/main/scripts/mini.sh)"

Key	Command	Key	Command
`<C-\>`	buffers	`<C-p>`	files
`<C-g>`	grep	`<C-l>`	live_grep
`<C-k>`	builtin commands	`<F1>`	neovim help

Installation

Using lazy.nvim

{
  "ibhagwan/fzf-lua",
  -- optional for icon support
  dependencies = { "nvim-tree/nvim-web-devicons" },
  -- or if using mini.icons/mini.nvim
  -- dependencies = { "nvim-mini/mini.icons" },
  ---@module "fzf-lua"
  ---@type fzf-lua.Config|{}
  ---@diagnostic disable: missing-fields
  opts = {}
  ---@diagnostic enable: missing-fields
}

Show dependencies

Dependencies

neovim version >= 0.9
fzf version > 0.36 or skim binary installed
nvim-web-devicons or mini.icons (optional)

Optional dependencies

fd - better find utility
rg - better grep utility
bat - syntax highlighted previews when using fzf's native previewer
delta - syntax highlighted git pager for git status previews
jj - for Jujutsu commands (jj_files, vcs_files)
nvim-dap - for Debug Adapter Protocol (DAP) support
nvim-treesitter-context - for viewing treesitter context within the previewer
render-markdown.nvim or markview.nvim - for rendering markdown files in the previewer

Below are a few optional dependencies for viewing media files (which you need to configure in previewer.builtin.extensions):

chafa - terminal image previewer (recommended, supports most file formats)
viu - terminal image previewer
ueberzugpp - terminal image previewer using X11/Wayland child windows, sixels, kitty and iterm2

Tip

If your terminal supports the kitty graphics protocol (e.g. kitty, ghostty, etc) install @folke's snacks.nvim to render images using the snacks.image module, it will be auto-detected by fzf-lua and requires no configuration.

Windows Notes

rg is required for grep and tags
git for Windows is required for git (though installing git-bash|sh is not required).
Installation of dependencies (fzf, rg, fd, etc) is possible via scoop, chocolatey or winget-cli
Although almost everything works on Windows exactly as the *NIX/OSX check out the Windows README for known issues and limitations.

Usage

Fzf-lua aims to be as plug and play as possible with sane defaults, you can run any fzf-lua command like this:

:lua require("fzf-lua").files()
-- once loaded we can use the global object
:lua FzfLua.files()
-- or the vim command:
:FzfLua files

or with arguments:

:lua FzfLua.files({ cwd = '~/.config' })
-- or using the `FzfLua` vim command:
:FzfLua files cwd=~/.config

Resume

Resuming work from where you left off is as easy as:

:lua FzfLua.resume()
-- or
:FzfLua resume

Alternatively, resuming work on a specific picker:

:lua FzfLua.files({ resume = true })
-- or
:FzfLua files resume=true

Combining Pickers

Fzf-Lua can combine any of the available pickers into a single display using the combine method, for example file history (oldfiles) and git-files:

:lua FzfLua.combine({ pickers = "oldfiles;git_files" })
-- or using the `FzfLua` vim command:
:FzfLua combine pickers=oldfiles;git_files

Note

The first picker options determine the options used by the combined picker, that includes formatters, previewer, path_shorten, etc. To avoid errors combine only pickers of the same entry types (i.e files)

Global Picker

Fzf-Lua conveniently comes with a VS-Code like picker by default (customizable) combining files, buffers and LSP symbols:

Prefix	Behavior
`no prefix`	Files
`$`	Buffers
`@`	LSP Symbols (current buffer)
`#`	LSP Symbols (workspace/project)

:lua FzfLua.global()
-- or using the `FzfLua` vim command:
:FzfLua global

LIST OF AVAILABLE COMMANDS BELOW 👇

Commands

Buffers and Files

Command	List
`buffers`	open buffers
`files`	`find` or `fd` on a path
`oldfiles`	opened files history
`history`	opened buffers/files history
`quickfix`	quickfix list
`quickfix_stack`	quickfix stack
`loclist`	location list
`loclist_stack`	location stack
`lines`	open buffers lines
`blines`	current buffer lines
`treesitter`	current buffer treesitter symbols
`tabs`	open tabs
`args`	argument list
`vcs_files`	`jj`/`git` files or `find`/`fd`

Search

Command	List
`grep`	search for a pattern with `grep` or `rg`
`grep_last`	run search again with the last pattern
`grep_cword`	search word under cursor
`grep_cWORD`	search WORD under cursor
`grep_visual`	search visual selection
`grep_project`	search all project lines (fzf.vim's `:Rg`)
`grep_curbuf`	search current buffer lines
`grep_quickfix`	search the quickfix list
`grep_loclist`	search the location list
`lgrep_curbuf`	live grep current buffer
`lgrep_quickfix`	live grep the quickfix list
`lgrep_loclist`	live grep the location list
`live_grep`	live grep current project
`live_grep_resume`	live grep continue last search
`live_grep_glob`	live_grep with `rg --glob` support
`live_grep_native`	performant version of `live_grep`

Command	List
`tags`	search project tags
`btags`	search buffer tags
`tags_grep`	grep project tags
`tags_grep_cword`	`tags_grep` word under cursor
`tags_grep_cWORD`	`tags_grep` WORD under cursor
`tags_grep_visual`	`tags_grep` visual selection
`tags_live_grep`	live grep project tags

Command	List
`git_files`	`git ls-files`
`git_status`	`git status`
`git_diff`	`git diff {ref}`
`git_hunks`	`git hunks {ref}`
`git_reflog`	`git reflog`
`git_commits`	git commit log (project)
`git_bcommits`	git commit log (buffer)
`git_blame`	git blame (buffer)
`git_branches`	git branches
`git_worktrees`	git worktrees
`git_tags`	git tags
`git_stash`	git stash

Command	List
`jj_files`	`jj file list` tracked files

LSP/Diagnostics

Command	List
`lsp_references`	References
`lsp_definitions`	Definitions
`lsp_declarations`	Declarations
`lsp_typedefs`	Type Definitions
`lsp_implementations`	Implementations
`lsp_document_symbols`	Document Symbols
`lsp_workspace_symbols`	Workspace Symbols
`lsp_live_workspace_symbols`	Workspace Symbols (live query)
`lsp_incoming_calls`	Incoming Calls
`lsp_outgoing_calls`	Outgoing Calls
`lsp_type_sub`	Sub Types
`lsp_type_super`	Super Types
`lsp_code_actions`	Code Actions
`lsp_finder`	All LSP locations, combined view
`diagnostics_document`	Document Diagnostics
`diagnostics_workspace`	Workspace Diagnostics
`lsp_document_diagnostics`	alias to `diagnostics_document`
`lsp_workspace_diagnostics`	alias to `diagnostics_workspace`

Misc

Command	List
`resume`	resume last command/query
`builtin`	fzf-lua builtin commands
`combine`	combine different fzf-lua pickers
`global`	global picker for files,buffers and symbols
`profiles`	fzf-lua configuration profiles
`helptags`	help tags
`manpages`	man pages
`colorschemes`	color schemes
`awesome_colorschemes`	Awesome Neovim color schemes
`highlights`	highlight groups
`commands`	neovim commands
`command_history`	command history
`search_history`	search history
`marks`	:marks
`jumps`	:jumps
`changes`	:changes
`registers`	:registers
`tagstack`	:tags
`autocmds`	:autocmd
`nvim_options`	neovim options
`keymaps`	key mappings
`filetypes`	filetypes
`menus`	menus
`spellcheck`	misspelled words in buffer
`spell_suggest`	spelling suggestions
`packadd`	:packadd
`undotree`	history undo tree

Neovim API

:help vim.ui.select for more info

Command	List
`register_ui_select`	register fzf-lua as the UI interface for `vim.ui.select`
`deregister_ui_select`	de-register fzf-lua with `vim.ui.select`

nvim-dap

Requires nvim-dap

Command	List
`dap_commands`	list,run `nvim-dap` builtin commands
`dap_configurations`	list,run debug configurations
`dap_breakpoints`	list,delete breakpoints
`dap_variables`	active session variables
`dap_frames`	active session jump to frame

Tmux

tmux

Command	List
`tmux_buffers`	list tmux paste buffers

Zoxide

zoxide

Command	List
`zoxide`	list recent directories

Completion Functions

Command	List
`complete_path`	complete path under cursor (incl dirs)
`complete_file`	complete file under cursor (excl dirs)
`complete_line`	complete line (all open buffers)
`complete_bline`	complete line (current buffer only)

Customization

Note

Refer to OPTIONS to see detailed usage notes and a comprehensive list of yet more(!) available options.

require("fzf-lua").setup {
  -- MISC GLOBAL SETUP OPTIONS, SEE BELOW
  -- fzf_bin = ...,
  -- each of these options can also be passed as function that return options table
  -- e.g. winopts = function() return { ... } end
  winopts = { ...  },     -- UI Options
  keymap = { ...  },      -- Neovim keymaps / fzf binds
  actions = { ...  },     -- Fzf "accept" binds
  fzf_opts = { ...  },    -- Fzf CLI flags
  fzf_colors = { ...  },  -- Fzf `--color` specification
  hls = { ...  },         -- Highlights
  previewers = { ...  },  -- Previewers options
  -- SPECIFIC COMMAND/PICKER OPTIONS, SEE BELOW
  -- files = { ... },
}

DEFAULT OPTIONS OF THE DIFFERENT CONFIG SECTIONS BELOW 👇

globals

  -- Use skim (or a speccific fzf binary/version) instead of fzf?
  -- fzf_bin = 'sk',
  -- Padding can help kitty term users with double-width icon rendering
  file_icon_padding = '',
  -- Uncomment if your terminal/font does not support unicode character
  -- 'EN SPACE' (U+2002), the below sets it to 'NBSP' (U+00A0) instead
  -- nbsp = '\xc2\xa0',
  -- Function override for opening the help window (default bound to `<F1>`)
  -- Override this function if you want to customize window config of the
  -- help window (location, width, border, etc.)
  help_open_win = vim.api.nvim_open_win,

winopts

winopts = {
    -- split = "belowright new",-- open in a split instead?
            -- "belowright new"  : split below
            -- "aboveleft new"   : split above
            -- "belowright vnew" : split right
            -- "aboveleft vnew   : split left
    -- Only valid when using a float window
    -- (i.e. when 'split' is not defined, default)
    height           = 0.85,            -- window height
    width            = 0.80,            -- window width
    row              = 0.35,            -- window row position (0=top, 1=bottom)
    col              = 0.50,            -- window col position (0=left, 1=right)
    -- border argument passthrough to nvim_open_win()
    border           = "rounded",
    -- Backdrop opacity, 0 is fully opaque, 100 is fully transparent (i.e. disabled)
    backdrop         = 60,
    -- title         = "Title",
    -- title_pos     = "center",        -- 'left', 'center' or 'right'
    -- title_flags   = false,           -- uncomment to disable title flags
    fullscreen       = false,           -- start fullscreen?
    -- enable treesitter highlighting for the main fzf window will only have
    -- effect where grep like results are present, i.e. "file:line:col:text"
    -- due to highlight color collisions will also override `fzf_colors`
    -- set `fzf_colors=false` or `fzf_colors.hl=...` to override
    treesitter       = {
      enabled    = true,
      fzf_colors = { ["hl"] = "-1:reverse", ["hl+"] = "-1:reverse" }
    },
    preview = {
      -- default     = 'bat',           -- override the default previewer?
                                        -- default uses the 'builtin' previewer
      border         = "rounded",       -- preview border: accepts both `nvim_open_win`
                                        -- and fzf values (e.g. "border-top", "none")
                                        -- native fzf previewers (bat/cat/git/etc)
                                        -- can also be set to `fun(winopts, metadata)`
      wrap           = false,           -- preview line wrap (fzf's 'wrap|nowrap')
      hidden         = false,           -- start preview hidden
      vertical       = "down:45%",      -- up|down:size
      horizontal     = "right:60%",     -- right|left:size
      layout         = "flex",          -- horizontal|vertical|flex
      flip_columns   = 100,             -- #cols to switch to horizontal on flex
      -- Only used with the builtin previewer:
      title          = true,            -- preview border title (file/buf)?
      title_pos      = "center",        -- left|center|right, title alignment
      scrollbar      = "float",         -- `false` or string:'float|border'
                                        -- float:  in-window floating border
                                        -- border: in-border "block" marker
      scrolloff      = -1,              -- float scrollbar offset from right
                                        -- applies only when scrollbar = 'float'
      delay          = 20,              -- delay(ms) displaying the preview
                                        -- prevents lag on fast scrolling
      winopts = {                       -- builtin previewer window options
        number            = true,
        relativenumber    = false,
        cursorline        = true,
        cursorlineopt     = "both",
        cursorcolumn      = false,
        signcolumn        = "no",
        list              = false,
        foldenable        = false,
        foldmethod        = "manual",
      },
    },
    on_create = function()
      -- called once upon creation of the fzf main window
      -- can be used to add custom fzf-lua mappings, e.g:
      --   vim.keymap.set("t", "<C-j>", "<Down>", { silent = true, buffer = true })
    end,
    -- called once _after_ the fzf interface is closed
    -- on_close = function() ... end
}

keymap

keymap = {
    -- Below are the default binds, setting any value in these tables will override
    -- the defaults, to inherit from the defaults change [1] from `false` to `true`
    builtin = {
      -- neovim `:tmap` mappings for the fzf win
      -- true,        -- uncomment to inherit all the below in your custom config
      ["<M-Esc>"]     = "hide",     -- hide fzf-lua, `:FzfLua resume` to continue
      ["<F1>"]        = "toggle-help",
      ["<F2>"]        = "toggle-fullscreen",
      -- Only valid with the 'builtin' previewer
      ["<F3>"]        = "toggle-preview-wrap",
      ["<F4>"]        = "toggle-preview",
      -- Rotate preview clockwise/counter-clockwise
      ["<F5>"]        = "toggle-preview-cw",
      -- Preview toggle behavior default/extend
      ["<F6>"]        = "toggle-preview-behavior",
      -- `ts-ctx` binds require `nvim-treesitter-context`
      ["<F7>"]        = "toggle-preview-ts-ctx",
      ["<F8>"]        = "preview-ts-ctx-dec",
      ["<F9>"]        = "preview-ts-ctx-inc",
      ["<S-Left>"]    = "preview-reset",
      ["<S-down>"]    = "preview-page-down",
      ["<S-up>"]      = "preview-page-up",
      ["<M-S-down>"]  = "preview-down",
      ["<M-S-up>"]    = "preview-up",
    },
    fzf = {
      -- fzf '--bind=' options
      -- true,        -- uncomment to inherit all the below in your custom config
      ["ctrl-z"]      = "abort",
      ["ctrl-u"]      = "unix-line-discard",
      ["ctrl-f"]      = "half-page-down",
      ["ctrl-b"]      = "half-page-up",
      ["ctrl-a"]      = "beginning-of-line",
      ["ctrl-e"]      = "end-of-line",
      ["alt-a"]       = "toggle-all",
      ["alt-g"]       = "first",
      ["alt-G"]       = "last",
      -- Only valid with fzf previewers (bat/cat/git/etc)
      ["f3"]          = "toggle-preview-wrap",
      ["f4"]          = "toggle-preview",
      ["shift-down"]  = "preview-page-down",
      ["shift-up"]    = "preview-page-up",
    },
},

actions

actions = {
    -- Below are the default actions, setting any value in these tables will override
    -- the defaults, to inherit from the defaults change [1] from `false` to `true`
    files = {
      -- true,        -- uncomment to inherit all the below in your custom config
      -- Pickers inheriting these actions:
      --   files, git_files, git_status, grep, lsp, oldfiles, quickfix, loclist,
      --   tags, btags, args, buffers, tabs, lines, blines
      -- `file_edit_or_qf` opens a single selection or sends multiple selection to quickfix
      -- replace `enter` with `file_edit` to open all files/bufs whether single or multiple
      -- replace `enter` with `file_switch_or_edit` to attempt a switch in current tab first
      ["enter"]       = FzfLua.actions.file_edit_or_qf,
      ["ctrl-s"]      = FzfLua.actions.file_split,
      ["ctrl-v"]      = FzfLua.actions.file_vsplit,
      ["ctrl-t"]      = FzfLua.actions.file_tabedit,
      ["alt-q"]       = FzfLua.actions.file_sel_to_qf,
      ["alt-Q"]       = FzfLua.actions.file_sel_to_ll,
      ["alt-i"]       = FzfLua.actions.toggle_ignore,
      ["alt-h"]       = FzfLua.actions.toggle_hidden,
      ["alt-f"]       = FzfLua.actions.toggle_follow,
    },
  }

fzf_opts

fzf_opts = {
    -- options are sent as `<left>=<right>`
    -- set to `false` to remove a flag
    -- set to `true` for a no-value flag
    -- for raw args use `fzf_args` instead
    ["--ansi"]           = true,
    ["--info"]           = "inline-right", -- fzf < v0.42 = "inline"
    ["--height"]         = "100%",
    ["--layout"]         = "reverse",
    ["--border"]         = "none",
    ["--highlight-line"] = true,           -- fzf >= v0.53
  }

-- Only used when fzf_bin = "fzf-tmux", by default opens as a
-- popup 80% width, 80% height (note `-p` requires tmux > 3.2)
-- and removes the sides margin added by `fzf-tmux` (fzf#3162)
-- for more options run `fzf-tmux --help`
-- NOTE: since fzf v0.53 / sk v0.15 it is recommended to use
-- native tmux integration by adding the below to `fzf_opts`
-- fzf_opts = { ["--tmux"] = "center,80%,60%" }
fzf_tmux_opts = { ["-p"] = "80%,80%", ["--margin"] = "0,0" },

fzf_colors

Note

See the Fzf Colors section for more info.

  -- 
  -- Set fzf's terminal colorscheme (optional)
  --
  -- Set to `true` to automatically generate an fzf's colorscheme from
  -- Neovim's current colorscheme:
  -- fzf_colors       = true,
  -- 
  -- Building a custom colorscheme, has the below specifications:
  -- If rhs is of type "string" rhs will be passed raw, e.g.:
  --   `["fg"] = "underline"` will be translated to `--color fg:underline`
  -- If rhs is of type "table", the following convention is used:
  --   [1] "what" field to extract from the hlgroup, i.e "fg", "bg", etc.
  --   [2] Neovim highlight group(s), can be either "string" or "table"
  --       when type is "table" the first existing highlight group is used
  --   [3+] any additional fields are passed raw to fzf's command line args
  -- Example of a "fully loaded" color option:
  --   `["fg"] = { "fg", { "NonExistentHl", "Comment" }, "underline", "bold" }`
  -- Assuming `Comment.fg=#010101` the resulting fzf command line will be:
  --   `--color fg:#010101:underline:bold`
  -- NOTE: to pass raw arguments `fzf_opts["--color"]` or `fzf_args`
  -- NOTE: below is an example, not the defaults:
  fzf_colors = {
      true,   -- inherit fzf colors that aren't specified below from
              -- the auto-generated theme similar to `fzf_colors=true`
      ["fg"]          = { "fg", "CursorLine" },
      ["bg"]          = { "bg", "Normal" },
      ["hl"]          = { "fg", "Comment" },
      ["fg+"]         = { "fg", "Normal", "underline" },
      ["bg+"]         = { "bg", { "CursorLine", "Normal" } },
      ["hl+"]         = { "fg", "Statement" },
      ["info"]        = { "fg", "PreProc" },
      ["prompt"]      = { "fg", "Conditional" },
      ["pointer"]     = { "fg", "Exception" },
      ["marker"]      = { "fg", "Keyword" },
      ["spinner"]     = { "fg", "Label" },
      ["header"]      = { "fg", "Comment" },
      ["gutter"]      = "-1",
  },

hls

Note

See the highlights section below for all available highlight groups.

hls = {
    normal = "Normal"          -- highlight group for normal fg/bg
    preview_normal = "Normal"  -- highlight group for preview fg/bg
    ...
}

previewers

previewers = {
    cat = {
      cmd             = "cat",
      args            = "-n",
    },
    bat = {
      cmd             = "bat",
      args            = "--color=always --style=numbers,changes",
    },
    head = {
      cmd             = "head",
      args            = nil,
    },
    git_diff = {
      -- if required, use `{file}` for argument positioning
      -- e.g. `cmd_modified = "git diff --color HEAD {file} | cut -c -30"`
      cmd_deleted     = "git diff --color HEAD --",
      cmd_modified    = "git diff --color HEAD",
      cmd_untracked   = "git diff --color --no-index /dev/null",
      -- git-delta is automatically detected as pager, set `pager=false`
      -- to disable, can also be set under 'git.status.preview_pager'
    },
    man = {
      -- NOTE: remove the `-c` flag when using man-db
      -- replace with `man -P cat %s | col -bx` on OSX
      cmd             = "man -c %s | col -bx",
    },
    builtin = {
      syntax          = true,         -- preview syntax highlight?
      syntax_limit_l  = 0,            -- syntax limit (lines), 0=nolimit
      syntax_limit_b  = 1024*1024,    -- syntax limit (bytes), 0=nolimit
      limit_b         = 1024*1024*10, -- preview limit (bytes), 0=nolimit
      -- previewer treesitter options:
      -- enable specific filetypes with: `{ enabled = { "lua" } }
      -- exclude specific filetypes with: `{ disabled = { "lua" } }
      -- disable `nvim-treesitter-context` with `context = false`
      -- disable fully with: `treesitter = false` or `{ enabled = false }`
      treesitter      = {
        enabled = true,
        disabled = {},
        -- nvim-treesitter-context config options
        context = { max_lines = 1, trim_scope = "inner" }
      },
      -- By default, the main window dimensions are calculated as if the
      -- preview is visible, when hidden the main window will extend to
      -- full size. Set the below to "extend" to prevent the main window
      -- from being modified when toggling the preview.
      toggle_behavior = "default",
      -- Title transform function, by default only displays the tail
      -- title_fnamemodify = function(s) return vim.fn.fnamemodify(s, ":t") end,
      -- preview extensions using a custom shell command:
      -- for example, use `viu` for image previews
      -- will do nothing if `viu` isn't executable
      extensions      = {
        -- neovim terminal only supports `viu` block output
        ["png"]       = { "viu", "-b" },
        -- by default the filename is added as last argument
        -- if required, use `{file}` for argument positioning
        ["svg"]       = { "chafa", "{file}" },
        ["jpg"]       = { "ueberzug" },
      },
      -- if using `ueberzug` in the above extensions map
      -- set the default image scaler, possible scalers:
      --   false (none), "crop", "distort", "fit_contain",
      --   "contain", "forced_cover", "cover"
      -- https://github.com/seebye/ueberzug
      ueberzug_scaler = "cover",
      -- render_markdown.nvim integration, enabled by default for markdown
      render_markdown = { enabled = true, filetypes = { ["markdown"] = true } },
      -- snacks.images integration, enabled by default
      snacks_image = { enabled = true, render_inline = true },
    },
    -- Code Action previewers, default is "codeaction" (set via `lsp.code_actions.previewer`)
    -- "codeaction_native" uses fzf's native previewer, recommended when combined with git-delta
    codeaction = {
      -- options for vim.diff(): https://neovim.io/doc/user/lua.html#vim.diff()
      diff_opts = { ctxlen = 3 },
    },
    codeaction_native = {
      diff_opts = { ctxlen = 3 },
      -- git-delta is automatically detected as pager, set `pager=false`
      -- to disable, can also be set under 'lsp.code_actions.preview_pager'
      -- recommended styling for delta
      --pager = [[delta --width=$COLUMNS --hunk-header-style="omit" --file-style="omit"]],
    },
}

picker options

  -- use `defaults` (table or function) if you wish to set "global-picker" defaults
  -- for example, using "mini.icons" globally and open the quickfix list at the top
  --   defaults = {
  --     file_icons   = "mini",
  --     copen        = "topleft copen",
  --   },
  files = {
    -- previewer      = "bat",          -- uncomment to override previewer
                                        -- (name from 'previewers' table)
                                        -- set to 'false' to disable
    prompt            = 'Files❯ ',
    multiprocess      = true,           -- run command in a separate process
    git_icons         = false,          -- show git icons?
    file_icons        = true,           -- show file icons (true|"devicons"|"mini")?
    color_icons       = true,           -- colorize file|git icons
    -- path_shorten   = 1,              -- 'true' or number, shorten path?
    -- Uncomment for custom vscode-like formatter where the filename is first:
    -- e.g. "fzf-lua/previewer/fzf.lua" => "fzf.lua previewer/fzf-lua"
    -- formatter      = "path.filename_first",
    -- executed command priority is 'cmd' (if exists)
    -- otherwise auto-detect prioritizes `fd`:`rg`:`find`
    -- default options are controlled by 'fd|rg|find|_opts'
    -- cmd            = "rg --files",
    find_opts         = [[-type f \! -path '*/.git/*' \! -path '*/.jj/*']],
    rg_opts           = [[--color=never --files -g "!.git" -g "!.jj"]],
    fd_opts           = [[--color=never --type f --type l --exclude .git --exclude .jj]],
    dir_opts          = [[/s/b/a:-d]],
    -- by default, cwd appears in the header only if {opts} contain a cwd
    -- parameter to a different folder than the current working directory
    -- uncomment if you wish to force display of the cwd as part of the
    -- query prompt string (fzf.vim style), header line or both
    -- cwd_header = true,
    cwd_prompt             = true,
    cwd_prompt_shorten_len = 32,        -- shorten prompt beyond this length
    cwd_prompt_shorten_val = 1,         -- shortened path parts length
    toggle_ignore_flag = "--no-ignore", -- flag toggled in `actions.toggle_ignore`
    toggle_hidden_flag = "--hidden",    -- flag toggled in `actions.toggle_hidden`
    toggle_follow_flag = "-L",          -- flag toggled in `actions.toggle_follow`
    hidden             = true,          -- enable hidden files by default
    follow             = false,         -- do not follow symlinks by default
    no_ignore          = false,         -- respect ".gitignore"  by default
    absolute_path      = false,         -- display absolute paths
    actions = {
      -- inherits from 'actions.files', here we can override
      -- or set bind to 'false' to disable a default action
      -- uncomment to override `actions.file_edit_or_qf`
      --   ["enter"]     = actions.file_edit,
      -- custom actions are available too
      --   ["ctrl-y"]    = function(selected) print(selected[1]) end,
    }
  },
  git = {
    files = {
      prompt        = 'GitFiles❯ ',
      cmd           = 'git ls-files --exclude-standard',
      multiprocess  = true,           -- run command in a separate process
      git_icons     = true,           -- show git icons?
      file_icons    = true,           -- show file icons (true|"devicons"|"mini")?
      color_icons   = true,           -- colorize file|git icons
      -- force display the cwd header line regardless of your current working
      -- directory can also be used to hide the header when not wanted
      -- cwd_header = true
    },
    status = {
      prompt        = 'GitStatus❯ ',
      cmd           = "git -c color.status=false --no-optional-locks status --porcelain=v1 -u",
      multiprocess  = true,           -- run command in a separate process
      file_icons    = true,
      color_icons   = true,
      previewer     = "git_diff",
      -- git-delta is automatically detected as pager, uncomment to disable
      -- preview_pager = false,
      actions = {
        -- actions inherit from 'actions.files' and merge
        ["right"]  = { fn = actions.git_unstage, reload = true },
        ["left"]   = { fn = actions.git_stage, reload = true },
        ["ctrl-x"] = { fn = actions.git_reset, reload = true },
      },
      -- If you wish to use a single stage|unstage toggle instead
      -- using 'ctrl-s' modify the 'actions' table as shown below
      -- actions = {
      --   ["right"]   = false,
      --   ["left"]    = false,
      --   ["ctrl-x"]  = { fn = actions.git_reset, reload = true },
      --   ["ctrl-s"]  = { fn = actions.git_stage_unstage, reload = true },
      -- },
    },
    diff = {
      cmd               = "git --no-pager diff --name-only {ref}",
      ref               = "HEAD",
      preview           = "git diff {ref} {file}",
      -- git-delta is automatically detected as pager, uncomment to disable
      -- preview_pager = false,
      file_icons        = true,
      color_icons       = true,
      fzf_opts          = { ["--multi"] = true },
    },
    hunks = {
      cmd               = "git --no-pager diff --color=always {ref}",
      ref               = "HEAD",
      file_icons        = true,
      color_icons       = true,
      fzf_opts          = {
      ["--multi"] = true,
      ["--delimiter"] = ":",
      ["--nth"] = "3..",
      },
    },
    commits = {
      prompt        = 'Commits❯ ',
      cmd           = [[git log --color --pretty=format:"%C(yellow)%h%Creset ]]
          .. [[%Cgreen(%><(12)%cr%><|(12))%Creset %s %C(blue)<%an>%Creset"]],
      preview       = "git show --color {1}",
      -- git-delta is automatically detected as pager, uncomment to disable
      -- preview_pager = false,
      actions = {
        ["enter"]   = actions.git_checkout,
        -- remove `exec_silent` or set to `false` to exit after yank
        ["ctrl-y"]  = { fn = actions.git_yank_commit, exec_silent = true },
      },
    },
    bcommits = {
      prompt        = 'BCommits❯ ',
      -- default preview shows a git diff vs the previous commit
      -- if you prefer to see the entire commit you can use:
      --   git show --color {1} --rotate-to={file}
      --   {1}    : commit SHA (fzf field index expression)
      --   {file} : filepath placement within the commands
      cmd           = [[git log --color --pretty=format:"%C(yellow)%h%Creset ]]
          .. [[%Cgreen(%><(12)%cr%><|(12))%Creset %s %C(blue)<%an>%Creset" {file}]],
      preview       = "git show --color {1} -- {file}",
      -- git-delta is automatically detected as pager, uncomment to disable
      -- preview_pager = false,
      actions = {
        ["enter"]   = actions.git_buf_edit,
        ["ctrl-s"]  = actions.git_buf_split,
        ["ctrl-v"]  = actions.git_buf_vsplit,
        ["ctrl-t"]  = actions.git_buf_tabedit,
        ["ctrl-y"]  = { fn = actions.git_yank_commit, exec_silent = true },
      },
    },
    blame = {
      prompt        = "Blame> ",
      cmd           = [[git blame --color-lines {file}]],
      preview       = "git show --color {1} -- {file}",
      -- git-delta is automatically detected as pager, uncomment to disable
      -- preview_pager = false,
      actions = {
        ["enter"]  = actions.git_goto_line,
        ["ctrl-s"] = actions.git_buf_split,
        ["ctrl-v"] = actions.git_buf_vsplit,
        ["ctrl-t"] = actions.git_buf_tabedit,
        ["ctrl-y"] = { fn = actions.git_yank_commit, exec_silent = true },
      },
    },
    branches = {
      prompt   = 'Branches❯ ',
      cmd      = "git branch --all --color",
      preview  = "git log --graph --pretty=oneline --abbrev-commit --color {1}",
      remotes  = "local", -- "detach|local", switch behavior for remotes
      actions  = {
        ["enter"]   = actions.git_switch,
        ["ctrl-x"]  = { fn = actions.git_branch_del, reload = true },
        ["ctrl-a"]  = { fn = actions.git_branch_add, field_index = "{q}", reload = true },
      },
      -- If you wish to add branch and switch immediately
      -- cmd_add  = { "git", "checkout", "-b" },
      cmd_add  = { "git", "branch" },
      -- If you wish to delete unmerged branches add "--force"
      -- cmd_del  = { "git", "branch", "--delete", "--force" },
      cmd_del  = { "git", "branch", "--delete" },
    },
    tags = {
      prompt   = "Tags> ",
      cmd      = [[git for-each-ref --color --sort="-taggerdate" --format ]]
          .. [["%(color:yellow)%(refname:short)%(color:reset) ]]
          .. [[%(color:green)(%(taggerdate:relative))%(color:reset)]]
          .. [[ %(subject) %(color:blue)%(taggername)%(color:reset)" refs/tags]],
      preview  = [[git log --graph --color --pretty=format:"%C(yellow)%h%Creset ]]
          .. [[%Cgreen(%><(12)%cr%><|(12))%Creset %s %C(blue)<%an>%Creset" {1}]],
      actions  = { ["enter"] = actions.git_checkout },
    },
    stash = {
      prompt          = 'Stash> ',
      cmd             = "git --no-pager stash list",
      preview         = "git --no-pager stash show --patch --color {1}",
      actions = {
        ["enter"]     = actions.git_stash_apply,
        ["ctrl-x"]    = { fn = actions.git_stash_drop, reload = true },
      },
    },
    icons = {
      ["M"]           = { icon = "M", color = "yellow" },
      ["D"]           = { icon = "D", color = "red" },
      ["A"]           = { icon = "A", color = "green" },
      ["R"]           = { icon = "R", color = "yellow" },
      ["C"]           = { icon = "C", color = "yellow" },
      ["T"]           = { icon = "T", color = "magenta" },
      ["?"]           = { icon = "?", color = "magenta" },
      -- override git icons?
      -- ["M"]        = { icon = "★", color = "red" },
      -- ["D"]        = { icon = "✗", color = "red" },
      -- ["A"]        = { icon = "+", color = "green" },
    },
  },
  grep = {
    prompt            = 'Rg❯ ',
    input_prompt      = 'Grep For❯ ',
    multiprocess      = true,           -- run command in a separate process
    git_icons         = false,          -- show git icons?
    file_icons        = true,           -- show file icons (true|"devicons"|"mini")?
    color_icons       = true,           -- colorize file|git icons
    -- executed command priority is 'cmd' (if exists)
    -- otherwise auto-detect prioritizes `rg` over `grep`
    -- default options are controlled by 'rg|grep_opts'
    -- cmd            = "rg --vimgrep",
    grep_opts         = "--binary-files=without-match --line-number --recursive --color=auto --perl-regexp -e",
    rg_opts           = "--column --line-number --no-heading --color=always --smart-case --max-columns=4096 -e",
    hidden             = false,       -- disable hidden files by default
    follow             = false,       -- do not follow symlinks by default
    no_ignore          = false,       -- respect ".gitignore"  by default
    -- Uncomment to use the rg config file `$RIPGREP_CONFIG_PATH`
    -- RIPGREP_CONFIG_PATH = vim.env.RIPGREP_CONFIG_PATH
    --
    -- Set to 'true' to always parse globs in both 'grep' and 'live_grep'
    -- search strings will be split using the 'glob_separator' and translated
    -- to '--iglob=' arguments, requires 'rg'
    -- can still be used when 'false' by calling 'live_grep_glob' directly
    rg_glob           = true,         -- default to glob parsing with `rg`
    glob_flag         = "--iglob",    -- for case sensitive globs use '--glob'
    glob_separator    = "%s%-%-",     -- query separator pattern (lua): ' --'
    -- advanced usage: for custom argument parsing define
    -- 'rg_glob_fn' to return a pair:
    --   first returned argument is the new search query
    --   second returned argument are additional rg flags
    -- rg_glob_fn = function(query, opts)
    --   ...
    --   return new_query, flags
    -- end,
    --
    -- Enable with narrow term width, split results to multiple lines
    -- NOTE: multiline requires fzf >= v0.53 and is ignored otherwise
    -- multiline      = 1,      -- Display as: PATH:LINE:COL\nTEXT
    -- multiline      = 2,      -- Display as: PATH:LINE:COL\nTEXT\n
    actions = {
      -- actions inherit from 'actions.files' and merge
      -- this action toggles between 'grep' and 'live_grep'
      ["ctrl-g"]      = { actions.grep_lgrep }
      -- uncomment to enable '.gitignore' toggle for grep
      -- ["ctrl-r"]   = { actions.toggle_ignore }
    },
  },
  args = {
    prompt            = 'Args❯ ',
    files_only        = true,
    -- actions inherit from 'actions.files' and merge
    actions           = { ["ctrl-x"] = { fn = actions.arg_del, reload = true } },
  },
  oldfiles = {
    prompt            = 'History❯ ',
    cwd_only          = false,
    stat_file         = true,         -- verify files exist on disk
    -- can also be a lua function, for example:
    -- stat_file = FzfLua.utils.file_is_readable,
    -- stat_file = function() return true end,
    include_current_session = false,  -- include bufs from current session
    ignore_current_buffer   = true,   -- exclude current buf from session
  },
  buffers = {
    prompt            = 'Buffers❯ ',
    file_icons        = true,         -- show file icons (true|"devicons"|"mini")?
    color_icons       = true,         -- colorize file|git icons
    sort_lastused     = true,         -- sort buffers() by last used
    show_unloaded     = true,         -- show unloaded buffers
    cwd_only          = false,        -- buffers for the cwd only
    cwd               = nil,          -- buffers list for a given dir
    actions = {
      -- actions inherit from 'actions.files' and merge
      -- by supplying a table of functions we're telling
      -- fzf-lua to not close the fzf window, this way we
      -- can resume the buffers picker on the same window
      -- eliminating an otherwise unaesthetic win "flash"
      ["ctrl-x"]      = { fn = actions.buf_del, reload = true },
    }
  },
  tabs = {
    prompt            = 'Tabs❯ ',
    tab_title         = "Tab",
    tab_marker        = "<<",
    locate            = true,         -- position cursor at current window
    file_icons        = true,         -- show file icons (true|"devicons"|"mini")?
    color_icons       = true,         -- colorize file|git icons
    actions = {
      -- actions inherit from 'actions.files' and merge
      ["enter"]       = actions.buf_switch,
      ["ctrl-x"]      = { fn = actions.buf_del, reload = true },
    },
    fzf_opts = {
      -- hide tabnr
      ["--delimiter"] = "[\\):]",
      ["--with-nth"]  = '2..',
    },
  },
  -- `blines` has the same defaults as `lines` aside from prompt and `show_bufname`
  lines = {
    prompt            = 'Lines❯ ',
    file_icons        = true,
    show_bufname      = true,         -- display buffer name
    show_unloaded     = true,         -- show unloaded buffers
    show_unlisted     = false,        -- exclude 'help' buffers
    no_term_buffers   = true,         -- exclude 'term' buffers
    sort_lastused     = true,         -- sort by most recent
    winopts  = { treesitter = true }, -- enable TS highlights
    fzf_opts = {
      -- do not include bufnr in fuzzy matching
      -- tiebreak by line no.
      ["--multi"]     = true,
      ["--delimiter"] = "[\t]",
      ["--tabstop"]   = "1",
      ["--tiebreak"]  = "index",
      ["--with-nth"]  = "2..",
      ["--nth"]       = "4..",
    },
  },
  tags = {
    prompt                = 'Tags❯ ',
    ctags_file            = nil,      -- auto-detect from tags-option
    multiprocess          = true,
    file_icons            = true,
    color_icons           = true,
    -- 'tags_live_grep' options, `rg` prioritizes over `grep`
    rg_opts               = "--no-heading --color=always --smart-case",
    grep_opts             = "--color=auto --perl-regexp",
    fzf_opts              = { ["--tiebreak"] = "begin" },
    actions = {
      -- actions inherit from 'actions.files' and merge
      -- this action toggles between 'grep' and 'live_grep'
      ["ctrl-g"]          = { actions.grep_lgrep }
    },
  },
  btags = {
    prompt                = 'BTags❯ ',
    ctags_file            = nil,      -- auto-detect from tags-option
    ctags_autogen         = true,     -- dynamically generate ctags each call
    multiprocess          = true,
    file_icons            = false,
    rg_opts               = "--color=never --no-heading",
    grep_opts             = "--color=never --perl-regexp",
    fzf_opts              = { ["--tiebreak"] = "begin" },
    -- actions inherit from 'actions.files'
  },
  colorschemes = {
    prompt            = 'Colorschemes❯ ',
    live_preview      = true,       -- apply the colorscheme on preview?
    actions           = { ["enter"] = actions.colorscheme },
    winopts           = { height = 0.55, width = 0.30, },
    -- uncomment to ignore colorschemes names (lua patterns)
    -- ignore_patterns   = { "^delek$", "^blue$" },
  },
  awesome_colorschemes = {
    prompt            = 'Colorschemes❯ ',
    live_preview      = true,       -- apply the colorscheme on preview?
    max_threads       = 5,          -- max download/update threads
    winopts           = { row = 0, col = 0.99, width = 0.50 },
    fzf_opts          = {
      ["--multi"]     = true,
      ["--delimiter"] = "[:]",
      ["--with-nth"]  = "3..",
      ["--tiebreak"]  = "index",
    },
    actions           = {
      ["enter"]   = actions.colorscheme,
      ["ctrl-g"]  = { fn = actions.toggle_bg, exec_silent = true },
      ["ctrl-r"]  = { fn = actions.cs_update, reload = true },
      ["ctrl-x"]  = { fn = actions.cs_delete, reload = true },
    },
  },
  keymaps = {
    prompt            = "Keymaps> ",
    winopts           = { preview = { layout = "vertical" } },
    fzf_opts          = { ["--tiebreak"] = "index", },
    -- by default, we ignore <Plug> and <SNR> mappings
    -- set `ignore_patterns = false` to disable filtering
    ignore_patterns   = { "^<SNR>", "^<Plug>" },
    show_desc         = true,
    show_details      = true,
    actions           = {
      ["enter"]       = actions.keymap_apply,
      ["ctrl-s"]      = actions.keymap_split,
      ["ctrl-v"]      = actions.keymap_vsplit,
      ["ctrl-t"]      = actions.keymap_tabedit,
    },
  },
  nvim_options = {
    prompt            = "Nvim Options> ",
    separator         = "│",  -- separator between option name and value
    color_values      = true, -- colorize boolean values
    actions           = {
      ["enter"]     = { fn = actions.nvim_opt_edit_local, reload = true },
      ["alt-enter"] = { fn = actions.nvim_opt_edit_global, reload = true },
    },
  },
  quickfix = {
    file_icons        = true,
    valid_only        = false, -- select among only the valid quickfix entries
  },
  quickfix_stack = {
    prompt = "Quickfix Stack> ",
    marker = ">",                   -- current list marker
  },
  lsp = {
    prompt_postfix    = '❯ ',       -- will be appended to the LSP label
                                    -- to override use 'prompt' instead
    cwd_only          = false,      -- LSP/diagnostics for cwd only?
    async_or_timeout  = 5000,       -- timeout(ms) or 'true' for async calls
    file_icons        = true,
    git_icons         = false,
    jump1             = true,       -- skip the UI when result is a single entry
    jump1_action      = FzfLua.actions.file_edit
    -- The equivalent of using `includeDeclaration` in lsp buf calls, e.g:
    -- :lua vim.lsp.buf.references({includeDeclaration = false})
    includeDeclaration = true,      -- include current declaration in LSP context
    -- settings for 'lsp_{document|workspace|lsp_live_workspace}_symbols'
    symbols = {
        -- lsp_query      = "foo"       -- query passed to the LSP directly
        -- query          = "bar"       -- query passed to fzf prompt for fuzzy matching
        locate            = false,      -- attempt to position cursor at current symbol
        async_or_timeout  = true,       -- symbols are async by default
        symbol_style      = 1,          -- style for document/workspace symbols
                                        -- false: disable,    1: icon+kind
                                        --     2: icon only,  3: kind only
                                        -- NOTE: icons are extracted from
                                        -- vim.lsp.protocol.CompletionItemKind
        -- icons for symbol kind
        -- see https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#symbolKind
        -- see https://github.com/neovim/neovim/blob/829d92eca3d72a701adc6e6aa17ccd9fe2082479/runtime/lua/vim/lsp/protocol.lua#L117
        symbol_icons     = {
          File          = "󰈙",
          Module        = "",
          Namespace     = "󰦮",
          Package       = "",
          Class         = "󰆧",
          Method        = "󰊕",
          Property      = "",
          Field         = "",
          Constructor   = "",
          Enum          = "",
          Interface     = "",
          Function      = "󰊕",
          Variable      = "󰀫",
          Constant      = "󰏿",
          String        = "",
          Number        = "󰎠",
          Boolean       = "󰨙",
          Array         = "󱡠",
          Object        = "",
          Key           = "󰌋",
          Null          = "󰟢",
          EnumMember    = "",
          Struct        = "󰆼",
          Event         = "",
          Operator      = "󰆕",
          TypeParameter = "󰗴",
        },
        -- colorize using Treesitter '@' highlight groups ("@function", etc).
        -- or 'false' to disable highlighting
        symbol_hl         = function(s) return "@" .. s:lower() end,
        -- additional symbol formatting, works with or without style
        symbol_fmt        = function(s, opts) return "[" .. s .. "]" end,
        -- prefix child symbols. set to any string or `false` to disable
        child_prefix      = true,
        -- prepend parent to symbol, set to any string or `false` to disable
        -- parent_postfix    = ".",
        fzf_opts          = { ["--tiebreak"] = "begin" },
    },
    code_actions = {
        prompt            = 'Code Actions> ',
        async_or_timeout  = 5000,
        -- when git-delta is installed use "codeaction_native" for beautiful diffs
        -- try it out with `:FzfLua lsp_code_actions previewer=codeaction_native`
        -- scroll up to `previewers.codeaction{_native}` for more previewer options
        previewer        = "codeaction",
    },
    finder = {
        prompt      = "LSP Finder> ",
        file_icons  = true,
        color_icons = true,
        async       = true,         -- async by default
        silent      = true,         -- suppress "not found"
        separator   = "| ",         -- separator after provider prefix, `false` to disable
        includeDeclaration = true,  -- include current declaration in LSP context
        -- by default display all LSP locations
        -- to customize, duplicate table and delete unwanted providers
        providers   = {
            { "references",      prefix = FzfLua.utils.ansi_codes.blue("ref ") },
            { "definitions",     prefix = FzfLua.utils.ansi_codes.green("def ") },
            { "declarations",    prefix = FzfLua.utils.ansi_codes.magenta("decl") },
            { "typedefs",        prefix = FzfLua.utils.ansi_codes.red("tdef") },
            { "implementations", prefix = FzfLua.utils.ansi_codes.green("impl") },
            { "incoming_calls",  prefix = FzfLua.utils.ansi_codes.cyan("in  ") },
            { "outgoing_calls",  prefix = FzfLua.utils.ansi_codes.yellow("out ") },
            { "type_sub",        prefix = FzfLua.utils.utils.ansi_codes.cyan("sub ") },
            { "type_super",      prefix = FzfLua.utils.utils.ansi_codes.yellow("supr") },
        },
    }
  },
  diagnostics ={
    prompt            = 'Diagnostics❯ ',
    cwd_only          = false,
    file_icons        = false,
    git_icons         = false,
    color_headings    = true,   -- use diag highlights to color source & filepath
    diag_icons        = true,   -- display icons from diag sign definitions
    diag_source       = true,   -- display diag source (e.g. [pycodestyle])
    diag_code         = true,   -- display diag code (e.g. [undefined])
    icon_padding      = '',     -- add padding for wide diagnostics signs
    multiline         = 2,      -- split heading and diag to separate lines
    -- severity_only:   keep any matching exact severity
    -- severity_limit:  keep any equal or more severe (lower)
    -- severity_bound:  keep any equal or less severe (higher)
  },
  marks = {
    marks = "", -- filter vim marks with a lua pattern
    -- for example if you want to only show user defined marks
    -- you would set this option as %a this would match characters from [A-Za-z]
    -- or if you want to show only numbers you would set the pattern to %d (0-9).
  },
  complete_path = {
    cmd          = nil, -- default: auto detect fd|rg|find
    complete     = { ["enter"] = actions.complete },
    word_pattern = nil, -- default: "[^%s\"']*"
  },
  complete_file = {
    cmd          = nil, -- default: auto detect rg|fd|find
    file_icons   = true,
    color_icons  = true,
    word_pattern = nil,
    -- actions inherit from 'actions.files' and merge
    actions      = { ["enter"] = actions.complete },
    -- previewer hidden by default
    winopts      = { preview = { hidden = true } },
  },
  zoxide = {
    cmd          = "zoxide query --list --score",
    scope        = "global", -- cd action scope "local|win|tab"
    git_root     = false,    -- auto-detect git root
    formatter    = "path.dirname_first",
    fzf_opts     = {
      ["--no-multi"]  = true,
      ["--delimiter"] = "[\t]",
      ["--tabstop"]   = "4",
      ["--tiebreak"]  = "end,index", -- prefer dirs ending with search term
      ["--nth"]       = "2..",       -- exclude score from fuzzy matching
    },
    actions      = { enter = actions.cd }
  },
  -- uncomment to use fzf native previewers
  -- (instead of using a neovim floating window)
  -- manpages = { previewer = "man_native" },
  -- helptags = { previewer = "help_native" },

Tip

To experiment with different options without modifying the global config, options can be sent as inline parameters to the function calls. Expand below to see examples of inline customization and Refer to OPTIONS for yet more examples.

CLICK FOR EXAMPLES OF INLINE CUSTOMIZATION

Inline Customization

Different fzf layout:

:lua FzfLua.files({ fzf_opts = {['--layout'] = 'reverse-list'} })
-- Or via the vimL command
:FzfLua files fzf_opts.--layout=reverse-list

Using files with a different command and working directory:

:lua FzfLua.files({ prompt="LS> ", cmd = "ls", cwd="~/.config" })
-- Or via the vimL command
:FzfLua files prompt="LS>\ " cmd=ls cwd=~/.config

Using live_grep with git grep:

:lua FzfLua.live_grep({ cmd = "git grep --line-number --column --color=always" })

spell_suggest with non-default window size relative to cursor:

:lua FzfLua.spell_suggest({ winopts = { height=0.33, width=0.33, relative="cursor" } })
-- Or via the vimL command
:FzfLua spell_suggest winopts={height=0.33,width=0.33,relative=cursor}
:FzfLua spell_suggest winopts={height=0.33,width=0.33} winopts.relative=cursor

Profiles

Conveniently, fzf-lua comes with a set of preconfigured profiles if you do not want to tinker with customization.

Use :FzfLua profiles to experiment with the different profiles, once you've found what you like and wish to make the profile persist, send a string argument at the first index of the table sent to the setup function:

Tip

setup can be called multiple times for profile "live" switching, see profiles page for more info.

require('fzf-lua').setup({'fzf-native'})

You can also start with a profile as "baseline" and customize it, for example, telescope defaults with bat previewer:

:lua require"fzf-lua".setup({"telescope",winopts={preview={default="bat"}}})

Combining of profiles is also available by sending table instead of string as the first argument:

:lua require"fzf-lua".setup({{"telescope","fzf-native"},winopts={fullscreen=true}})

Tip

The default profile is a combination of border-fused+hide profiles, without the "hide" profile pressing esc terminates the fzf process which makes for an imperfect resume limited to resuming only the picker/query (without cursor position, selection, etc), to restore the default esc behavior combine any existing profile with "hide" by using a table in opts[1]:

require("fzf-lua").setup({
  { "fzf-native", "hide" },
  -- your other settings here
})

Coming from fzf.vim?

Easy! just use the fzf-vim profile:

require('fzf-lua').setup({'fzf-vim'})

Tip

Using the fzf-vim profile will automatically create fzf.vim's user commands (i.e. :Files, :Rg), if you wish to use a different profile you can create the same user commands by running :FzfLua setup_fzfvim_cmds.

CLICK TO SEE THE AVAILABLE PROFILES

Available Profiles

Profile	Details
`default`	fzf-lua defaults, uses neovim "builtin" buffer previewer and devicons (if available)
`default-title`	fzf-lua defaults, using title for picker info (default on neovim >= 0.9)
`default-prompt`	fzf-lua defaults, using prompt for picker info (default on neovim < 0.9)
`fzf-native`	utilizes fzf's native previewing ability in the terminal where possible using `bat` for previews
`fzf-tmux`	similar to `fzf-native` and opens in a tmux popup (requires tmux > 3.2)
`fzf-vim`	closest to `fzf.vim`'s defaults (+icons), also sets up user commands (`:Files`, `:Rg`, etc)
`max-perf`	similar to `fzf-native` and disables icons globally for max performance
`telescope`	closest match to telescope defaults in look and feel and keybinds
`skim`	uses `skim` as an fzf alternative, (requires the `sk` binary)
`borderless`	borderless and minimalistic seamless look & feel
`borderless-full`	borderless with description in window title (instead of prompt)
`border-fused`	single border around both fzf and the previewer
`ivy`	UI at bottom, similar to telescope's ivy layout
`hide`	send fzf process to background instead of termination

Extensibility

Fzf-lua can be easily extended and customised for your own needs: have a look at a full list of examples and plugins browsing the 💡Wiki 💡

Have ideas for new pickers, plugins or extensions? Add it to the wiki, it's open edit!

Insert-mode completion

Fzf-lua comes with a set of completion functions for paths/files and lines from open buffers as well as custom completion, for example, set path/completion using <C-x><C-f>:

vim.keymap.set({ "n", "v", "i" }, "<C-x><C-f>",
  function() FzfLua.complete_path() end,
  { silent = true, desc = "Fuzzy complete path" })

Or with a custom command and preview:

Note

only complete_file supports a previewer as complete_path mixes both files and directories.

vim.keymap.set({ "i" }, "<C-x><C-f>",
  function()
    FzfLua.complete_file({
      cmd = "rg --files",
      winopts = { preview = { hidden = true } }
    })
  end, { silent = true, desc = "Fuzzy complete file" })

CLICK FOR CUSTOM COMPLETION DETAILS

Custom Completion

Every fzf-lua function can be easily converted to a completion function by sending complete = true in the options:

By default fzf-lua will insert the entry at the cursor location as if you used p to paste the selected entry.

FzfLua.fzf_exec({"foo", "bar"}, {complete = true})

Custom completion is possible using a custom completion callback, the example below will replace the text from the current cursor column with the selected entry:

FzfLua.fzf_exec({"foo", "bar"}, {
  -- @param selected: the selected entry or entries
  -- @param opts: fzf-lua caller/provider options
  -- @param line: originating buffer completed line
  -- @param col: originating cursor column location
  -- @return newline: will replace the current buffer line
  -- @return newcol?: optional, sets the new cursor column
  complete = function(selected, opts, line, col)
    local newline = line:sub(1, col) .. selected[1]
    -- set cursor to EOL, since `nvim_win_set_cursor`
    -- is 0-based we have to lower the col value by 1
    return newline, #newline - 1
  end
})

Highlights

Highlight groups can be easily customized either via the lua API:

:lua vim.api.nvim_set_hl(0, "FzfLuaBorder", { link = "FloatBorder" })

or via setup:

require('fzf-lua').setup {
  hls = { border = "FloatBorder" }
}

or temporarily in the call:

:lua FzfLua.files({ hls={preview_title="IncSearch"} })
-- vimL equivalent
:FzfLua files hls.preview_title=IncSearch

CLICK TO SEE AVAILABLE HIGHLIGHT GROUPS

Highlight groups

FzfLua conveniently creates the below highlights, each hlgroup can be temporarily overridden by its corresponding winopts option:

Highlight Group	Default	Override Via	Notes
FzfLuaNormal	Normal	`hls.normal`	Main win `fg/bg`
FzfLuaBorder	Normal	`hls.border`	Main win border
FzfLuaTitle	FzfLuaNormal	`hls.title`	Main win title
FzfLuaTitleFlags	CursorLine	`hls.title_flags`	Main win title flags
FzfLuaBackdrop	*bg=Black	`hls.backdrop`	Backdrop color
FzfLuaPreviewNormal	FzfLuaNormal	`hls.preview_normal`	Builtin preview `fg/bg`
FzfLuaPreviewBorder	FzfLuaBorder	`hls.preview_border`	Builtin preview border
FzfLuaPreviewTitle	FzfLuaTitle	`hls.preview_title`	Builtin preview title
FzfLuaCursor	Cursor	`hls.cursor`	Builtin preview `Cursor`
FzfLuaCursorLine	CursorLine	`hls.cursorline`	Builtin preview `Cursorline`
FzfLuaCursorLineNr	CursorLineNr	`hls.cursorlinenr`	Builtin preview `CursorLineNr`
FzfLuaSearch	IncSearch	`hls.search`	Builtin preview search matches
FzfLuaScrollBorderEmpty	FzfLuaBorder	`hls.scrollborder_e`	Builtin preview `border` scroll empty
FzfLuaScrollBorderFull	FzfLuaBorder	`hls.scrollborder_f`	Builtin preview `border` scroll full
FzfLuaScrollFloatEmpty	PmenuSbar	`hls.scrollfloat_e`	Builtin preview `float` scroll empty
FzfLuaScrollFloatFull	PmenuThumb	`hls.scrollfloat_f`	Builtin preview `float` scroll full
FzfLuaHelpNormal	FzfLuaNormal	`hls.help_normal`	Help win `fg/bg`
FzfLuaHelpBorder	FzfLuaBorder	`hls.help_border`	Help win border
FzfLuaHeaderBind	*BlanchedAlmond	`hls.header_bind`	Header keybind
FzfLuaHeaderText	*Brown1	`hls.header_text`	Header text
FzfLuaPathColNr	*CadetBlue1	`hls.path_colnr`	Path col nr (`qf,lsp,diag`)
FzfLuaPathLineNr	*LightGreen	`hls.path_linenr`	Path line nr (`qf,lsp,diag`)
FzfLuaBufName	Directory	`hls.buf_name`	Buffer name (`lines`)
FzfLuaBufId	TabLine	`hls.buf_id`	Buffer ID (`lines`)
FzfLuaBufNr	*BlanchedAlmond	`hls.buf_nr`	Buffer number (`buffers,tabs`)
FzfLuaBufLineNr	LineNr	`hls.buf_linenr`	Buffer line nr (`lines,blines`)
FzfLuaBufFlagCur	*Brown1	`hls.buf_flag_cur`	Buffer line (`buffers`)
FzfLuaBufFlagAlt	*CadetBlue1	`hls.buf_flag_alt`	Buffer line (`buffers`)
FzfLuaTabTitle	*LightSkyBlue1	`hls.tab_title`	Tab title (`tabs`)
FzfLuaTabMarker	*BlanchedAlmond	`hls.tab_marker`	Tab marker (`tabs`)
FzfLuaDirIcon	Directory	`hls.dir_icon`	Paths directory icon
FzfLuaDirPart	Comment	`hls.dir_part`	Path formatters directory hl group
FzfLuaFilePart	@none	`hls.file_part`	Path formatters file hl group
FzfLuaLivePrompt	*PaleVioletRed1	`hls.live_prompt`	"live" queries prompt text
FzfLuaLiveSym	*PaleVioletRed1	`hls.live_sym`	LSP live symbols query match
FzfLuaCmdEx	Statement	`hls.cmd_ex`	Ex commands in `commands`
FzfLuaCmdBuf	Added	`hls.cmd_buf`	Buffer commands in `commands`
FzfLuaCmdGlobal	Directory	`hls.cmd_global`	Global commands in `commands`
FzfLuaFzfNormal	FzfLuaNormal	`fzf.normal`	fzf's `fg\|bg`
FzfLuaFzfCursorLine	FzfLuaCursorLine	`fzf.cursorline`	fzf's `fg+\|bg+`
FzfLuaFzfMatch	Special	`fzf.match`	fzf's `hl+`
FzfLuaFzfBorder	FzfLuaBorder	`fzf.border`	fzf's `border`
FzfLuaFzfScrollbar	FzfLuaFzfBorder	`fzf.scrollbar`	fzf's `scrollbar`
FzfLuaFzfSeparator	FzfLuaFzfBorder	`fzf.separator`	fzf's `separator`
FzfLuaFzfGutter	FzfLuaNormal	`fzf.gutter`	fzf's `gutter` (hl `bg` is used)
FzfLuaFzfHeader	FzfLuaTitle	`fzf.header`	fzf's `header`
FzfLuaFzfInfo	NonText	`fzf.info`	fzf's `info`
FzfLuaFzfPointer	Special	`fzf.pointer`	fzf's `pointer`
FzfLuaFzfMarker	FzfLuaFzfPointer	`fzf.marker`	fzf's `marker`
FzfLuaFzfSpinner	FzfLuaFzfPointer	`fzf.spinner`	fzf's `spinner`
FzfLuaFzfPrompt	Special	`fzf.prompt`	fzf's `prompt`
FzfLuaFzfQuery	FzfLuaNormal	`fzf.query`	fzf's `header`

^{_{*Not a highlight group, RGB color from nvim_get_color_map}}

CLICK FOR FZF COLORS DETAILS

Fzf Colors

Fzf's terminal colors are controlled by fzf's --color flag which can be configured during setup via fzf_colors.

Set to true to have fzf-lua automatically generate an fzf colorscheme from your current Neovim colorscheme:

require("fzf-lua").setup({ fzf_colors = true })
-- Or in the direct call options
:lua FzfLua.files({ fzf_colors = true })
:FzfLua files fzf_colors=true

Customizing the fzf colorscheme (see man fzf for all color options):

require('fzf-lua').setup {
  fzf_colors = {
    -- First existing highlight group will be used
    -- values in 3rd+ index will be passed raw
    -- i.e:  `--color fg+:#010101:bold:underline`
    ["fg+"] = { "fg" , { "Comment", "Normal" }, "bold", "underline" },
    -- It is also possible to pass raw values directly
    ["gutter"] = "-1"
  }
}

Conveniently, fzf-lua can also be configured using fzf.vim's g:fzf_colors, i.e:

-- Similarly, first existing highlight group will be used
:lua vim.g.fzf_colors = { ["gutter"] = { "bg", "DoesNotExist", "IncSearch" } }

However, the above doesn't allow combining both neovim highlights and raw args, if you're only using fzf-lua we can hijack g:fzf_colors to accept fzf-lua style values (i.e. table at 2nd index and 3rd+ raw args):

:lua vim.g.fzf_colors = { ["fg+"] = { "fg", { "ErrorMsg" }, "bold", "underline" } }

Credits

Big thank you to all those I borrowed code/ideas from, I read so many configs and plugin codes that I probably forgot where I found some samples from so if I missed your name feel free to contact me and I'll add it below:

@junegunn for creating the magical fzf and fzf.vim

@vijaymarupudi for the wonderful nvim-fzf plugin which started this endeavour
@tjdevries for too many great things to list here and borrowing code from nvim-telescope
@lukas-reineke for inspiration after browsing dotfiles
@sindrets for borrowing utilities from diffview.nvim
@kevinhwang91 for inspiring the builtin previewer code while using nvim-bqf

apache/apisix

The Cloud-Native API Gateway and AI Gateway

Apache APISIX API Gateway ｜ AI Gateway

Apache APISIX is a dynamic, real-time, high-performance API Gateway.

APISIX API Gateway provides rich traffic management features such as load balancing, dynamic upstream, canary release, circuit breaking, authentication, observability, and more.

APISIX can serve as an AI Gateway through its flexible plugin system, providing AI proxying, load balancing for LLMs, retries and fallbacks, token-based rate limiting, and robust security to ensure the efficiency and reliability of AI agents. APISIX also provides the mcp-bridge plugin to seamlessly convert stdio-based MCP servers to scalable HTTP SSE services.

You can use APISIX API Gateway to handle traditional north-south traffic, as well as east-west traffic between services. It can also be used as a k8s ingress controller.

The technical architecture of Apache APISIX:

Community

Kindly Write a Review for APISIX in G2.
Mailing List: Mail to dev-subscribe@apisix.apache.org, follow the reply to subscribe to the mailing list.
Slack Workspace - invitation link (Please open an issue if this link is expired), and then join the #apisix channel (Channels -> Browse channels -> search for "apisix").
- follow and interact with us using hashtag #ApacheAPISIX
Documentation
Discussions
Blog

Features

You can use APISIX API Gateway as a traffic entrance to process all business data, including dynamic routing, dynamic upstream, dynamic certificates, A/B testing, canary release, blue-green deployment, limit rate, defense against malicious attacks, metrics, monitoring alarms, service observability, service governance, etc.

All platforms
- Cloud-Native: Platform agnostic, No vendor lock-in, APISIX API Gateway can run from bare-metal to Kubernetes.
- Supports ARM64: Don't worry about the lock-in of the infra technology.
Multi protocols
- TCP/UDP Proxy: Dynamic TCP/UDP proxy.
- Dubbo Proxy: Dynamic HTTP to Dubbo proxy.
- Dynamic MQTT Proxy: Supports to load balance MQTT by client_id, both support MQTT 3.1.*, 5.0.
- gRPC proxy: Proxying gRPC traffic.
- gRPC Web Proxy: Proxying gRPC Web traffic to gRPC Service.
- gRPC transcoding: Supports protocol transcoding so that clients can access your gRPC API by using HTTP/JSON.
- Proxy Websocket
- Proxy Protocol
- HTTP(S) Forward Proxy
- SSL: Dynamically load an SSL certificate
- HTTP/3 with QUIC
Full Dynamic
- Hot Updates And Hot Plugins: Continuously updates its configurations and plugins without restarts!
- Proxy Rewrite: Support rewrite the host, uri, schema, method, headers of the request before send to upstream.
- Response Rewrite: Set customized response status code, body and header to the client.
- Dynamic Load Balancing: Round-robin load balancing with weight.
- Hash-based Load Balancing: Load balance with consistent hashing sessions.
- Health Checks: Enable health check on the upstream node and will automatically filter unhealthy nodes during load balancing to ensure system stability.
- Circuit-Breaker: Intelligent tracking of unhealthy upstream services.
- Proxy Mirror: Provides the ability to mirror client requests.
- Traffic Split: Allows users to incrementally direct percentages of traffic between various upstreams.
Fine-grained routing
- Supports full path matching and prefix matching
- Support all Nginx built-in variables as conditions for routing, so you can use cookie, args, etc. as routing conditions to implement canary release, A/B testing, etc.
- Support various operators as judgment conditions for routing, for example {"arg_age", ">", 24}
- Support custom route matching function
- IPv6: Use IPv6 to match the route.
- Support TTL
- Support priority
- Support Batch Http Requests
- Support filtering route by GraphQL attributes
Security
- Rich authentication & authorization support:
  - key-auth
  - JWT
  - basic-auth
  - wolf-rbac
  - casbin
  - keycloak
  - casdoor
- IP Whitelist/Blacklist
- Referer Whitelist/Blacklist
- IdP: Support external Identity platforms, such as Auth0, okta, etc..
- Limit-req
- Limit-count
- Limit-concurrency
- Anti-ReDoS(Regular expression Denial of Service): Built-in policies to Anti ReDoS without configuration.
- CORS Enable CORS(Cross-origin resource sharing) for your API.
- URI Blocker: Block client request by URI.
- Request Validator
- CSRF Based on the Double Submit Cookie way, protect your API from CSRF attacks.
OPS friendly
- Zipkin tracing: Zipkin
- Open source APM: support Apache SkyWalking
- Works with external service discovery: In addition to the built-in etcd, it also supports Consul, Consul_kv, Nacos, Eureka and Zookeeper (CP).
- Monitoring And Metrics: Prometheus
- Clustering: APISIX nodes are stateless, creates clustering of the configuration center, please refer to etcd Clustering Guide.
- High availability: Support to configure multiple etcd addresses in the same cluster.
- Dashboard
- Version Control: Supports rollbacks of operations.
- CLI: start\stop\reload APISIX through the command line.
- Standalone: Supports to load route rules from local YAML file, it is more friendly such as under the kubernetes(k8s).
- Global Rule: Allows to run any plugin for all request, eg: limit rate, IP filter etc.
- High performance: The single-core QPS reaches 18k with an average delay of fewer than 0.2 milliseconds.
- Fault Injection
- REST Admin API: Using the REST Admin API to control Apache APISIX, which only allows 127.0.0.1 access by default, you can modify the allow_admin field in conf/config.yaml to specify a list of IPs that are allowed to call the Admin API. Also, note that the Admin API uses key auth to verify the identity of the caller.
- External Loggers: Export access logs to external log management tools. (HTTP Logger, TCP Logger, Kafka Logger, UDP Logger, RocketMQ Logger, SkyWalking Logger, Alibaba Cloud Logging(SLS), Google Cloud Logging, Splunk HEC Logging, File Logger, SolarWinds Loggly Logging, TencentCloud CLS).
- ClickHouse: push logs to ClickHouse.
- Elasticsearch: push logs to Elasticsearch.
- Datadog: push custom metrics to the DogStatsD server, comes bundled with Datadog agent, over the UDP protocol. DogStatsD basically is an implementation of StatsD protocol which collects the custom metrics for Apache APISIX agent, aggregates it into a single data point and sends it to the configured Datadog server.
- Helm charts
- HashiCorp Vault: Support secret management solution for accessing secrets from Vault secure storage backed in a low trust environment. Currently, RS256 keys (public-private key pairs) or secret keys can be linked from vault in jwt-auth authentication plugin using APISIX Secret resource.
Highly scalable
- Custom plugins: Allows hooking of common phases, such as rewrite, access, header filter, body filter and log, also allows to hook the balancer stage.
- Plugin can be written in Java/Go/Python
- Plugin can be written with Proxy Wasm SDK
- Custom load balancing algorithms: You can use custom load balancing algorithms during the balancer phase.
- Custom routing: Support users to implement routing algorithms themselves.
Multi-Language support
- Apache APISIX is a multi-language gateway for plugin development and provides support via RPC and Wasm.
- The RPC way, is the current way. Developers can choose the language according to their needs and after starting an independent process with the RPC, it exchanges data with APISIX through local RPC communication. Till this moment, APISIX has support for Java, Golang, Python and Node.js.
- The Wasm or WebAssembly, is an experimental way. APISIX can load and run Wasm bytecode via APISIX wasm plugin written with the Proxy Wasm SDK. Developers only need to write the code according to the SDK and then compile it into a Wasm bytecode that runs on Wasm VM with APISIX.
Serverless
- Lua functions: Invoke functions in each phase in APISIX.
- AWS Lambda: Integration with AWS Lambda function as a dynamic upstream to proxy all requests for a particular URI to the AWS API gateway endpoint. Supports authorization via api key and AWS IAM access secret.
- Azure Functions: Seamless integration with Azure Serverless Function as a dynamic upstream to proxy all requests for a particular URI to the Microsoft Azure cloud.
- Apache OpenWhisk: Seamless integration with Apache OpenWhisk as a dynamic upstream to proxy all requests for a particular URI to your own OpenWhisk cluster.

Get Started

Installation

Please refer to install documentation.
Getting started

The getting started guide is a great way to learn the basics of APISIX. Just follow the steps in Getting Started.

Further, you can follow the documentation to try more plugins.
Admin API

Apache APISIX provides REST Admin API to dynamically control the Apache APISIX cluster.
Plugin development

You can refer to plugin development guide, and sample plugin example-plugin's code implementation. Reading plugin concept would help you learn more about the plugin.

For more documents, please refer to Apache APISIX Documentation site

Benchmark

Using AWS's eight-core server, APISIX's QPS reaches 140,000 with a latency of only 0.2 ms.

Benchmark script has been open sourced, welcome to try and contribute.

APISIX also works perfectly in AWS graviton3 C7g.

User Stories

Who Uses APISIX API Gateway?

A wide variety of companies and organizations use APISIX API Gateway for research, production and commercial product, below are some of them:

Airwallex
Bilibili
CVTE
European eFactory Platform
European Copernicus Reference System
Geely
HONOR
Horizon Robotics
iQIYI
Lenovo
NASA JPL
Nayuki
OPPO
QingCloud
Swisscom
Tencent Game
Travelsky
vivo
Sina Weibo
WeCity
WPS
XPENG
Zoom

Logos

Acknowledgments

Inspired by Kong and Orange.

License

Apache 2.0 License

folke/snacks.nvim

🍿 A collection of QoL plugins for Neovim

🍿 `snacks.nvim`

A collection of small QoL plugins for Neovim.

✨ Features

Snack	Description	Setup
animate	Efficient animations including over 45 easing functions (library)
bigfile	Deal with big files	‼️
bufdelete	Delete buffers without disrupting window layout
dashboard	Beautiful declarative dashboards	‼️
debug	Pretty inspect & backtraces for debugging
dim	Focus on the active scope by dimming the rest
explorer	A file explorer (picker in disguise)	‼️
gh	GitHub CLI integration
git	Git utilities
gitbrowse	Open the current file, branch, commit, or repo in a browser (e.g. GitHub, GitLab, Bitbucket)
image	Image viewer using Kitty Graphics Protocol, supported by `kitty`, `wezterm` and `ghostty`	‼️
indent	Indent guides and scopes
input	Better `vim.ui.input`	‼️
keymap	Better `vim.keymap` with support for filetypes and LSP clients
layout	Window layouts
lazygit	Open LazyGit in a float, auto-configure colorscheme and integration with Neovim
notifier	Pretty `vim.notify`	‼️
notify	Utility functions to work with Neovim's `vim.notify`
picker	Picker for selecting items	‼️
profiler	Neovim lua profiler
quickfile	When doing `nvim somefile.txt`, it will render the file as quickly as possible, before loading your plugins.	‼️
rename	LSP-integrated file renaming with support for plugins like neo-tree.nvim and mini.files.
scope	Scope detection, text objects and jumping based on treesitter or indent	‼️
scratch	Scratch buffers with a persistent file
scroll	Smooth scrolling	‼️
statuscolumn	Pretty status column	‼️
terminal	Create and toggle floating/split terminals
toggle	Toggle keymaps integrated with which-key icons / colors
util	Utility functions for Snacks (library)
win	Create and manage floating windows or splits
words	Auto-show LSP references and quickly navigate between them	‼️
zen	Zen mode • distraction-free coding

⚡️ Requirements

Neovim >= 0.9.4
for proper icons support:
- mini.icons (optional)
- nvim-web-devicons (optional)
- a Nerd Font (optional)

📦 Installation

Install the plugin with your package manager:

lazy.nvim

Important

A couple of plugins require snacks.nvim to be set-up early. Setup creates some autocmds and does not load any plugins. Check the code to see what it does.

Caution

You need to explicitly pass options for a plugin or set enabled = true to enable it.

Tip

It's a good idea to run :checkhealth snacks to see if everything is set up correctly.

{
  "folke/snacks.nvim",
  priority = 1000,
  lazy = false,
  ---@type snacks.Config
  opts = {
    -- your configuration comes here
    -- or leave it empty to use the default settings
    -- refer to the configuration section below
    bigfile = { enabled = true },
    dashboard = { enabled = true },
    explorer = { enabled = true },
    indent = { enabled = true },
    input = { enabled = true },
    picker = { enabled = true },
    notifier = { enabled = true },
    quickfile = { enabled = true },
    scope = { enabled = true },
    scroll = { enabled = true },
    statuscolumn = { enabled = true },
    words = { enabled = true },
  },
}

For an in-depth setup of snacks.nvim with lazy.nvim, check the example below.

⚙️ Configuration

Please refer to the readme of each plugin for their specific configuration.

Default Options

---@class snacks.Config
---@field animate? snacks.animate.Config
---@field bigfile? snacks.bigfile.Config
---@field dashboard? snacks.dashboard.Config
---@field dim? snacks.dim.Config
---@field explorer? snacks.explorer.Config
---@field gh? snacks.gh.Config
---@field gitbrowse? snacks.gitbrowse.Config
---@field image? snacks.image.Config
---@field indent? snacks.indent.Config
---@field input? snacks.input.Config
---@field layout? snacks.layout.Config
---@field lazygit? snacks.lazygit.Config
---@field notifier? snacks.notifier.Config
---@field picker? snacks.picker.Config
---@field profiler? snacks.profiler.Config
---@field quickfile? snacks.quickfile.Config
---@field scope? snacks.scope.Config
---@field scratch? snacks.scratch.Config
---@field scroll? snacks.scroll.Config
---@field statuscolumn? snacks.statuscolumn.Config
---@field terminal? snacks.terminal.Config
---@field toggle? snacks.toggle.Config
---@field win? snacks.win.Config
---@field words? snacks.words.Config
---@field zen? snacks.zen.Config
---@field styles? table<string, snacks.win.Config>
---@field image? snacks.image.Config|{}
{
  image = {
    -- define these here, so that we don't need to load the image module
    formats = {
      "png",
      "jpg",
      "jpeg",
      "gif",
      "bmp",
      "webp",
      "tiff",
      "heic",
      "avif",
      "mp4",
      "mov",
      "avi",
      "mkv",
      "webm",
      "pdf",
      "icns",
    },
  },
}

Some plugins have examples in their documentation. You can include them in your config like this:

{
  dashboard = { example = "github" }
}

If you want to customize options for a plugin after they have been resolved, you can use the config function:

{
  gitbrowse = {
    config = function(opts, defaults)
      table.insert(opts.remote_patterns, { "my", "custom pattern" })
    end
  },
}

🚀 Usage

See the example below for how to configure snacks.nvim.

{
  "folke/snacks.nvim",
  priority = 1000,
  lazy = false,
  ---@type snacks.Config
  opts = {
    bigfile = { enabled = true },
    dashboard = { enabled = true },
    explorer = { enabled = true },
    indent = { enabled = true },
    input = { enabled = true },
    notifier = {
      enabled = true,
      timeout = 3000,
    },
    picker = { enabled = true },
    quickfile = { enabled = true },
    scope = { enabled = true },
    scroll = { enabled = true },
    statuscolumn = { enabled = true },
    words = { enabled = true },
    styles = {
      notification = {
        -- wo = { wrap = true } -- Wrap notifications
      }
    }
  },
  keys = {
    -- Top Pickers & Explorer
    { "<leader><space>", function() Snacks.picker.smart() end, desc = "Smart Find Files" },
    { "<leader>,", function() Snacks.picker.buffers() end, desc = "Buffers" },
    { "<leader>/", function() Snacks.picker.grep() end, desc = "Grep" },
    { "<leader>:", function() Snacks.picker.command_history() end, desc = "Command History" },
    { "<leader>n", function() Snacks.picker.notifications() end, desc = "Notification History" },
    { "<leader>e", function() Snacks.explorer() end, desc = "File Explorer" },
    -- find
    { "<leader>fb", function() Snacks.picker.buffers() end, desc = "Buffers" },
    { "<leader>fc", function() Snacks.picker.files({ cwd = vim.fn.stdpath("config") }) end, desc = "Find Config File" },
    { "<leader>ff", function() Snacks.picker.files() end, desc = "Find Files" },
    { "<leader>fg", function() Snacks.picker.git_files() end, desc = "Find Git Files" },
    { "<leader>fp", function() Snacks.picker.projects() end, desc = "Projects" },
    { "<leader>fr", function() Snacks.picker.recent() end, desc = "Recent" },
    -- git
    { "<leader>gb", function() Snacks.picker.git_branches() end, desc = "Git Branches" },
    { "<leader>gl", function() Snacks.picker.git_log() end, desc = "Git Log" },
    { "<leader>gL", function() Snacks.picker.git_log_line() end, desc = "Git Log Line" },
    { "<leader>gs", function() Snacks.picker.git_status() end, desc = "Git Status" },
    { "<leader>gS", function() Snacks.picker.git_stash() end, desc = "Git Stash" },
    { "<leader>gd", function() Snacks.picker.git_diff() end, desc = "Git Diff (Hunks)" },
    { "<leader>gf", function() Snacks.picker.git_log_file() end, desc = "Git Log File" },
    -- gh
    { "<leader>gi", function() Snacks.picker.gh_issue() end, desc = "GitHub Issues (open)" },
    { "<leader>gI", function() Snacks.picker.gh_issue({ state = "all" }) end, desc = "GitHub Issues (all)" },
    { "<leader>gp", function() Snacks.picker.gh_pr() end, desc = "GitHub Pull Requests (open)" },
    { "<leader>gP", function() Snacks.picker.gh_pr({ state = "all" }) end, desc = "GitHub Pull Requests (all)" },
    -- Grep
    { "<leader>sb", function() Snacks.picker.lines() end, desc = "Buffer Lines" },
    { "<leader>sB", function() Snacks.picker.grep_buffers() end, desc = "Grep Open Buffers" },
    { "<leader>sg", function() Snacks.picker.grep() end, desc = "Grep" },
    { "<leader>sw", function() Snacks.picker.grep_word() end, desc = "Visual selection or word", mode = { "n", "x" } },
    -- search
    { '<leader>s"', function() Snacks.picker.registers() end, desc = "Registers" },
    { '<leader>s/', function() Snacks.picker.search_history() end, desc = "Search History" },
    { "<leader>sa", function() Snacks.picker.autocmds() end, desc = "Autocmds" },
    { "<leader>sb", function() Snacks.picker.lines() end, desc = "Buffer Lines" },
    { "<leader>sc", function() Snacks.picker.command_history() end, desc = "Command History" },
    { "<leader>sC", function() Snacks.picker.commands() end, desc = "Commands" },
    { "<leader>sd", function() Snacks.picker.diagnostics() end, desc = "Diagnostics" },
    { "<leader>sD", function() Snacks.picker.diagnostics_buffer() end, desc = "Buffer Diagnostics" },
    { "<leader>sh", function() Snacks.picker.help() end, desc = "Help Pages" },
    { "<leader>sH", function() Snacks.picker.highlights() end, desc = "Highlights" },
    { "<leader>si", function() Snacks.picker.icons() end, desc = "Icons" },
    { "<leader>sj", function() Snacks.picker.jumps() end, desc = "Jumps" },
    { "<leader>sk", function() Snacks.picker.keymaps() end, desc = "Keymaps" },
    { "<leader>sl", function() Snacks.picker.loclist() end, desc = "Location List" },
    { "<leader>sm", function() Snacks.picker.marks() end, desc = "Marks" },
    { "<leader>sM", function() Snacks.picker.man() end, desc = "Man Pages" },
    { "<leader>sp", function() Snacks.picker.lazy() end, desc = "Search for Plugin Spec" },
    { "<leader>sq", function() Snacks.picker.qflist() end, desc = "Quickfix List" },
    { "<leader>sR", function() Snacks.picker.resume() end, desc = "Resume" },
    { "<leader>su", function() Snacks.picker.undo() end, desc = "Undo History" },
    { "<leader>uC", function() Snacks.picker.colorschemes() end, desc = "Colorschemes" },
    -- LSP
    { "gd", function() Snacks.picker.lsp_definitions() end, desc = "Goto Definition" },
    { "gD", function() Snacks.picker.lsp_declarations() end, desc = "Goto Declaration" },
    { "gr", function() Snacks.picker.lsp_references() end, nowait = true, desc = "References" },
    { "gI", function() Snacks.picker.lsp_implementations() end, desc = "Goto Implementation" },
    { "gy", function() Snacks.picker.lsp_type_definitions() end, desc = "Goto T[y]pe Definition" },
    { "gai", function() Snacks.picker.lsp_incoming_calls() end, desc = "C[a]lls Incoming" },
    { "gao", function() Snacks.picker.lsp_outgoing_calls() end, desc = "C[a]lls Outgoing" },
    { "<leader>ss", function() Snacks.picker.lsp_symbols() end, desc = "LSP Symbols" },
    { "<leader>sS", function() Snacks.picker.lsp_workspace_symbols() end, desc = "LSP Workspace Symbols" },
    -- Other
    { "<leader>z",  function() Snacks.zen() end, desc = "Toggle Zen Mode" },
    { "<leader>Z",  function() Snacks.zen.zoom() end, desc = "Toggle Zoom" },
    { "<leader>.",  function() Snacks.scratch() end, desc = "Toggle Scratch Buffer" },
    { "<leader>S",  function() Snacks.scratch.select() end, desc = "Select Scratch Buffer" },
    { "<leader>n",  function() Snacks.notifier.show_history() end, desc = "Notification History" },
    { "<leader>bd", function() Snacks.bufdelete() end, desc = "Delete Buffer" },
    { "<leader>cR", function() Snacks.rename.rename_file() end, desc = "Rename File" },
    { "<leader>gB", function() Snacks.gitbrowse() end, desc = "Git Browse", mode = { "n", "v" } },
    { "<leader>gg", function() Snacks.lazygit() end, desc = "Lazygit" },
    { "<leader>un", function() Snacks.notifier.hide() end, desc = "Dismiss All Notifications" },
    { "<c-/>",      function() Snacks.terminal() end, desc = "Toggle Terminal" },
    { "<c-_>",      function() Snacks.terminal() end, desc = "which_key_ignore" },
    { "]]",         function() Snacks.words.jump(vim.v.count1) end, desc = "Next Reference", mode = { "n", "t" } },
    { "[[",         function() Snacks.words.jump(-vim.v.count1) end, desc = "Prev Reference", mode = { "n", "t" } },
    {
      "<leader>N",
      desc = "Neovim News",
      function()
        Snacks.win({
          file = vim.api.nvim_get_runtime_file("doc/news.txt", false)[1],
          width = 0.6,
          height = 0.6,
          wo = {
            spell = false,
            wrap = false,
            signcolumn = "yes",
            statuscolumn = " ",
            conceallevel = 3,
          },
        })
      end,
    }
  },
  init = function()
    vim.api.nvim_create_autocmd("User", {
      pattern = "VeryLazy",
      callback = function()
        -- Setup some globals for debugging (lazy-loaded)
        _G.dd = function(...)
          Snacks.debug.inspect(...)
        end
        _G.bt = function()
          Snacks.debug.backtrace()
        end

        -- Override print to use snacks for `:=` command
        if vim.fn.has("nvim-0.11") == 1 then
          vim._print = function(_, ...)
            dd(...)
          end
        else
          vim.print = _G.dd 
        end

        -- Create some toggle mappings
        Snacks.toggle.option("spell", { name = "Spelling" }):map("<leader>us")
        Snacks.toggle.option("wrap", { name = "Wrap" }):map("<leader>uw")
        Snacks.toggle.option("relativenumber", { name = "Relative Number" }):map("<leader>uL")
        Snacks.toggle.diagnostics():map("<leader>ud")
        Snacks.toggle.line_number():map("<leader>ul")
        Snacks.toggle.option("conceallevel", { off = 0, on = vim.o.conceallevel > 0 and vim.o.conceallevel or 2 }):map("<leader>uc")
        Snacks.toggle.treesitter():map("<leader>uT")
        Snacks.toggle.option("background", { off = "light", on = "dark", name = "Dark Background" }):map("<leader>ub")
        Snacks.toggle.inlay_hints():map("<leader>uh")
        Snacks.toggle.indent():map("<leader>ug")
        Snacks.toggle.dim():map("<leader>uD")
      end,
    })
  end,
}

🌈 Highlight Groups

Snacks defines a lot of highlight groups and it's impossible to document them all.

Instead, you can use the picker to see all the highlight groups.

Snacks.picker.highlights({pattern = "hl_group:^Snacks"})

xmake-io/xmake

🔥 A cross-platform build utility based on Lua

xmake

A cross-platform build utility based on Lua
Modern C/C++ build tool: Simple, Fast, Powerful dependency package integration

Support this project

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. 🙏

Introduction (中文)

What is Xmake?

Xmake is a cross-platform build utility based on the Lua scripting language.
Xmake is very lightweight and has no dependencies outside of the standard library.
Uses the xmake.lua file to maintain project builds with a simple and readable syntax.

Xmake can be used to directly build source code (like with Make or Ninja), or it can generate project source files like CMake or Meson. It also has a built-in package management system to help users integrate C/C++ dependencies.

Xmake = Build backend + Project Generator + Package Manager + [Remote|Distributed] Build + Cache

Although less precise, one can still understand Xmake in the following way:

Xmake ≈ Make/Ninja + CMake/Meson + Vcpkg/Conan + distcc + ccache/sccache

If you want to know more, please refer to the Documentation, GitHub or Gitee. You are also welcome to join our community.

The official Xmake repository can be found at xmake-io/xmake-repo.

Installation

With cURL

curl -fsSL https://xmake.io/shget.text | bash

With Wget

wget https://xmake.io/shget.text -O - | bash

With PowerShell

irm https://xmake.io/psget.text | iex

Other installation methods

If you don't want to use the above scripts to install Xmake, visit the Installation Guide for other installation methods (building from source, package managers, etc.).

Simple Project Description

target("console")
    set_kind("binary")
    add_files("src/*.c")

Creates a new target console of kind binary, and adds all the files ending in .c in the src directory.

Package dependencies

add_requires("tbox 1.6.*", "zlib", "libpng ~1.6")

Adds a requirement of tbox v1.6, zlib (any version), and libpng v1.6.

The official xmake package repository exists at: xmake-repo

Command line interface reference

The below assumes you are currently in the project's root directory.

Build a project

$ xmake

Run target

$ xmake run console

Debug target

$ xmake run -d console

Run test

$ xmake test

Configure platform

$ xmake f -p [windows|linux|macosx|android|iphoneos ..] -a [x86|arm64 ..] -m [debug|release]
$ xmake

Menu configuration

$ xmake f --menu

Supported platforms

Windows (x86, x64, arm, arm64, arm64ec)
macOS (i386, x86_64, arm64)
Linux (i386, x86_64, arm, arm64, riscv, mips, 390x, sh4 ...)
FreeBSD (i386, x86_64)
NetBSD (i386, x86_64)
OpenBSD (i386, x86_64)
DragonflyBSD (i386, x86_64)
Solaris (i386, x86_64)
Android (x86, x86_64, armeabi, armeabi-v7a, arm64-v8a)
iOS (armv7, armv7s, arm64, i386, x86_64)
WatchOS (armv7k, i386)
AppleTVOS (armv7, arm64, i386, x86_64)
AppleXROS (arm64, x86_64)
MSYS (i386, x86_64)
MinGW (i386, x86_64, arm, arm64)
Cygwin (i386, x86_64)
Wasm (wasm32, wasm64)
Haiku (i386, x86_64)
Harmony (x86_64, armeabi-v7a, arm64-v8a)
Cross (cross-toolchains ..)

Supported toolchains

$ xmake show -l toolchains
xcode         Xcode IDE
msvc          Microsoft Visual C/C++ Compiler
clang-cl      LLVM Clang C/C++ Compiler compatible with msvc
yasm          The Yasm Modular Assembler
clang         A C language family frontend for LLVM
go            Go Programming Language Compiler
dlang         D Programming Language Compiler (Auto)
dmd           D Programming Language Compiler
ldc           The LLVM-based D Compiler
gdc           The GNU D Compiler (GDC)
gfortran      GNU Fortran Programming Language Compiler
flang         LLVM Fortran Compiler
zig           Zig Programming Language Compiler
zigcc         Use zig cc/c++ as C/C++ Compiler
sdcc          Small Device C Compiler
cuda          CUDA Toolkit (nvcc, nvc, nvc++, nvfortran)
ndk           Android NDK
rust          Rust Programming Language Compiler
swift         Swift Programming Language Compiler
llvm          A collection of modular and reusable compiler and toolchain technologies
cross         Common cross compilation toolchain
nasm          NASM Assembler
gcc           GNU Compiler Collection
mingw         Minimalist GNU for Windows
gnu-rm        GNU Arm Embedded Toolchain
envs          Environment variables toolchain
fasm          Flat Assembler
tinycc        Tiny C Compiler
emcc          A toolchain for compiling to asm.js and WebAssembly
icc           Intel C/C++ Compiler
ifort         Intel Fortran Compiler
ifx           Intel LLVM Fortran Compiler
muslcc        The musl-based cross-compilation toolchain
fpc           Free Pascal Programming Language Compiler
wasi          WASI-enabled WebAssembly C/C++ toolchain
nim           Nim Programming Language Compiler
dotnet        .NET SDK Toolchain
circle        A new C++20 compiler
armcc         ARM Compiler Version 5 of Keil MDK
armclang      ARM Compiler Version 6 of Keil MDK
c51           Keil development tools for the 8051 Microcontroller Architecture
icx           Intel LLVM C/C++ Compiler
dpcpp         Intel LLVM C++ Compiler for data parallel programming model based on Khronos SYCL
masm32        The MASM32 SDK
iverilog      Icarus Verilog
verilator     Verilator open-source SystemVerilog simulator and lint system
cosmocc       build-once run-anywhere
hdk           Harmony SDK
ti-c2000      TI-CGT C2000 compiler
ti-c6000      TI-CGT C6000 compiler
iararm        IAR ARM C/C++ Compiler
kotlin-native Kotlin Native Programming Language Compiler
filc          A memory safe implementation of the C and C++ programming languages (https://fil-c.org/)

Supported languages

C and C++
Objective-C and Objective-C++
Swift
Assembly
Golang
Rust
Dlang
Fortran
Cuda
Zig
Vala
Pascal
Nim
Verilog
FASM
NASM
YASM
MASM32
Cppfront
Kotlin
C#

Features

Xmake exhibits:

Simple yet flexible configuration grammar.
Quick, dependency-free installation.
Easy compilation for most all supported platforms.
Supports cross-compilation with intelligent analysis of cross toolchain information.
Extremely fast parallel compilation support.
Supports C++ modules (new in C++20).
Supports cross-platform C/C++ dependencies with built-in package manager.
Multi-language compilation support including mixed-language projects.
Rich plug-in support with various project generators (ex. Visual Studio/Makefiles/CMake/compile_commands.json)
REPL interactive execution support
Incremental compilation support with automatic analysis of header files
Built-in toolchain management
A large number of expansion modules
Remote compilation support
Distributed compilation support
Local and remote build cache support

Supported Project Types

Xmake supports the below types of projects:

Static libraries
Shared libraries
Console/CLI applications
CUDA programs
Qt applications
WDK drivers (umdf/kmdf/wdm)
WinSDK applications
MFC applications
Darwin applications (with metal support)
Frameworks and bundles (in Darwin)
SWIG modules (Lua, Python, ...)
LuaRocks modules
Protobuf programs
Lex/Yacc programs
Linux kernel modules

Package management

Download and build

Xmake can automatically fetch and install dependencies!

Supported package repositories

Official package repository xmake-repo (tbox >1.6.1)
Official package manager Xrepo
User-built repositories
Conan (conan::openssl/1.1.1g)
Conda (conda::libpng 1.3.67)
Vcpkg (vcpkg:ffmpeg)
Homebrew/Linuxbrew (brew::pcre2/libpcre2-8)
Pacman on archlinux/msys2 (pacman::libcurl)
Apt on ubuntu/debian (apt::zlib1g-dev)
Clib (clib::clibs/bytes@0.0.4)
Dub (dub::log 0.4.3)
Portage on Gentoo/Linux (portage::libhandy)
Nimble for nimlang (nimble::zip >1.3)
Cargo for rust (cargo::base64 0.13.0)
Zypper on openSUSE (zypper::libsfml2 2.5)

Package management features

The official repository provides nearly 500+ packages with simple compilation on all supported platforms
Full platform package support, support for cross-compiled dependent packages
Support package virtual environment using xrepo env shell
Precompiled package acceleration for Windows (NT)
Support self-built package repositories and private repository deployment
Third-party package repository support for repositories such as: vcpkg, conan, conda, etc.
Supports automatic pulling of remote toolchains
Supports dependency version locking

Processing architecture

Below is a diagram showing roughly the architecture of Xmake, and thus how it functions.

Distributed Compilation

Cross-platform support.
Support for MSVC, Clang, GCC and other cross-compilation toolchains.
Support for building for Android, Linux, Windows NT, and Darwin hosts.
No dependencies other than the compilation toolchain.
Support for build server load balancing scheduling.
Support for real time compressed transfer of large files (lz4).
Almost zero configuration cost, no shared filesystem required, for convenience and security.

For more details see: Distributed Compilation

Remote Compilation

For more details see: Remote Compilation

Local/Remote Build Cache

For more details see: Build Cache Acceleration

Benchmark

Xmake's speed on is par with Ninja! The test project: xmake-core

Multi-task parallel compilation

buildsystem	Termux (8core/-j12)	buildsystem	MacOS (8core/-j12)
xmake	24.890s	xmake	12.264s
ninja	25.682s	ninja	11.327s
cmake(gen+make)	5.416s+28.473s	cmake(gen+make)	1.203s+14.030s
cmake(gen+ninja)	4.458s+24.842s	cmake(gen+ninja)	0.988s+11.644s

Single task compilation

buildsystem	Termux (-j1)	buildsystem	MacOS (-j1)
xmake	1m57.707s	xmake	39.937s
ninja	1m52.845s	ninja	38.995s
cmake(gen+make)	5.416s+2m10.539s	cmake(gen+make)	1.203s+41.737s
cmake(gen+ninja)	4.458s+1m54.868s	cmake(gen+ninja)	0.988s+38.022s

More Examples

Debug and release profiles

add_rules("mode.debug", "mode.release")

target("console")
    set_kind("binary")
    add_files("src/*.c")
    if is_mode("debug") then
        add_defines("DEBUG")
    end

Custom scripts

target("test")
    set_kind("binary")
    add_files("src/*.c")
    after_build(function (target)
        print("hello: %s", target:name())
        os.exec("echo %s", target:targetfile())
    end)

Automatic integration of dependent packages

Download and use packages in xmake-repo or third-party repositories:

add_requires("tbox >1.6.1", "libuv master", "vcpkg::ffmpeg", "brew::pcre2/libpcre2-8")
add_requires("conan::openssl/1.1.1g", {alias = "openssl", optional = true, debug = true})
target("test")
    set_kind("binary")
    add_files("src/*.c")
    add_packages("tbox", "libuv", "vcpkg::ffmpeg", "brew::pcre2/libpcre2-8", "openssl")

In addition, we can also use the xrepo command to quickly install dependencies.

Qt QuickApp Program

target("test")
    add_rules("qt.quickapp")
    add_files("src/*.cpp")
    add_files("src/qml.qrc")

Cuda Program

target("test")
    set_kind("binary")
    add_files("src/*.cu")
    add_cugencodes("native")
    add_cugencodes("compute_75")

WDK/UMDF Driver Program

target("echo")
    add_rules("wdk.driver", "wdk.env.umdf")
    add_files("driver/*.c")
    add_files("driver/*.inx")
    add_includedirs("exe")

target("app")
    add_rules("wdk.binary", "wdk.env.umdf")
    add_files("exe/*.cpp")

For more WDK driver examples (UMDF/KMDF/WDM), please visit WDK Program Examples

Darwin Applications

target("test")
    add_rules("xcode.application")
    add_files("src/*.m", "src/**.storyboard", "src/*.xcassets")
    add_files("src/Info.plist")

Framework and Bundle Program (Darwin)

target("test")
    add_rules("xcode.framework") -- or xcode.bundle
    add_files("src/*.m")
    add_files("src/Info.plist")

OpenMP Program

add_requires("libomp", {optional = true})
target("loop")
    set_kind("binary")
    add_files("src/*.cpp")
    add_rules("c++.openmp")
    add_packages("libomp")

Zig Program

target("test")
    set_kind("binary")
    add_files("src/main.zig")

Automatically fetch remote toolchain

fetch a special version of LLVM

Require the Clang version packaged with LLM-10 to compile a project.

add_requires("llvm 10.x", {alias = "llvm-10"})
target("test")
    set_kind("binary")
    add_files("src/*.c")
    set_toolchains("llvm@llvm-10")

Fetch a cross-compilation toolchain

We can also pull a specified cross-compilation toolchain in to compile the project.

add_requires("muslcc")
target("test")
    set_kind("binary")
    add_files("src/*.c")
    set_toolchains("@muslcc")

Fetch toolchain and packages

We can also use the specified muslcc cross-compilation toolchain to compile and integrate all dependent packages.

add_requires("muslcc")
add_requires("zlib", "libogg", {system = false})

set_toolchains("@muslcc")

target("test")
    set_kind("binary")
    add_files("src/*.c")
    add_packages("zlib", "libogg")

Plugins

Generate IDE project file plugin（makefile, vs2002 - vs2026 .. ）

$ xmake project -k vsxmake -m "debug,release" # New vsproj generator (Recommended)
$ xmake project -k vs -m "debug,release"
$ xmake project -k cmake
$ xmake project -k ninja
$ xmake project -k compile_commands

Run a custom lua script plugin

$ xmake l ./test.lua
$ xmake l -c "print('hello xmake!')"
$ xmake l lib.detect.find_tool gcc
$ xmake l
> print("hello xmake!")
> {1, 2, 3}
< {
    1,
    2,
    3
  }

To see a list of builtin plugins, please visit Builtin plugins.

Please download and install other plugins from the plugins repository xmake-plugins.

IDE/Editor Integration

xmake-vscode

xmake-sublime

xmake-idea

xmake-zed (thanks @jeleferai)
xmake.vim (third-party, thanks @luzhlon)
xmake-visualstudio (third-party, thanks @HelloWorld886)
xmake-qtcreator (third-party, thanks @Arthapz)

Xmake Gradle Plugin (JNI)

We can use the xmake-gradle plugin to compile JNI libraries via gradle.

plugins {
  id 'org.tboox.gradle-xmake-plugin' version '1.1.5'
}

android {
    externalNativeBuild {
        xmake {
            path "jni/xmake.lua"
        }
    }
}

The xmakeBuild task will be injected into the assemble task automatically if the gradle-xmake-plugin has been applied.

$ ./gradlew app:assembleDebug
> Task :nativelib:xmakeConfigureForArm64
> Task :nativelib:xmakeBuildForArm64
>> xmake build
[ 50%]: cache compiling.debug nativelib.cc
[ 75%]: linking.debug libnativelib.so
[100%]: build ok!
>> install artifacts to /Users/ruki/projects/personal/xmake-gradle/nativelib/libs/arm64-v8a
> Task :nativelib:xmakeConfigureForArmv7
> Task :nativelib:xmakeBuildForArmv7
>> xmake build
[ 50%]: cache compiling.debug nativelib.cc
[ 75%]: linking.debug libnativelib.so
[100%]: build ok!
>> install artifacts to /Users/ruki/projects/personal/xmake-gradle/nativelib/libs/armeabi-v7a
> Task :nativelib:preBuild
> Task :nativelib:assemble
> Task :app:assembleDebug

CI Integration

GitHub Action

The github-action-setup-xmake plugin for GitHub Actions can allow you to use Xmake with minimal efforts if you use GitHub Actions for your CI pipeline.

uses: xmake-io/github-action-setup-xmake@v1
with:
  xmake-version: latest

Who is using Xmake?

The list of people and projects who are using Xmake is available here.

If you are using Xmake, you are welcome to submit your information to the above list through a PR, so that other users and the developers can gauge interest. This also lets users use xmake more confidently and gives us motivation to continue to maintain it.

This will help the Xmake project and it's community grow stronger and expand!

Contacts

Email：waruqi@gmail.com
Homepage：xmake.io
Community
- Chat on Reddit
- Chat on Telegram
- Chat on Discord
- Chat on QQ Group: 343118190, 662147501
Source Code：GitHub, Gitee
WeChat Public: tboox-os

Thanks

This project exists thanks to all the people who have contributed:

TitanSnow: Provide the xmake logo and install scripts
uael: Provide the semantic versioning library sv
OpportunityLiu: Improve cuda, tests and ci
xq144: Improve xrepo env shell, and contribute a lot of packages to the xmake-repo repository.
star-hengxing: Contribute a lot of packages to the xmake-repo repository.
Arthapz: Contribute new C++ Modules implementation.
SirLynix: Contributed many packages and let more people know about xmake.
enderger: Helped smooth out the edges on the English translation of the README

Powered by

mason-org/mason-lspconfig.nvim

Extension to mason.nvim that makes it easier to use lspconfig with mason.nvim.

mason-lspconfig.nvim

mason-lspconfig bridges mason.nvim with the lspconfig plugin - making it easier to use both plugins together.

:help mason-lspconfig.nvim

^{Latest version: v2.1.0}

Introduction

:h mason-lspconfig-introduction

This plugin's main responsibilities are to:

allow you to (i) automatically install, and (ii) automatically enable (vim.lsp.enable()) installed servers
provide extra convenience APIs such as the :LspInstall command
provide additional LSP configurations for a few servers
translate between nvim-lspconfig server names and mason.nvim package names (e.g. lua_ls <-> lua-language-server)

Note

Since the introduction of :h vim.lsp.config in Neovim 0.11, this plugin's feature set has been reduced. Use this plugin if you want to automatically enable installed servers (:h vim.lsp.enable()) or have access to the :LspInstall command.

Requirements

:h mason-lspconfig-requirements

neovim >= 0.11.0
mason.nvim >= 2.0.0
nvim-lspconfig >= 2.0.0

Installation & Usage

:h mason-lspconfig-quickstart

Install using your plugin manager of choice. Setup is required:

require("mason-lspconfig").setup()

It's important that you set up mason.nvim and have nvim-lspconfig available in :h runtimepath before setting up mason-lspconfig.nvim.

Refer to the Configuration section for information about which settings are available.

Recommended setup for `lazy.nvim`

The following is the recommended setup when using lazy.nvim. It will set up the plugin for you, meaning you don't have to call require("mason-lspconfig").setup() yourself.

{
    "mason-org/mason-lspconfig.nvim",
    opts = {},
    dependencies = {
        { "mason-org/mason.nvim", opts = {} },
        "neovim/nvim-lspconfig",
    },
}

Automatically enable installed servers

mason-lspconfig.nvim will automatically enable (vim.lsp.enable()) installed servers for you by default.

To disable this feature:

require("mason-lspconfig").setup {
    automatic_enable = false
}

To exclude certain servers from being enabled:

require("mason-lspconfig").setup {
    automatic_enable = {
        exclude = {
            "rust_analyzer",
            "ts_ls"
        }
    }
}

Alternatively, to only enable specific servers:

require("mason-lspconfig").setup {
    automatic_enable = {
        "lua_ls",
        "vimls"
    }
}

Note

This will only enable servers that are installed via Mason. It will not recognize servers installed elsewhere on your system.

Commands

:h mason-lspconfig-commands

:LspInstall [<server> ...]: Installs the provided servers. If no server is provided you will be prompted to select a server based on the current buffer's &filetype.
:LspUninstall <server> ...: Uninstalls the provided servers.

Configuration

:h mason-lspconfig-settings

You may optionally configure certain behavior of mason-lspconfig.nvim when calling the .setup() function. Refer to the default configuration for a list of all available settings.

Example:

require("mason-lspconfig").setup {
    ensure_installed = { "lua_ls", "rust_analyzer" },
}

Configuration using `lazy.nvim`

{
    "mason-org/mason-lspconfig.nvim",
    opts = {
        ensure_installed = { "lua_ls", "rust_analyzer" },
    },
    dependencies = {
        { "mason-org/mason.nvim", opts = {} },
        "neovim/nvim-lspconfig",
    },
}

Default configuration

local DEFAULT_SETTINGS = {
    -- A list of servers to automatically install if they're not already installed. Example: { "rust_analyzer@nightly", "lua_ls" }
    ---@type string[]
    ensure_installed = {},

    -- Whether installed servers should automatically be enabled via `:h vim.lsp.enable()`.
    --
    -- To exclude certain servers from being automatically enabled:
    -- ```lua
    --   automatic_enable = {
    --     exclude = { "rust_analyzer", "ts_ls" }
    --   }
    -- ```
    --
    -- To only enable certain servers to be automatically enabled:
    -- ```lua
    --   automatic_enable = {
    --     "lua_ls",
    --     "vimls"
    --   }
    -- ```
    ---@type boolean | string[] | { exclude: string[] }
    automatic_enable = true,
}

obsidian-nvim/obsidian.nvim

Obsidian 🤝 Neovim (actively maintained version)

obsidian.nvim

A community fork of epwalsh/obsidian.nvim, neovim plugin for Obsidian vaults.

Built for people who love the concept of Obsidian -- a simple, markdown-based notes app -- but love Neovim too much to stand typing characters into anything else.

This plugin is not meant to replace Obsidian, but to complement it. The Obsidian app comes with a mobile app and has a lot of functionality that's not feasible to implement in Neovim, such as the graph explorer view. That said, this plugin stands on its own as well. You don't necessarily need to use it alongside the Obsidian app.

🍴 About the fork

The original project has not been actively maintained for quite a while and with bugs, issues and pull requests piling up, people from the community decided to fork and maintain the project.

Discussions are happening in GitHub Discussions
Sponsor the project at Open Collective
To migrate from original repo or older releases, see Breaking changes
See the documentation:
- obsidian.nvim wiki for documentation of the latest release.
- :Obsidian help or :Obsidian helpgrep for documentation update to date with your current installation.
- :h obsidian-api for API reference.

⭐ Features

▶️ Completion: Ultra-fast, asynchronous autocompletion for note references and tags via nvim-cmp or blink.cmp (triggered by typing [[ for wiki and markdown links, # for tags)

🏃 Navigation: Navigate throughout your vault via links, backlinks, tags and etc.

📷 Images: Paste images into notes.

📈 Status: See note status in footer like obsidian app.

🔄 Sync: Sync support for Obsidian Sync.

Keymaps

smart_action, bind to <CR> will:
- If cursor is on a link, follow the link.
- If cursor is on a tag, show all notes with that tag in a picker.
- If cursor is on a checkbox, toggle the checkbox, see Checkbox.create_new.
- If cursor is on a heading, cycle the fold of that heading, see Folding to set this up.
nav_link, bind to [o and ]o will navigate cursor to next valid link in the buffer.

For other available actions and remapping default ones, see Keymaps

Commands

There's one entry point user command for this plugin: Obsidian

Obsidian<CR> (<enter>) to select sub commands.
Obsidian <Tab> to get completion for sub commands.
Sub commands are context sensitive, meaning some actions will only appear when:
- you are in a note.
- you are in visual mode.
See Commands for more info.

Top level commands

:Obsidian check - check for common issues in your vault and plugin setup
:Obsidian dailies [OFFSET ...] - open a picker list of daily notes
- :Obsidian dailies -2 1 to list daily notes from 2 days ago until tomorrow
:Obsidian help - find files in the help wiki
:Obsidian helpgrep - grep files in the help wiki
:Obsidian new [TITLE] - create a new note
:Obsidian open [QUERY] - open a note in the Obsidian app
- query is used to resolve the note to open by ID, path, or alias, else use current note
:Obsidian today [OFFSET_OR_DATE] - open/create a new daily note
- offset is in days, e.g. use :Obsidian today -1 to go to yesterday's note.
- you can also give an argument like 3-1/2026-3-1, it will parse common date formats and open daily for that specific date.
- Unlike :Obsidian yesterday and :Obsidian tomorrow this command does not differentiate between weekdays and weekends
:Obsidian tomorrow - open/create the daily note for the next working day
:Obsidian yesterday - open/create the daily note for the previous working day
:Obsidian new_from_template [TITLE] [TEMPLATE] - create a new note with TITLE from a template with the name TEMPLATE
- both arguments are optional. If not given, the template will be selected from a list using your preferred picker
:Obsidian quick_switch - switch to another note in your vault, searching by its name with a picker
:Obsidian search [QUERY] - search for (or create) notes in your vault using ripgrep with your preferred picker
:Obsidian sync [SUBCMD] - use obsidian-headless to access official obsidian sync service. Default off, enable with opts.sync.enabled = true, for more see Sync.
:Obsidian tags [TAG ...] - get a picker list of all occurrences of the given tags
:Obsidian unique_note [TITLE] - create a new note with a unique, timestamp-based ID
:Obsidian workspace [NAME] - switch to another workspace

Note commands

:Obsidian backlinks - get a picker list of references to the current note
- grr/vim.lsp.buf.references to see references in quickfix list
:Obsidian follow_link [STRATEGY] - follow a note reference under the cursor
- available strategies: vsplit, hsplit, vsplit_force, hsplit_force
:Obsidian toc - get a picker list of table of contents for current note
:Obsidian template [NAME] - insert a template from the templates folder, selecting from a list using your preferred picker
- Template
:Obsidian links - get a picker list of all links in current note
:Obsidian paste_img [IMGNAME] - paste an image from the clipboard into the note at the cursor position by saving it to the vault and adding a markdown image link
- Images
:Obsidian rename [NEWNAME] - rename the note of the current buffer or reference under the cursor, updating all backlinks across the vault
- runs :wa before renaming, and loads every note with backlinks into your buffer-list
- after renaming you need to do :wa again for changes to take effect
- alternatively, call vim.lsp.buf.rename or use grn
:Obsidian toggle_checkbox - cycle through checkbox options

Visual mode commands

:Obsidian extract_note [TITLE] - extract the visually selected text into a new note and link to it
:Obsidian link [QUERY] - link an inline visual selection of text to a note
- query will be used to resolve the note by ID, path, or alias, else query is selected text
:Obsidian link_new [TITLE] - create a new note and link it to an inline visual selection of text
- if title is not given, selected text is used

📝 Requirements

System requirements

Neovim >= 0.10.0
For completion and search features: ripgrep
Additional system dependencies:
- Windows WSL users need wsl-open for :Obsidian open.
- MacOS users need pngpaste (brew install pngpaste) for :Obsidian paste_img.
- Linux users need xclip (X11) or wl-clipboard (Wayland) for :Obsidian paste_img.

Plugin dependencies

There's no required dependency, but there are a number of optional dependencies that enhance the obsidian.nvim experience.

Completion:

Pickers:

Image viewing:

snacks.image
See Images for configuration.

📥 Installation

Warning

For stability you may want to use latest release, be aware that the README on main may reference features that haven't been released yet.

So view the README on the tag for the latest release instead of main.

Tip

To see your installation status, run :checkhealth obsidian

To try out or debug this plugin, run nvim -u minimal.lua to try in a clean environment

Using `lazy.nvim`

return {
  "obsidian-nvim/obsidian.nvim",
  version = "*", -- use latest release, remove to use latest commit
  ---@module 'obsidian'
  ---@type obsidian.config
  opts = {
    legacy_commands = false, -- this will be removed in the next major release
    workspaces = {
      {
        name = "personal",
        path = "~/vaults/personal",
      },
      {
        name = "work",
        path = "~/vaults/work",
      },
    },
  },
}

Using `rocks.nvim`

:Rocks install obsidian.nvim

Using `vim.pack` (nvim-0.12+)

vim.pack.add {
  {
    src = "https://github.com/obsidian-nvim/obsidian.nvim",
    version = vim.version.range "*", -- use latest release, remove to use latest commit
  },
}

⚙️ Configuration

To configure obsidian.nvim, pass your custom options that are different from default options to require"obsidian".setup().

🤝 Contributing

Please read the CONTRIBUTING guide before submitting a pull request.

_neo451 💻	_{Stefan Otte} 💻	_guspix 💻	_ffricken 💻	_{Erlan Rangel} 💻	_bosvik 💻	_{Jost Alemann} 📖
_{Luis Garcia} 💻	_Joe 💻	_{Horia Gug} 💻	_{Aquiles Gomez} 💻	_{Alvaro Sevilla} 💻	_{Sebastian Stark} 💻	_{Jumpei Yamakawa} 💻
_marcocofano 💻	_Jaehaks 💻	_Magnus 💻	_{Noam Stolero} 💻	_aileot 💻	_{Rico Sta. Cruz} 📖	_{KIM Hyunjae} 💻
_{Ben Burgess} 💻	_{Sebastian Szyller} 💻	_nobe4 💻	_Anaritus 💻	_{Michael Davis} 💻	_{Brian Rodriguez} 💻	_carschandler 📖
_{Aki Sasaki} 💻	_{Reinaldo Molina} 💻	_{Stuart Rackham} 💻	_{Ahmed Mughal} 💻	_{trash-panda-v91-beta} 💻	_{Jakob Westhoff} 💻	_{Christian Johansen} 💻
_{Volodymyr Kot} 💻	_{Jorge Villalobos} 💻	_Tak 💻	_{Emilio Marin} 💻	_{Vladimir Gusev} 💻	_{FirelightFlagboy} 💻	_{Cameron Ring} 💻
_{Miklós Balázs} 💻	_{Clément Vannicatte} 📖	_Anatoliy 💻	_acidsugarx 💻	_{João Sampaio} 💻	_{Sundar Gurumurthy} 💻	_apalermo01 💻
_S1RENS 💻	_CaeChao 💻	_{Kahlil Hodgson} 💻	_{Frederik Roland Christiansen} 💻	_{Lucky Laughing} 💻	_{Jorg Jenni} 💻	_zzhirong 💻
_{Franco Ruggeri} 💻	_{John T. Kelly} 💻	_antinomie8 💻

❤️ Acknowledgement

We would like to thank epwalsh for creating this beautiful plugin. If you're feeling especially generous, he still appreciates some coffee funds!.

olimorris/codecompanion.nvim

✨ AI Coding, Vim Style

Code with LLMs and Agents via the in-built adapters, the community adapters or by building your own

New features are always announced here

💜 Sponsors

Thank you to the following people:

If you love CodeCompanion and use it in your workflow, please consider sponsoring me

✨ Features

💬 Copilot Chat meets Zed AI, in Neovim
⚡ Integrates Neovim with LLMs and Agents in the CLI
🔌 Support for LLMs from Anthropic, Copilot, GitHub Models, DeepSeek, Gemini, Mistral AI, Novita, Ollama, OpenAI, Azure OpenAI, HuggingFace and xAI (or bring your own)
🤖 Support for Agent Client Protocol, enabling coding with agents like Augment Code, Cagent from Docker, Claude Code, Codex, Copilot CLI, Gemini CLI, Goose, Cursor CLI, Kimi CLI, Kiro, Mistral Vibe and OpenCode
🫶 User contributed and supported adapters
🔋 Support for Model Context Protocol (MCP)
🚀 Inline transformations, code creation and refactoring
🎨 Editor Context, Slash Commands, Agents/Tools and Workflows to improve LLM output
🧠 Support for rules files like CLAUDE.md, .cursor/rules and your own custom ones
✨ Built-in prompt library for common tasks like advice on LSP errors and code explanations
🏗️ Create your own custom prompts, Editor Context and Slash Commands
📚 Have multiple chats open at the same time
🎨 Support for vision and images as input
💪 Async execution for fast performance

📸 In Action

The Chat Buffer

Tools + Agentic Workflows

Inline Interaction

🚀 Getting Started

Everything you need to know about CodeCompanion (installation, configuration and usage) is within the docs.

🧰 Troubleshooting

Before raising an issue, there are a number of steps you can take to troubleshoot a problem:

Checkhealth

Run :checkhealth codecompanion and check all dependencies are installed correctly. Also take note of the log file path.

Turn on logging

Update your config and turn debug logging on:

-- lazy.nvim
{
  "olimorris/codecompanion.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim",
    "nvim-treesitter/nvim-treesitter",
  },
  opts = {
    -- NOTE: The log_level is in `opts.opts`
    opts = {
      log_level = "DEBUG", -- or "TRACE"
    },
  },
},

-- Other package managers
require("codecompanion").setup({
  opts = {
    log_level = "DEBUG", -- or "TRACE"
  }
})

and inspect the log file as per the location from the checkhealth command.

Try with a minimal.lua file

A large proportion of issues which are raised in Neovim plugins are to do with a user's own config. That's why I always ask users to fill in a minimal.lua file when they raise an issue. We can rule out their config being an issue and it allows me to recreate the problem.

For this purpose, I have included a minimal.lua file in the repository for you to test out if you're facing issues. Simply copy the file, edit it and run neovim with nvim --clean -u minimal.lua.

🎁 Contributing

I am open to contributions but they will be implemented at my discretion. Feel free to open up a discussion before embarking on a PR and please read the CONTRIBUTING.md guide.

👏 Acknowledgements

Steven Arcangeli for his genius creation of the chat buffer and his feedback early on
Wtf.nvim for the LSP assistant action
CopilotChat.nvim for the rendering and usability of the chat buffer
Aerial.nvim for the Tree-sitter parsing which inspired the symbols Slash Command
Saghen for the fantastic docs inspiration from blink.cmp and continued PRs to the project
Catwell for the queue inspiration that I use to stack agents and tools
bassamsdata for the amazing insert_edit_into_file tool (the list is endless) and ongoing contributions to this project
ravitemer for the fantastic extensions API
Davidyz for his continued, excellent contributions that keep CodeCompanion going
Conrad Irwin, Agus Zubiaga and Morgan Krey from Zed Industries for their support in implementing ACP
Sidekick.nvim for the diff and terminal input inspiration

stevearc/oil.nvim

Neovim file explorer: edit your filesystem like a buffer

oil.nvim

A vim-vinegar like file explorer that lets you edit your filesystem like a normal Neovim buffer.

https://user-images.githubusercontent.com/506791/209727111-6b4a11f4-634a-4efa-9461-80e9717cea94.mp4

Requirements

Neovim 0.8+
Icon provider plugin (optional)
- mini.icons for file and folder icons
- nvim-web-devicons for file icons

Installation

oil.nvim supports all the usual plugin managers

lazy.nvim

{
  'stevearc/oil.nvim',
  ---@module 'oil'
  ---@type oil.SetupOpts
  opts = {},
  -- Optional dependencies
  dependencies = { { "nvim-mini/mini.icons", opts = {} } },
  -- dependencies = { "nvim-tree/nvim-web-devicons" }, -- use if you prefer nvim-web-devicons
  -- Lazy loading is not recommended because it is very tricky to make it work correctly in all situations.
  lazy = false,
}

Packer

require("packer").startup(function()
  use({
    "stevearc/oil.nvim",
    config = function()
      require("oil").setup()
    end,
  })
end)

Paq

require("paq")({
  { "stevearc/oil.nvim" },
})

vim-plug

Plug 'stevearc/oil.nvim'

dein

call dein#add('stevearc/oil.nvim')

Pathogen

git clone --depth=1 https://github.com/stevearc/oil.nvim.git ~/.vim/bundle/

Neovim native package

git clone --depth=1 https://github.com/stevearc/oil.nvim.git \
  "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/oil/start/oil.nvim

Quick start

Add the following to your init.lua

require("oil").setup()

Then open a directory with nvim .. Use <CR> to open a file/directory, and - to go up a directory. Otherwise, just treat it like a normal buffer and make changes as you like. Remember to :w when you're done to actually perform the actions.

If you want to mimic the vim-vinegar method of navigating to the parent directory of a file, add this keymap:

vim.keymap.set("n", "-", "<CMD>Oil<CR>", { desc = "Open parent directory" })

You can open a directory with :edit <path> or :Oil <path>. To open oil in a floating window, do :Oil --float <path>.

Options

require("oil").setup({
  -- Oil will take over directory buffers (e.g. `vim .` or `:e src/`)
  -- Set to false if you want some other plugin (e.g. netrw) to open when you edit directories.
  default_file_explorer = true,
  -- Id is automatically added at the beginning, and name at the end
  -- See :help oil-columns
  columns = {
    "icon",
    -- "permissions",
    -- "size",
    -- "mtime",
  },
  -- Buffer-local options to use for oil buffers
  buf_options = {
    buflisted = false,
    bufhidden = "hide",
  },
  -- Window-local options to use for oil buffers
  win_options = {
    wrap = false,
    signcolumn = "no",
    cursorcolumn = false,
    foldcolumn = "0",
    spell = false,
    list = false,
    conceallevel = 3,
    concealcursor = "nvic",
  },
  -- Send deleted files to the trash instead of permanently deleting them (:help oil-trash)
  delete_to_trash = false,
  -- Skip the confirmation popup for simple operations (:help oil.skip_confirm_for_simple_edits)
  skip_confirm_for_simple_edits = false,
  -- Selecting a new/moved/renamed file or directory will prompt you to save changes first
  -- (:help prompt_save_on_select_new_entry)
  prompt_save_on_select_new_entry = true,
  -- Oil will automatically delete hidden buffers after this delay
  -- You can set the delay to false to disable cleanup entirely
  -- Note that the cleanup process only starts when none of the oil buffers are currently displayed
  cleanup_delay_ms = 2000,
  lsp_file_methods = {
    -- Enable or disable LSP file operations
    enabled = true,
    -- Time to wait for LSP file operations to complete before skipping
    timeout_ms = 1000,
    -- Set to true to autosave buffers that are updated with LSP willRenameFiles
    -- Set to "unmodified" to only save unmodified buffers
    autosave_changes = false,
  },
  -- Constrain the cursor to the editable parts of the oil buffer
  -- Set to `false` to disable, or "name" to keep it on the file names
  constrain_cursor = "editable",
  -- Set to true to watch the filesystem for changes and reload oil
  watch_for_changes = false,
  -- Keymaps in oil buffer. Can be any value that `vim.keymap.set` accepts OR a table of keymap
  -- options with a `callback` (e.g. { callback = function() ... end, desc = "", mode = "n" })
  -- Additionally, if it is a string that matches "actions.<name>",
  -- it will use the mapping at require("oil.actions").<name>
  -- Set to `false` to remove a keymap
  -- See :help oil-actions for a list of all available actions
  keymaps = {
    ["g?"] = { "actions.show_help", mode = "n" },
    ["<CR>"] = "actions.select",
    ["<C-s>"] = { "actions.select", opts = { vertical = true } },
    ["<C-h>"] = { "actions.select", opts = { horizontal = true } },
    ["<C-t>"] = { "actions.select", opts = { tab = true } },
    ["<C-p>"] = "actions.preview",
    ["<C-c>"] = { "actions.close", mode = "n" },
    ["<C-l>"] = "actions.refresh",
    ["-"] = { "actions.parent", mode = "n" },
    ["_"] = { "actions.open_cwd", mode = "n" },
    ["`"] = { "actions.cd", mode = "n" },
    ["g~"] = { "actions.cd", opts = { scope = "tab" }, mode = "n" },
    ["gs"] = { "actions.change_sort", mode = "n" },
    ["gx"] = "actions.open_external",
    ["g."] = { "actions.toggle_hidden", mode = "n" },
    ["g\\"] = { "actions.toggle_trash", mode = "n" },
  },
  -- Set to false to disable all of the above keymaps
  use_default_keymaps = true,
  view_options = {
    -- Show files and directories that start with "."
    show_hidden = false,
    -- This function defines what is considered a "hidden" file
    is_hidden_file = function(name, bufnr)
      local m = name:match("^%.")
      return m ~= nil
    end,
    -- This function defines what will never be shown, even when `show_hidden` is set
    is_always_hidden = function(name, bufnr)
      return false
    end,
    -- Sort file names with numbers in a more intuitive order for humans.
    -- Can be "fast", true, or false. "fast" will turn it off for large directories.
    natural_order = "fast",
    -- Sort file and directory names case insensitive
    case_insensitive = false,
    sort = {
      -- sort order can be "asc" or "desc"
      -- see :help oil-columns to see which columns are sortable
      { "type", "asc" },
      { "name", "asc" },
    },
    -- Customize the highlight group for the file name
    highlight_filename = function(entry, is_hidden, is_link_target, is_link_orphan)
      return nil
    end,
  },
  -- Extra arguments to pass to SCP when moving/copying files over SSH
  extra_scp_args = {},
  -- Extra arguments to pass to aws s3 when creating/deleting/moving/copying files using aws s3
  extra_s3_args = {},
  -- EXPERIMENTAL support for performing file operations with git
  git = {
    -- Return true to automatically git add/mv/rm files
    add = function(path)
      return false
    end,
    mv = function(src_path, dest_path)
      return false
    end,
    rm = function(path)
      return false
    end,
  },
  -- Configuration for the floating window in oil.open_float
  float = {
    -- Padding around the floating window
    padding = 2,
    -- max_width and max_height can be integers or a float between 0 and 1 (e.g. 0.4 for 40%)
    max_width = 0,
    max_height = 0,
    border = nil,
    win_options = {
      winblend = 0,
    },
    -- optionally override the oil buffers window title with custom function: fun(winid: integer): string
    get_win_title = nil,
    -- preview_split: Split direction: "auto", "left", "right", "above", "below".
    preview_split = "auto",
    -- This is the config that will be passed to nvim_open_win.
    -- Change values here to customize the layout
    override = function(conf)
      return conf
    end,
  },
  -- Configuration for the file preview window
  preview_win = {
    -- Whether the preview window is automatically updated when the cursor is moved
    update_on_cursor_moved = true,
    -- How to open the preview window "load"|"scratch"|"fast_scratch"
    preview_method = "fast_scratch",
    -- A function that returns true to disable preview on a file e.g. to avoid lag
    disable_preview = function(filename)
      return false
    end,
    -- Window-local options to use for preview window buffers
    win_options = {},
  },
  -- Configuration for the floating action confirmation window
  confirmation = {
    -- Width dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%)
    -- min_width and max_width can be a single value or a list of mixed integer/float types.
    -- max_width = {100, 0.8} means "the lesser of 100 columns or 80% of total"
    max_width = 0.9,
    -- min_width = {40, 0.4} means "the greater of 40 columns or 40% of total"
    min_width = { 40, 0.4 },
    -- optionally define an integer/float for the exact width of the preview window
    width = nil,
    -- Height dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%)
    -- min_height and max_height can be a single value or a list of mixed integer/float types.
    -- max_height = {80, 0.9} means "the lesser of 80 columns or 90% of total"
    max_height = 0.9,
    -- min_height = {5, 0.1} means "the greater of 5 columns or 10% of total"
    min_height = { 5, 0.1 },
    -- optionally define an integer/float for the exact height of the preview window
    height = nil,
    border = nil,
    win_options = {
      winblend = 0,
    },
  },
  -- Configuration for the floating progress window
  progress = {
    max_width = 0.9,
    min_width = { 40, 0.4 },
    width = nil,
    max_height = { 10, 0.9 },
    min_height = { 5, 0.1 },
    height = nil,
    border = nil,
    minimized_border = "none",
    win_options = {
      winblend = 0,
    },
  },
  -- Configuration for the floating SSH window
  ssh = {
    border = nil,
  },
  -- Configuration for the floating keymaps help window
  keymaps_help = {
    border = nil,
  },
})

Adapters

Oil does all of its filesystem interaction through an adapter abstraction. In practice, this means that oil can be used to view and modify files in more places than just the local filesystem, so long as the destination has an adapter implementation.

Note that file operations work across adapters. This means that you can use oil to copy files to/from a remote server using the ssh adapter just as easily as you can copy files from one directory to another on your local machine.

SSH

This adapter allows you to browse files over ssh, much like netrw. To use it, simply open a buffer using the following name template:

nvim oil-ssh://[username@]hostname[:port]/[path]

This may look familiar. In fact, this is the same url format that netrw uses.

Note that at the moment the ssh adapter does not support Windows machines, and it requires the server to have a /bin/sh binary as well as standard unix commands (ls, rm, mv, mkdir, chmod, cp, touch, ln, echo).

S3

This adapter allows you to browse files stored in aws s3. To use it, make sure aws is setup correctly and then simply open a buffer using the following name template:

nvim oil-s3://[bucket]/[path]

Note that older versions of Neovim don't support numbers in the url, so for Neovim 0.11 and older the url starts with oil-sss.

Recipes

Third-party extensions

These are plugins maintained by other authors that extend the functionality of oil.nvim.

oil-git-status.nvim - Shows git status of files in statuscolumn
oil-git.nvim - Shows git status of files with colour and symbols
oil-git.nvim - Async git status integration with directory support
oil-lsp-diagnostics.nvim - Shows LSP diagnostics indicator as virtual text

API

FAQ

Q: Why "oil"?

A: From the vim-vinegar README, a quote by Drew Neil:

Split windows and the project drawer go together like oil and vinegar

Vinegar was taken. Let's be oil. Plus, I think it's pretty slick 😉

Q: Why would I want to use oil vs any other plugin?

You like to use a netrw-like view to browse directories (as opposed to a file tree)
AND you want to be able to edit your filesystem like a buffer
AND you want to perform cross-directory actions. AFAIK there is no other plugin that does this. (update: mini.files also offers this functionality)

If you don't need those features specifically, check out the alternatives listed below

Q: Why write another plugin yourself instead of adding functionality to one that already exists?

A: Because I am a maniac control freak.

Q: Can oil display files as a tree view?

A: No. A tree view would require a completely different methodology, necessitating a complete rewrite. I don't use tree views, so I will leave this as a plugin for someone else to write.

Q: What are some alternatives?

mini.files: A newer plugin that also supports cross-directory filesystem-as-buffer edits. It utilizes a unique column view.
vim-vinegar: The granddaddy. This made me fall in love with single-directory file browsing. I stopped using it when I encountered netrw bugs and performance issues.
defx.nvim: What I switched to after vim-vinegar. Much more flexible and performant, but requires python and the API is a little hard to work with.
dirbuf.nvim: The first plugin I encountered that let you edit the filesystem like a buffer. Never used it because it can't do cross-directory edits.
lir.nvim: What I used prior to writing this plugin. Similar to vim-vinegar, but with better Neovim integration (floating windows, lua API).
vim-dirvish: Never personally used, but well-established, stable, simple directory browser.
vidir: Never personally used, but might be the first plugin to come up with the idea of editing a directory like a buffer.

There's also file trees like neo-tree and nvim-tree, but they're really a different category entirely.

nvim-tree/nvim-web-devicons

Provides Nerd Font icons (glyphs) for use by neovim plugins

Nvim-web-devicons

Provides Nerd Font ^[1] icons (glyphs) for use by Neovim plugins:

Icons by:
- Extension
- Full name
Colours
Light and dark variants
API to modify/add icons

A lua fork of vim-devicons.

Tip

nvim-web-devicons adds new icons as they are introduced to Nerd Fonts. Please ensure that you are using the latest version of the font as newly introduced icons may display incorrectly or as an "unknown character".

Important

Nerd fonts moved some symbols with version 3.0. Version 2.3 is meant for transition, supporting both version 2 and version 3 icons. Nvim-web-devicons requires version 2.3 or above to work properly. If you are unable to update please use your plugin manager to pin version of nvim-web-dev icons to nerd-v2-compat tag.

Requirements

Installation

Plug 'nvim-tree/nvim-web-devicons'

or with packer.nvim

use 'nvim-tree/nvim-web-devicons'

or with lazy.nvim

{ "nvim-tree/nvim-web-devicons", opts = {} },

Additional Icons

Additional icons may be added for icons that are present in Nerd Fonts: use the Cheat Sheet search for available icons.

PRs are always welcome! Please see CONTRIBUTING

Important

If the icon you need is not available on Nerd Fonts you first need to make a PR to a project that feeds glyphs to Nerd Fonts. Probably the most adequate project to contribute is https://github.com/devicons/devicon. Take into account that months can pass before the icon is available on the Nerd Fonts project, once there feel free to open a PR on this project, see CONTRIBUTING

Usage

Viewing

Run :NvimWebDeviconsHiTest to see all icons and their highlighting.

Variants

Light or dark color variants of the icons depend on &background.
The variant can also be set manually in setup with the variant option.

The variant is updated:

on OptionSet event for background, or
after explicitly calling require("nvim-web-devicons").refresh().

However, be advised that the plugin using nvim-web-devicons may have cached the icons.

Case Sensitivity

Filename icons e.g. "Dockerfile" are case insensitively matched.

Extension icons e.g. "lua" are case sensitive.

Setup

This adds all the highlight groups for the devicons i.e. it calls vim.api.nvim_set_hl for all icons this might need to be re-called in a Colorscheme to re-apply cleared highlights if the color scheme changes

require'nvim-web-devicons'.setup {
 -- your personal icons can go here (to override)
 -- you can specify color or cterm_color instead of specifying both of them
 -- DevIcon will be appended to `name`
 override = {
  zsh = {
    icon = "",
    color = "#428850",
    cterm_color = "65",
    name = "Zsh"
  }
 };
 -- globally enable different highlight colors per icon (default to true)
 -- if set to false all icons will have the default icon's color
 color_icons = true;
 -- globally enable default icons (default to false)
 -- will get overriden by `get_icons` option
 default = true;
 -- globally enable "strict" selection of icons - icon will be looked up in
 -- different tables, first by filename, and if not found by extension; this
 -- prevents cases when file doesn't have any extension but still gets some icon
 -- because its name happened to match some extension (default to false)
 strict = true;
 -- set the light or dark variant manually, instead of relying on `background`
 -- (default to nil)
 variant = "light|dark";
 -- override blend value for all highlight groups :h highlight-blend.
 -- setting this value to `0` will make all icons opaque. in practice this means
 -- that icons width will not be affected by pumblend option (see issue #608)
 -- (default to nil)
 blend = 0;
 -- same as `override` but specifically for overrides by filename
 -- takes effect when `strict` is true
 override_by_filename = {
  [".gitignore"] = {
    icon = "",
    color = "#f1502f",
    name = "Gitignore"
  }
 };
 -- same as `override` but specifically for overrides by extension
 -- takes effect when `strict` is true
 override_by_extension = {
  ["log"] = {
    icon = "",
    color = "#81e043",
    name = "Log"
  }
 };
 -- same as `override` but specifically for operating system
 -- takes effect when `strict` is true
 override_by_operating_system = {
  ["apple"] = {
    icon = "",
    color = "#A2AAAD",
    cterm_color = "248",
    name = "Apple",
  },
 };
}

Get Icon

Get the icon for a given file by passing in the name, the extension and an optional options table. The name is passed in to check for an exact match e.g. .bashrc if there is no exact name match the extension is used. Calls .setup() if it hasn't already ran.

require'nvim-web-devicons'.get_icon(filename, extension, options)

The optional options argument can used to change how the plugin works the keys include default = <boolean> and strict = <boolean>. If the default key is set to true this function will return a default if there is no matching icon. If the strict key is set to true this function will lookup icon specifically by filename, and if not found then specifically by extension, and fallback to default icon if default key is set to true. e.g.

require'nvim-web-devicons'.get_icon(filename, extension, { default = true })

You can check if the setup function was already called with:

require'nvim-web-devicons'.has_loaded()

Get icon and color code

get_icon_color differs from get_icon only in the second return value. get_icon_cterm_color returns cterm color instead of gui color get_icon returns icon and highlight name. If you want to get color code, you can use this function.

local icon, color = require'nvim-web-devicons'.get_icon_color("init.lua", "lua")
assert(icon == "")
assert(color == "#51a0cf")

Get all icons

It is possible to get all of the registered icons with the get_icons() function:

require'nvim-web-devicons'.get_icons()

This can be useful for debugging purposes or for creating custom highlights for each icon.

Mapped categories can be fetched via:

require'nvim-web-devicons'.get_icons_by_filename()
require'nvim-web-devicons'.get_icons_by_extension()
require'nvim-web-devicons'.get_icons_by_operating_system()
require'nvim-web-devicons'.get_icons_by_desktop_environment()
require'nvim-web-devicons'.get_icons_by_window_manager()

Set an icon

You can override individual icons with the set_icon({...}) function:

require("nvim-web-devicons").set_icon {
  zsh = {
    icon = "",
    color = "#428850",
    cterm_color = "65",
    name = "Zsh"
  }
}

You can override the default icon with the set_default_icon(icon, color, cterm_color) function:

require("nvim-web-devicons").set_default_icon('', '#6d8086', 65)

Getting and setting icons by filetype

You can get the icon and colors associated with a filetype using the by_filetype functions:

require("nvim-web-devicons").get_icon_by_filetype(filetype, opts)
require("nvim-web-devicons").get_icon_colors_by_filetype(filetype, opts)
require("nvim-web-devicons").get_icon_color_by_filetype(filetype, opts)
require("nvim-web-devicons").get_icon_cterm_color_by_filetype(filetype, opts)

or set the icon to use for a filetype with:

require("nvim-web-devicons").set_icon_by_filetype { cpp = "c", pandoc = "md", }

These functions are the same as their counterparts without the _by_filetype suffix, but they take a filetype instead of a name/extension.

You can also use get_icon_name_by_filetype(filetype) to get the icon name associated with the filetype.

Known Issues

My `setup` Overrides Are Not Applied

Cause: A plugin may be calling nvim-web-devicons setup before you do. Your setup call will be ignored.

Workaround: Call nvim-web-devicons setup before the plugin's own setup.

Windows and WSL not rendering icons properly on some terminals

On Windows and WSL, it is possible that the icons are not rendered properly when using a terminal that relies on Windows' default system libraries. An example of this is Alacritty (#271). Other terminals (e.g. Windows Terminal, and WezTerm) do no have this issue, as they ship newer versions of these libraries. More precisely, they use newer versions of conpty.dll and OpenConsole.exe. So, as a workaround to the rendering issue, you need to make your terminal use these newer files. Whether this is possible depends on the terminal you are using. Please refer to the terminal's documentation for this.

In the specific case of Alacritty, you need to place up-to-date conpty.dll and OpenConsole.exe files in your PATH. Microsoft does not provide these files directly, but you can get them from other terminal emulators that ship them.

Contributing

PRs are always welcome! Please see CONTRIBUTING

Not limited to Nerd Font icons: unicode and other fonts may be used. ↩︎

mason-org/mason.nvim

Portable package manager for Neovim that runs everywhere Neovim runs. Easily install and manage LSP servers, DAP servers, linters, and formatters.

Portable package manager for Neovim that runs everywhere Neovim runs.
Easily install and manage LSP servers, DAP servers, linters, and formatters.

:help mason.nvim

^{Latest version: v2.2.1}

Introduction

:h mason-introduction

mason.nvim is a Neovim plugin that allows you to easily manage external editor tooling such as LSP servers, DAP servers, linters, and formatters through a single interface. It runs everywhere Neovim runs (across Linux, macOS, Windows, etc.), with only a small set of external requirements needed.

Packages are installed in Neovim's data directory (:h standard-path) by default. Executables are linked to a single bin/ directory, which mason.nvim will add to Neovim's PATH during setup, allowing seamless access from Neovim builtins (LSP client, shell, terminal, etc.) as well as other 3rd party plugins.

For a list of all available packages, see https://mason-registry.dev/registry/list.

Installation & Usage

:h mason-quickstart

Install using your plugin manager of choice. Setup is required:

require("mason").setup()

mason.nvim is optimized to load as little as possible during setup. Lazy-loading the plugin, or somehow deferring the setup, is not recommended.

Refer to the Configuration section for information about which settings are available.

Recommended setup for `lazy.nvim`

The following is the recommended setup when using lazy.nvim. It will set up the plugin for you, meaning you don't have to call require("mason").setup() yourself.

{
    "mason-org/mason.nvim",
    opts = {}
}

Requirements

:h mason-requirements

mason.nvim relaxes the minimum requirements by attempting multiple different utilities (for example, wget, curl, and Invoke-WebRequest are all perfect substitutes). The minimum recommended requirements are:

neovim >= 0.10.0
For Unix systems:
- git(1)
- curl(1) or GNU wget(1)
- unzip(1)
- GNU tar (tar(1) or gtar(1) depending on platform)
- gzip(1)
For Windows systems:
- pwsh or powershell
- git
- GNU tar
- One of the following:
  - 7zip
  - peazip
  - archiver
  - winzip
  - WinRAR

Note that mason.nvim will regularly shell out to external package managers, such as cargo and npm. Depending on your personal usage, some of these will also need to be installed. Refer to :checkhealth mason for a full list.

Commands

:h mason-commands

:Mason - opens a graphical status window
:MasonUpdate - updates all managed registries
:MasonInstall <package> ... - installs/re-installs the provided packages
:MasonUninstall <package> ... - uninstalls the provided packages
:MasonUninstallAll - uninstalls all packages
:MasonLog - opens the mason.nvim log file in a new tab window

Registries

Mason's core package registry is located at mason-org/mason-registry. Before any packages can be used, the registry needs to be downloaded. This is done automatically for you when using the different Mason commands (e.g. :MasonInstall), but can also be done manually by using the :MasonUpdate command.

If you're utilizing Mason's Lua APIs to access packages, it's recommended to use the :h mason-registry.refresh() or :h mason-registry.update() functions to ensure you have the latest package information before retrieving packages.

Screenshots

Configuration

:h mason-settings

You may optionally configure certain behavior of mason.nvim when calling the .setup() function. Refer to the default configuration for a list of all available settings.

Example:

require("mason").setup({
    ui = {
        icons = {
            package_installed = "✓",
            package_pending = "➜",
            package_uninstalled = "✗"
        }
    }
})

Configuration using `lazy.nvim`

{
    "mason-org/mason.nvim",
    opts = {
        ui = {
            icons = {
                package_installed = "✓",
                package_pending = "➜",
                package_uninstalled = "✗"
            }
        }
    }
}

Default configuration

---@class MasonSettings
local DEFAULT_SETTINGS = {
    ---@since 1.0.0
    -- The directory in which to install packages.
    install_root_dir = path.concat { vim.fn.stdpath "data", "mason" },

    ---@since 1.0.0
    -- Where Mason should put its bin location in your PATH. Can be one of:
    -- - "prepend" (default, Mason's bin location is put first in PATH)
    -- - "append" (Mason's bin location is put at the end of PATH)
    -- - "skip" (doesn't modify PATH)
    ---@type '"prepend"' | '"append"' | '"skip"'
    PATH = "prepend",

    ---@since 1.0.0
    -- Controls to which degree logs are written to the log file. It's useful to set this to vim.log.levels.DEBUG when
    -- debugging issues with package installations.
    log_level = vim.log.levels.INFO,

    ---@since 1.0.0
    -- Limit for the maximum amount of packages to be installed at the same time. Once this limit is reached, any further
    -- packages that are requested to be installed will be put in a queue.
    max_concurrent_installers = 4,

    ---@since 1.0.0
    -- [Advanced setting]
    -- The registries to source packages from. Accepts multiple entries. Should a package with the same name exist in
    -- multiple registries, the registry listed first will be used.
    registries = {
        "github:mason-org/mason-registry",
    },

    ---@since 1.0.0
    -- The provider implementations to use for resolving supplementary package metadata (e.g., all available versions).
    -- Accepts multiple entries, where later entries will be used as fallback should prior providers fail.
    -- Builtin providers are:
    --   - mason.providers.registry-api  - uses the https://api.mason-registry.dev API
    --   - mason.providers.client        - uses only client-side tooling to resolve metadata
    providers = {
        "mason.providers.registry-api",
        "mason.providers.client",
    },

    github = {
        ---@since 1.0.0
        -- The template URL to use when downloading assets from GitHub.
        -- The placeholders are the following (in order):
        -- 1. The repository (e.g. "rust-lang/rust-analyzer")
        -- 2. The release version (e.g. "v0.3.0")
        -- 3. The asset name (e.g. "rust-analyzer-v0.3.0-x86_64-unknown-linux-gnu.tar.gz")
        download_url_template = "https://github.com/%s/releases/download/%s/%s",
    },

    pip = {
        ---@since 1.0.0
        -- Whether to upgrade pip to the latest version in the virtual environment before installing packages.
        upgrade_pip = false,

        ---@since 1.0.0
        -- These args will be added to `pip install` calls. Note that setting extra args might impact intended behavior
        -- and is not recommended.
        --
        -- Example: { "--proxy", "https://proxyserver" }
        install_args = {},
    },

    ui = {
        ---@since 1.0.0
        -- Whether to automatically check for new versions when opening the :Mason window.
        check_outdated_packages_on_open = true,

        ---@since 1.0.0
        -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|.
        -- Defaults to `:h 'winborder'` if nil.
        border = nil,

        ---@since 1.11.0
        -- The backdrop opacity. 0 is fully opaque, 100 is fully transparent.
        backdrop = 60,

        ---@since 1.0.0
        -- Width of the window. Accepts:
        -- - Integer greater than 1 for fixed width.
        -- - Float in the range of 0-1 for a percentage of screen width.
        width = 0.8,

        ---@since 1.0.0
        -- Height of the window. Accepts:
        -- - Integer greater than 1 for fixed height.
        -- - Float in the range of 0-1 for a percentage of screen height.
        height = 0.9,

        icons = {
            ---@since 1.0.0
            -- The list icon to use for installed packages.
            package_installed = "◍",
            ---@since 1.0.0
            -- The list icon to use for packages that are installing, or queued for installation.
            package_pending = "◍",
            ---@since 1.0.0
            -- The list icon to use for packages that are not installed.
            package_uninstalled = "◍",
        },

        keymaps = {
            ---@since 1.0.0
            -- Keymap to expand a package
            toggle_package_expand = "<CR>",
            ---@since 1.0.0
            -- Keymap to install the package under the current cursor position
            install_package = "i",
            ---@since 1.0.0
            -- Keymap to reinstall/update the package under the current cursor position
            update_package = "u",
            ---@since 1.0.0
            -- Keymap to check for new version for the package under the current cursor position
            check_package_version = "c",
            ---@since 1.0.0
            -- Keymap to update all installed packages
            update_all_packages = "U",
            ---@since 1.0.0
            -- Keymap to check which installed packages are outdated
            check_outdated_packages = "C",
            ---@since 1.0.0
            -- Keymap to uninstall a package
            uninstall_package = "X",
            ---@since 1.0.0
            -- Keymap to cancel a package installation
            cancel_installation = "<C-c>",
            ---@since 1.0.0
            -- Keymap to apply language filter
            apply_language_filter = "<C-f>",
            ---@since 1.1.0
            -- Keymap to toggle viewing package installation log
            toggle_package_install_log = "<CR>",
            ---@since 1.8.0
            -- Keymap to toggle the help view
            toggle_help = "g?",
        },
    },
}

^{👋 didn't find what you were looking for? Try looking in the help docs :help mason.nvim!}

GitHub Lua Weekly Trending

neovim/nvim-lspconfig

nvim-lspconfig

Important ⚠️

Migration instructions

Support

Install

Quickstart

Commands

Configuration

Config priority

Creating a config

As code

As a file

LSP Settings Type Annotations

Troubleshooting

Bug reports

Contributions

Release process

License

iDvel/rime-ice

雾凇拼音

基本套路

长期维护词库

使用说明

选择和安装 RIME 前端

手动安装

Git 安装

东风破 plum

仓输入法 Hamster

自动部署脚本

Arch Linux

Linux Fcitx4

感谢 ❤️

赞助 ☕

amzxyz/rime_wanxiang

万象系列方案

🌌 万象拼音——基于深度优化的词库和语法模型

🚀 核心功能亮点

🌟 项目愿景

✨ 效果预览 & 版本对比

🚀 新手快速入门

1. 📦 快速部署 (通用步骤)

2. 🍎 iOS 平台特殊操作指南

3. 🧠 语法模型安装 (推荐)

4. 🛠️ 进阶配置：Custom Patch (长期稳定之选)

5. 🧰 万象工具箱 (PC 端神器)

6. 📜 第三方更新脚本

7. 🌿 东风破 (Plum) 管理器

基础版（完整）

基础版（仅词库）

自然码辅助版（完整）

自然码辅助版（仅词库）

墨奇辅助版（完整）

墨奇辅助版（仅词库）

小鹤辅助版（完整）

小鹤辅助版（仅词库）

虎码辅助版（完整）

虎码辅助版（仅词库）

五笔辅助版（完整）

五笔辅助版（仅词库）

汉心辅助版（完整）

汉心辅助版（仅词库）

首右辅助版（完整）

首右辅助版（仅词库）

8. 📂 自定义扩展-线上数据获取

9. 📂 数据管理

答疑

功能一览

辅助码系统

其他亮点功能

🛠️ Super Replacer 参数配置手册

1. 核心全局参数

2. 任务项配置 (types)

3. 四大模式 (mode) 详解

4. 数据文件 (.txt) 编写规范

固定词库：

用户词库迁移：

生态

鸣谢

2. 任务项配置 (`types`)

3. 四大模式 (`mode`) 详解

4. 数据文件 (`.txt`) 编写规范