GitHub Lua Monthly Trending

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

iDvel/rime-ice

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

雾凇拼音

雾凇拼音是一份开箱即用的简体中文 Rime 输入法配置，词库长期维护，基本功能齐全，使用完全离线，质量稳定可靠。

雾凇拼音包含全拼和双拼输入方案、长期维护的精校词库、各类扩展功能和详尽的注释。适配小狼毫 Weasel、鼠须管 Squirrel、Fcitx5、iBus 等几乎所有 Rime 前端。你可以不折腾，一键下载部署后即刻使用；可以借着完善的注释和社区生态，让 AI 帮你定制改造；也可以将之作为深入了解和自定义 Rime 的起点。

使用雾凇拼音，享受跨平台一致、隐私友好、个性化门槛低的 Rime 简体中文输入体验。

安装

到 Rime 官网或 app 商店下载安装 Rime 输入法应用。然后：

下载雾凇拼音压缩包；
先清空^[2]输入法 用户文件夹/用户设定 内的全部文件，再将压缩包内的所有文件复制进去；
重新部署。

部署完成后就可以打字了。按 F4 可以切换输入方案或开关各项功能。重做以上三步可以更新/还原雾凇拼音。

也可以使用 /plum/ ℞ 配方管理工具，一行命令就能安装和更新雾凇拼音：

bash rime-install iDvel/rime-ice

了解更多细节以及其他支持的安装方式，参考详细安装指导。

介绍

雾凇拼音包含：

为简体中文设计的全拼和常见双拼方案，包括雾凇拼音（全拼）、智能 ABC、自然码、小鹤双拼、搜狗双拼、微软双拼、紫光双拼、拼音加加、9 键^[3] 和轻量的英文方案。
长期维护、精心调教且开源的百万中英词库：了解 >
完善的基础输入体验，以及丰富的扩展功能：了解 >
对 Rime 部分及主流前端每一项配置的详细注释，方便学习和自定义：示例 >

长期维护的中英词库

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

词库简介：

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

维护内容主要是异形词、错别字的校对，错误注音的修正，缺失的常用词汇的增添，词频的调整。欢迎在词库方面提 issue，我会及时更新修正。

功能演示和使用教程

—— ⌨️ 基础输入 ⌨️ ——

1. 方案选单	2. 中文输入

3. 英文输入	4. 中英混合输入

5. Emoji	6. 模糊音

7. 自动纠错	8. 繁简转换

—— 🔍 反查和符号 🔍 ——

1. 拆字反查	2. 数字符号转写

碰到生僻字，输入 `uU` + 字的部件拼音，得到汉字和注音	用拼音、英文输入短语中的数字和符号

3. 符号输入	4. 词汇别名

全拼 `v` + 拼音首字母；双拼 `V` + 拼音首字母	部分常用词，自动展示其翻译、别名、化学式、简称等

—— ✨ 扩展功能 ✨ ——

1. 以词定字	2. 辅码检字

用左右中括号键，输入候选的开头或末尾的字	输入拼音后，再输入 ` + 字的偏旁部首拼音，筛选候选

3. 错字错音提示	4. 英文自动大小写

输了错字错音，雾凇会提示正确的音形	大写开头，得到首字母大写的单词；多个大写字母开头，得到全大写的单词

5. 日期输入	6. 农历输入

全拼输 `rq`，双拼输 `date`，得到各种格式的当前日期和时间	全拼输 `nl`，双拼输 `lunar`，获取当前农历；输入 `N` + 日期，获取指定日期农历和节气

—— 🧰 便捷工具 🧰 ——

1. 计算器	2. Unicode 输入

输入 `cC` 后加上算式，得到计算结果	输入 `U` + Unicode 编码，得到对应字符

3. UUID 生成	4. 数字货币转写

输入 `uuid`，得到一个随机生成的 UUID	输入 `R` + 数字，自动转写为数字大写或者人民币大写

功能快捷键和行为定制，以及更多其他功能，请参考 lua 文件和方案文件中的注释。

鸣谢

这些项目和脚本为雾凇拼音提供的支持和参考。
校对标准论坛的存在。
@Huandeep 整理的多个词库。
@Mirtle 完善的多个功能。
@Lithium-7 对词库的大量修订。

Thanks to JetBrains for the OSS development license.

Thanks to all contributors.

常见问题

🛠️ 怎么修改雾凇拼音的配置

可以根据注释，直接在文件上修改，这样修改也简单，适合初次尝试。但注意，这会在更新后被覆盖掉。

熟悉后，推荐使用打补丁的方式来覆盖原配置的选项，不修改仓库中已有的文件，这样可放心全量拉取更新，通过 plum 或 git pull 时不用担心由于更新文件导致自定义的配置被覆盖。

⌨️ 双拼怎么添加自定义短语，怎么让拆字/英文的编码支持双拼

相对于全拼，双拼的一些配置有所不同：

双拼的自定义短语文件默认为 custom_phrase_double.txt，需要手动创建。
英文方案 melt_eng.schema.yaml 中有一些不通用的派生规则，默认启用的是全拼的。
部件拆字方案 radical_pinyin.schema.yaml 的反查和辅码，有一些不通用的派生规则，默认启用的是全拼的。
双拼是显示全拼编码还是双拼编码？比如小鹤双拼输入 zz 时，是显示 zz 还是 zou，默认是转换为全拼编码。translator 下的 preedit_format 属性会影响输入框和 Shift+回车时的显示，删除这部分就不转换。

双拼可以直接用 plum 自动打补丁，也可以手写，下面以小鹤双拼方案 double_pinyin_flypy.schema.yaml 为例。

（补丁放到仓库里了 others/双拼补丁示例）

创建 melt_eng.custom.yaml 修改英文派生规则：

patch:
  # 修改为小鹤双拼的拼写派生规则，因为不在同一个文件了，前面要加上文件名
  speller/algebra:
    __include: melt_eng.schema.yaml:/algebra_flypy

创建 radical_pinyin.custom.yaml 修改反查及辅码派生规则：

patch:
  # 修改为小鹤双拼的拼写派生规则，因为不在同一个文件了，前面要加上文件名
  speller/algebra:
    __include: radical_pinyin.schema.yaml:/algebra_flypy

（按需选择）创建 double_pinyin_flypy.custom.yaml：

patch:
  # （按需选择）清空 preedit_format 中的内容，输入时显示双拼编码
  translator/preedit_format: []

🔀 能实现全拼双拼混输吗

参考：https://dvel.me/posts/rime-full-pinyin-double-pinyin-mixed-input/

🚫 xx 字打不出来 / xx 读音没有

可能为生僻字，请尝试开启大字表。若确实为常用字（如常见于人名、物品名、术语），请 PR 或在 https://github.com/iDvel/rime-ice/issues/666 补充。

🔲 部分候选项变成豆腐块、方块、问号

系统缺少相关字体导致。请尝试下载或更换显示字体。

关于部分生僻字，参考 https://github.com/iDvel/rime-ice/issues/841 的推荐。

Windows 10 平台部分 Emoji 用系统默认字体无法显示，请尝试下载 Noto Color Emoji 或用 Windows 11 Emoji 字体替换。

⚠️ 部署失败或者报错

如果缩进错误，或用了 Tab，可能部署时并不会报错，而是自动加载默认配置。

如果发现方案选单里是朙月拼音，打的是繁体，那可能是配置有问题，Rime 自动加载了默认配置，检查一下修改过的地方。

配置错误也可能导致 default.yaml 文件被移入 trash/ 目录，你需要移动回来，改好后重新部署，然后可以直接删除 trash/ 目录。

🔄 中英文、大小写切换行为如何修改

Shift 是否切换中英，切换时的行为等等，参考 default.yaml 中 ascii_composer 下的详细注释。

📝 怎么修改标点符号映射

标点符号相关配置在 default.yaml 中定义，再在多个方案中引用。

修改 default.yaml 或在 default.custom.yaml 中打补丁即可全局修改。

🎨 怎么设置皮肤横向竖向排列

皮肤配置不通用，要参考各前端自己的配置方式。

小狼毫由 style/horizontal 属性决定：

patch:
  "style/horizontal": true  # true 横向 | false 竖向

鼠须管的 horizontal 属性已经弃用，在 squirrel.yaml 皮肤的选项中使用以下两个属性：

preset_color_schemes:
  皮肤名:
    candidate_list_layout: stacked  # stacked | linear  候选项排列方向
    text_orientation: horizontal    # horizontal | vertical  文字排列方向

⚠️ 注意具体皮肤的优先级比 style 的高。

鼠须管效果展示：

📌 怎么自定义短语

自定义短语用 Tab 分割词汇、编码、权重。

custom_phrase.txt 中是我自己的习惯，仅供参考，这个每个人的习惯都不一样，可以换成自己的。

可以新建一个文件，并在方案的 custom_phrase/user_dict: 下指定使用哪个文件。

💱 怎么设置台湾繁体

默认 OpenCC 的选项 traditionalize/opencc_config: s2t.json 是香港繁体。

台湾繁体有以下两种方式供参考，先修改为 s2tw.json：

参考 https://github.com/iDvel/rime-ice/issues/291，修改 opencc
参考 https://github.com/iDvel/rime-ice/issues/575，补加一个 t2tw （因为不知道什么原因，s2tw.json 选项并没有真正转换为台湾繁体，所以又补了一个 t2tw.json）（librime 1.10 已修复，新版本不再需要折腾了。）

😀 可以支持颜文字吗？

没有加入颜文字，可参考 https://github.com/iDvel/rime-ice/pull/920。

🐧 Linux 系统无候选 & 雾凇拼音候选后出现拼音注释等

输入 rq（双拼是 date），如若没有出现当前日期，则表示 Lua 没有成功加载，您就可能遇到上述问题。

请确保你已经正确安装了 librime 包，并以插件或其他形式安装了其依赖包 librime-lua（部分发行版——特别是红帽系——需要手动安装）；如果仍存在问题，或者你无法判断是否达成此条件，请：

若使用 fcitx 框架，请改用其继承者 fcitx5；若使用 fcitx5 框架，请保证安装的是 fcitx5-rime 而非 ~~fcitx-rime~~
若使用 ibus 框架，出现意外，可以考虑使用 AppImage，以跟进 librime 更新
若使用 fcitx5 框架，出现意外，请考虑使用 Flatpak，参考 Fcitx5 官方 wiki

AppImage 和 Flatpak 可以确保没有依赖问题。

请参考：https://github.com/iDvel/rime-ice/issues/840

🐧 Linux Fcitx5 首次安装雾凇拼音后，无法输入

请尝试修改任意 yaml 文件，再重新部署 Rime，不要仅依赖重启输入法框架。

请参考 https://github.com/iDvel/rime-ice/issues/1439

🌙 怎么添加或修改 Lua？

做好自己的 Lua 放在 lua/ 文件夹内，使用新版 librime-lua 引入模块的方式，不用修改 rime.lua：

- lua_translator@*my_translator  # 多了一个星号

比如想将自己修改后的 new_date_translator.lua 替换掉 date_translator：

# 方式一、复制完整的 translators 的内容过来
patch:
  engine/translators:
    # 。。。
    - lua_translator@*new_date_translator  # 将此处替换为自己的 Lua
    # 。。。

# 方式二、仅替换修改项，但依赖于原始排序（从 0 开始数），如果排序变动就替换错了
patch:
  engine/translators/@2: lua_translator@*new_date_translator

📋 我看到了日志里面的 WARNING

WARNING 日志仅为警告，一般可以忽视。ERROR 文件若有日志，则需要留神。

accessing blocking node with unresolved dependencies:

这是因为 melt_eng 和 radical_pinyin 引用了自身的节点，RIME build 时认为这可能会导致引用了一个未编译完成的文件，因而抛出警告。无视即可。

duplicate definition:

因为某些词典有重复的条目，build 时 RIME 认为这可能会造成编码和权重的覆写，因而抛出警告，无视即可。

许可证

GPL-3.0 (only) License.

赞助

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

由 @Mintimate 友情构建 ↩︎
这将清空你之前的用户偏好和词库，如需要，请先备份 ↩︎
九键方案仅适用于 iOS 平台的特定软件 ↩︎

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

nvim-lua/kickstart.nvim

A launch point for your personal nvim configuration

kickstart.nvim

Introduction

A starting point for Neovim that is:

Small
Single-file
Completely Documented

NOT a Neovim distribution, but instead a starting point for your configuration.

Installation

Install Neovim

Kickstart.nvim targets only the latest 'stable' and latest 'nightly' of Neovim. If you are experiencing issues, please make sure you have at least the latest stable version. Most likely, you want to install neovim via a package manager. To check your neovim version, run nvim --version and make sure it is not below the latest 'stable' version. If your chosen install method only gives you an outdated version of neovim, find alternative installation methods below.

Install External Dependencies

External Requirements:

Basic utils: git, make, unzip, C Compiler (gcc)
ripgrep, fd-find
tree-sitter CLI
Clipboard tool (xclip/xsel/win32yank or other depending on the platform)
A Nerd Font: optional, provides various icons
- if you have it set vim.g.have_nerd_font in init.lua to true
Emoji fonts (Ubuntu only, and only if you want emoji!) sudo apt install fonts-noto-color-emoji
Language Setup:
- If you want to write Typescript, you need npm
- If you want to write Golang, you will need go
- etc.

Note

See Install Recipes for additional Windows and Linux specific notes and quick install snippets

Install Kickstart

Note

Backup your previous configuration (if any exists)

Neovim's configurations are located under the following paths, depending on your OS:

OS	PATH
Linux, MacOS	`$XDG_CONFIG_HOME/nvim`, `~/.config/nvim`
Windows (cmd)	`%localappdata%\nvim\`
Windows (powershell)	`$env:LOCALAPPDATA\nvim\`

Recommended Step

Fork this repo so that you have your own copy that you can modify, then install by cloning the fork to your machine using one of the commands below, depending on your OS.

Note

Your fork's URL will be something like this: https://github.com/<your_github_username>/kickstart.nvim.git

You likely want to remove nvim-pack-lock.json from your fork's .gitignore file too - it's ignored in the kickstart repo to make maintenance easier, but it's recommended to track it in version control (see :help vim.pack-lockfile).

Clone kickstart.nvim

Note

If following the recommended step above (i.e., forking the repo), replace nvim-lua with <your_github_username> in the commands below

Linux and Mac

git clone https://github.com/nvim-lua/kickstart.nvim.git "${XDG_CONFIG_HOME:-$HOME/.config}"/nvim

Windows

If you're using cmd.exe:

git clone https://github.com/nvim-lua/kickstart.nvim.git "%localappdata%\nvim"

If you're using powershell.exe

git clone https://github.com/nvim-lua/kickstart.nvim.git "${env:LOCALAPPDATA}\nvim"

Post Installation

Start Neovim

nvim

That's it! vim.pack will install all the plugins from your config. Use :lua vim.pack.update(nil, { offline = true }) to inspect plugin state and :lua vim.pack.update() to fetch updates (:write applies updates, :quit cancels them).

Read The Friendly Documentation

Read through the init.lua file in your configuration folder for more information about extending and exploring Neovim. That also includes examples of adding popularly requested plugins.

Note

For more information about a particular plugin check its repository's documentation.

Getting Started

The Only Video You Need to Get Started with Neovim

FAQ

What should I do if I already have a pre-existing Neovim configuration?
- You should back it up and then delete all associated files.
- This includes your existing init.lua and the Neovim files in ~/.local which can be deleted with rm -rf ~/.local/share/nvim/
Can I keep my existing configuration in parallel to kickstart?
- Yes! You can use NVIM_APPNAME=nvim-NAME to maintain multiple configurations. For example, you can install the kickstart configuration in ~/.config/nvim-kickstart and create an alias:
```
alias nvim-kickstart='NVIM_APPNAME="nvim-kickstart" nvim'
```
  When you run Neovim using nvim-kickstart alias it will use the alternative config directory and the matching local directory ~/.local/share/nvim-kickstart. You can apply this approach to any Neovim distribution that you would like to try out.
What if I want to "uninstall" this configuration:
- Remove your config directory and local data directory (for example, ~/.config/nvim and ~/.local/share/nvim).
Why is the kickstart init.lua a single file? Wouldn't it make sense to split it into multiple files?
- The main purpose of kickstart is to serve as a teaching tool and a reference configuration that someone can easily use to git clone as a basis for their own. As you progress in learning Neovim and Lua, you might consider splitting init.lua into smaller parts. A fork of kickstart that does this while maintaining the same functionality is available here:
  - kickstart-modular.nvim
- Discussions on this topic can be found here:
  - Restructure the configuration
  - Reorganize init.lua into a multi-file setup

Install Recipes

Below you can find OS specific install instructions for Neovim and dependencies.

After installing all the dependencies continue with the Install Kickstart step.

Windows Installation

Windows with Microsoft C++ Build Tools and CMake

Kickstart's default config is make-only for `telescope-fzf-native.nvim`. If `make` is unavailable, the plugin is skipped.

Recommended: install make (see the chocolatey section below).

If you want a CMake-only setup, customize init.lua in two places:

Include telescope-fzf-native.nvim when cmake is available:

if vim.fn.executable 'make' == 1 or vim.fn.executable 'cmake' == 1 then
  table.insert(plugins, gh 'nvim-telescope/telescope-fzf-native.nvim')
end

In the PackChanged hook, use CMake when make is unavailable:

if name == 'telescope-fzf-native.nvim' then
  if vim.fn.executable 'make' == 1 then
    run_build(name, { 'make' }, ev.data.path)
  elseif vim.fn.executable 'cmake' == 1 then
    run_build(name, { 'cmake', '-S.', '-Bbuild', '-DCMAKE_BUILD_TYPE=Release' }, ev.data.path)
    run_build(name, { 'cmake', '--build', 'build', '--config', 'Release', '--target', 'install' }, ev.data.path)
  end
  return
end

See telescope-fzf-native documentation for build details.

Windows with gcc/make using chocolatey

Alternatively, one can install gcc and make which don't require changing the config, the easiest way is to use choco:

install chocolatey either follow the instructions on the page or use winget, run in cmd as admin:

winget install --accept-source-agreements chocolatey.chocolatey

install all requirements using choco, exit the previous cmd and open a new one so that choco path is set, and run in cmd as admin:

choco install -y neovim git ripgrep wget fd unzip gzip mingw make tree-sitter

WSL (Windows Subsystem for Linux)

wsl --install
wsl
sudo add-apt-repository ppa:neovim-ppa/unstable -y
sudo apt update
sudo apt install make gcc ripgrep fd-find tree-sitter-cli unzip git xclip neovim

Linux Install

Ubuntu Install Steps

sudo add-apt-repository ppa:neovim-ppa/unstable -y
sudo apt update
sudo apt install make gcc ripgrep fd-find tree-sitter-cli unzip git xclip neovim

Debian Install Steps

sudo apt update
sudo apt install make gcc ripgrep fd-find tree-sitter-cli unzip git xclip curl

# Now we install nvim
curl -LO https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.tar.gz
sudo rm -rf /opt/nvim-linux-x86_64
sudo mkdir -p /opt/nvim-linux-x86_64
sudo chmod a+rX /opt/nvim-linux-x86_64
sudo tar -C /opt -xzf nvim-linux-x86_64.tar.gz

# make it available in /usr/local/bin, distro installs to /usr/bin
sudo ln -sf /opt/nvim-linux-x86_64/bin/nvim /usr/local/bin/

Fedora Install Steps

sudo dnf install -y gcc make git ripgrep fd-find tree-sitter-cli unzip neovim

Arch Install Steps

sudo pacman -S --noconfirm --needed gcc make git ripgrep fd tree-sitter-cli unzip neovim

Alternative neovim installation methods

For some systems it is not unexpected that the package manager installation method recommended by neovim is significantly behind. If that is the case for you, pick one of the following methods that are known to deliver fresh neovim versions very quickly. They have been picked for their popularity and because they make installing and updating neovim to the latest versions easy. You can also find more detail about the available methods being discussed here.

Bob

Bob is a Neovim version manager for all platforms. Simply install rustup, and run the following commands:

rustup default stable
rustup update stable
cargo install bob-nvim
bob use stable

Homebrew

Homebrew is a package manager popular on Mac and Linux. Simply install using brew install.

Flatpak

Flatpak is a package manager for applications that allows developers to package their applications just once to make it available on all Linux systems. Simply install flatpak and setup flathub to install neovim.

asdf and mise-en-place

asdf and mise are tool version managers, mostly aimed towards project-specific tool versioning. However both support managing tools globally in the user-space as well:

mise

Install mise, then run:

mise plugins install neovim
mise use neovim@stable

asdf

Install asdf, then run:

asdf plugin add neovim
asdf install neovim stable
asdf set neovim stable --home
asdf reshim neovim

NeogitOrg/neogit

An interactive and powerful Git interface for Neovim, inspired by Magit

Neogit

A git interface for Neovim, inspired by Magit.

Installation

Here's an example spec for Lazy, but you're free to use whichever plugin manager suits you.

{
  "NeogitOrg/neogit",
  lazy = true,
  dependencies = {
    -- Only one of these is needed.
    "sindrets/diffview.nvim",        -- optional
    "esmuellert/codediff.nvim",      -- optional

    -- For a custom log pager
    "m00qek/baleia.nvim",            -- optional

    -- Only one of these is needed.
    "nvim-telescope/telescope.nvim", -- optional
    "ibhagwan/fzf-lua",              -- optional
    "nvim-mini/mini.pick",           -- optional
    "folke/snacks.nvim",             -- optional
  },
  cmd = "Neogit",
  keys = {
    { "<leader>gg", "<cmd>Neogit<cr>", desc = "Show Neogit UI" }
  }
}

Usage

You can either open Neogit by using the Neogit command:

:Neogit             " Open the status buffer in a new tab
:Neogit cwd=<cwd>   " Use a different repository path
:Neogit cwd=%:p:h   " Uses the repository of the current file
:Neogit kind=<kind> " Open specified popup directly
:Neogit commit      " Open commit popup

" Map it to a key
nnoremap <leader>gg <cmd>Neogit<cr>

-- Or via lua api
vim.keymap.set("n", "<leader>gg", "<cmd>Neogit<cr>", { desc = "Open Neogit UI" })

Or using the lua api:

local neogit = require('neogit')

-- open using defaults
neogit.open()

-- open a specific popup
neogit.open({ "commit" })

-- open as a split
neogit.open({ kind = "split" })

-- open with different project
neogit.open({ cwd = "~" })

-- You can map this to a key
vim.keymap.set("n", "<leader>gg", neogit.open, { desc = "Open Neogit UI" })

-- Wrap in a function to pass additional arguments
vim.keymap.set(
    "n",
    "<leader>gg",
    function() neogit.open({ kind = "split" }) end,
    { desc = "Open Neogit UI" }
)

The kind option can be one of the following values:

tab (default)
replace
split
split_above
split_above_all
split_below
split_below_all
vsplit
floating
auto (vsplit if window would have 80 cols, otherwise split)

Configuration

You can configure neogit by running the require('neogit').setup {} function, passing a table as the argument.

Default Config

local neogit = require("neogit")

neogit.setup {
  -- Use Treesitter to apply syntax highlighting to diff hunks
  treesitter_diff_highlight = true,
  -- Apply word-diff highlights to diff hunks
  word_diff_highlight = true,
  -- Hides the hints at the top of the status buffer
  disable_hint = false,
  -- Disables changing the buffer highlights based on where the cursor is.
  disable_context_highlighting = false,
  -- Disables signs for sections/items/hunks
  disable_signs = false,
  -- Path to git executable. Defaults to "git". Can be used to specify a custom git binary or wrapper script.
  git_executable = "git",
  -- Offer to force push when branches diverge
  prompt_force_push = true,
  -- Request confirmation when amending already published commits
  prompt_amend_commit = true,
  -- Changes what mode the Commit Editor starts in. `true` will leave nvim in normal mode, `false` will change nvim to
  -- insert mode, and `"auto"` will change nvim to insert mode IF the commit message is empty, otherwise leaving it in
  -- normal mode.
  disable_insert_on_commit = "auto",
  -- When enabled, will watch the `.git/` directory for changes and refresh the status buffer in response to filesystem
  -- events.
  filewatcher = {
    interval = 1000,
    enabled = true,
  },
  -- "ascii"   is the graph the git CLI generates
  -- "unicode" is the graph like https://github.com/rbong/vim-flog
  -- "kitty"   is the graph like https://github.com/isakbm/gitgraph.nvim - use https://github.com/rbong/flog-symbols if you don't use Kitty
  graph_style = "ascii",
  -- Show relative date by default. When set, use `strftime` to display dates
  commit_date_format = nil,
  log_date_format = nil,
  -- When set, used to format the diff. Requires *baleia* to colorize text with ANSI escape sequences. An example for `Delta` is `{ 'delta', '--width', '117' }`. For `Delta`, hyperlinks must be disabled when called by `neogit`, for text to be colorized properly.
  log_pager = nil,
  -- Show message with spinning animation when a git command is running.
  process_spinner = false,
  -- Used to generate URL's for branch popup action "pull request", "open commit" and "open tree"
  git_services = {
    ["github.com"] = {
      pull_request = "https://github.com/${owner}/${repository}/compare/${branch_name}?expand=1",
      commit = "https://github.com/${owner}/${repository}/commit/${oid}",
      tree = "https://${host}/${owner}/${repository}/tree/${branch_name}",
    },
    ["bitbucket.org"] = {
      pull_request = "https://bitbucket.org/${owner}/${repository}/pull-requests/new?source=${branch_name}&t=1",
      commit = "https://bitbucket.org/${owner}/${repository}/commits/${oid}",
      tree = "https://bitbucket.org/${owner}/${repository}/branch/${branch_name}",
    },
    ["gitlab.com"] = {
      pull_request = "https://gitlab.com/${owner}/${repository}/merge_requests/new?merge_request[source_branch]=${branch_name}",
      commit = "https://gitlab.com/${owner}/${repository}/-/commit/${oid}",
      tree = "https://gitlab.com/${owner}/${repository}/-/tree/${branch_name}?ref_type=heads",
    },
    ["azure.com"] = {
      pull_request = "https://dev.azure.com/${owner}/_git/${repository}/pullrequestcreate?sourceRef=${branch_name}&targetRef=${target}",
      commit = "",
      tree = "",
    },
    ["codeberg.org"] = {
      pull_request = "https://${host}/${owner}/${repository}/compare/${branch_name}",
      commit = "https://${host}/${owner}/${repository}/commit/${oid}",
      tree = "https://${host}/${owner}/${repository}/src/branch/${branch_name}",
    },
  },
  -- Allows a different telescope sorter. Defaults to 'fuzzy_with_index_bias'. The example below will use the native fzf
  -- sorter instead. By default, this function returns `nil`.
  telescope_sorter = function()
    return require("telescope").extensions.fzf.native_fzf_sorter()
  end,
  -- Persist the values of switches/options within and across sessions
  remember_settings = true,
  -- Scope persisted settings on a per-project basis
  use_per_project_settings = true,
  -- Table of settings to never persist. Uses format "Filetype--cli-value"
  ignored_settings = {},
  -- Configure highlight group features
  highlight = {
    italic = true,
    bold = true,
    underline = true
  },
  -- Set to false if you want to be responsible for creating _ALL_ keymappings
  use_default_keymaps = true,
  -- Neogit refreshes its internal state after specific events, which can be expensive depending on the repository size.
  -- Disabling `auto_refresh` will make it so you have to manually refresh the status after you open it.
  auto_refresh = true,
  -- Value used for `--sort` option for `git branch` command
  -- By default, branches will be sorted by commit date descending
  -- Flag description: https://git-scm.com/docs/git-branch#Documentation/git-branch.txt---sortltkeygt
  -- Sorting keys: https://git-scm.com/docs/git-for-each-ref#_options
  sort_branches = "-committerdate",
  -- Value passed to the `--<commit_order>-order` flag of the `git log` command
  -- Determines how commits are traversed and displayed in the log / graph:
  --   "topo"         topological order (parents always before children, good for graphs, slower on large repos)
  --   "date"         chronological order by commit date
  --   "author-date"  chronological order by author date
  --   ""             disable explicit ordering (fastest, recommended for very large repos)
  commit_order = "topo",
  -- Default for new branch name prompts
  initial_branch_name = "",
  -- Default for rename branch prompt. If not set, the current branch name is used
  initial_branch_rename = nil,
  -- Change the default way of opening neogit
  kind = "tab",
  -- Floating window style 
  floating = {
    relative = "editor",
    width = 0.8,
    height = 0.7,
    style = "minimal",
    border = "rounded",
  },
  -- Disable line numbers
  disable_line_numbers = true,
  -- Disable relative line numbers
  disable_relative_line_numbers = true,
  -- The time after which an output console is shown for slow running commands
  console_timeout = 2000,
  -- Automatically show console if a command takes more than console_timeout milliseconds
  auto_show_console = true,
  -- Automatically close the console if the process exits with a 0 (success) status
  auto_close_console = true,
  notification_icon = "󰊢",
  status = {
    show_head_commit_hash = true,
    recent_commit_count = 10,
    HEAD_padding = 10,
    HEAD_folded = false,
    mode_padding = 3,
    mode_text = {
      M = "modified",
      N = "new file",
      A = "added",
      D = "deleted",
      C = "copied",
      U = "updated",
      R = "renamed",
      T = "changed",
      DD = "unmerged",
      AU = "unmerged",
      UD = "unmerged",
      UA = "unmerged",
      DU = "unmerged",
      AA = "unmerged",
      UU = "unmerged",
      ["?"] = "",
    },
  },
  commit_editor = {
    kind = "tab",
    show_staged_diff = true,
    -- Accepted values:
    -- "split" to show the staged diff below the commit editor
    -- "vsplit" to show it to the right
    -- "split_above" Like :top split
    -- "vsplit_left" like :vsplit, but open to the left
    -- "auto" "vsplit" if window would have 80 cols, otherwise "split"
    staged_diff_split_kind = "split",
    spell_check = true,
  },
  commit_select_view = {
    kind = "tab",
  },
  commit_view = {
    kind = "vsplit",
    verify_commit = vim.fn.executable("gpg") == 1, -- Can be set to true or false, otherwise we try to find the binary
  },
  log_view = {
    kind = "tab",
  },
  rebase_editor = {
    kind = "auto",
  },
  reflog_view = {
    kind = "tab",
  },
  merge_editor = {
    kind = "auto",
  },
  preview_buffer = {
    kind = "floating_console",
  },
  popup = {
    kind = "split",
    show_title = false,
  },
  stash = {
    kind = "tab",
  },
  refs_view = {
    kind = "tab",
  },
  signs = {
    -- { CLOSED, OPENED }
    hunk = { "", "" },
    item = { ">", "v" },
    section = { ">", "v" },
  },
  -- Each Integration is auto-detected through plugin presence, however, it can be disabled by setting to `false`
  integrations = {
    -- If enabled, use telescope for menu selection rather than vim.ui.select.
    -- Allows multi-select and some things that vim.ui.select doesn't.
    telescope = nil,
    -- Neogit only provides inline diffs. If you want a more traditional way to look at diffs, you can use `diffview`.
    -- The diffview integration enables the diff popup.
    --
    -- Requires you to have `sindrets/diffview.nvim` installed.
    diffview = nil,

    -- Alternative diff viewer integration.
    -- Requires you to have `esmuellert/codediff.nvim` installed.
    codediff = nil,

    -- If enabled, uses fzf-lua for menu selection. If the telescope integration
    -- is also selected then telescope is used instead
    -- Requires you to have `ibhagwan/fzf-lua` installed.
    fzf_lua = nil,

    -- If enabled, uses mini.pick for menu selection. If the telescope integration
    -- is also selected then telescope is used instead
    -- Requires you to have `echasnovski/mini.pick` installed.
    mini_pick = nil,

    -- If enabled, uses snacks.picker for menu selection. If the telescope integration
    -- is also selected then telescope is used instead
    -- Requires you to have `folke/snacks.nvim` installed.
    snacks = nil,
  },
  -- Which diff viewer to use. nil = auto-detect (tries diffview first, then codediff).
  -- Can be "diffview" or "codediff".
  diff_viewer = nil,
  sections = {
    -- Reverting/Cherry Picking
    sequencer = {
      folded = false,
      hidden = false,
    },
    untracked = {
      folded = false,
      hidden = false,
    },
    unstaged = {
      folded = false,
      hidden = false,
    },
    staged = {
      folded = false,
      hidden = false,
    },
    stashes = {
      folded = true,
      hidden = false,
    },
    unpulled_upstream = {
      folded = true,
      hidden = false,
    },
    unmerged_upstream = {
      folded = false,
      hidden = false,
    },
    unpulled_pushRemote = {
      folded = true,
      hidden = false,
    },
    unmerged_pushRemote = {
      folded = false,
      hidden = false,
    },
    recent = {
      folded = true,
      hidden = false,
    },
    rebase = {
      folded = true,
      hidden = false,
    },
  },
  mappings = {
    commit_editor = {
      ["q"] = "Close",
      ["<c-c><c-c>"] = "Submit",
      ["<c-c><c-k>"] = "Abort",
      ["<m-p>"] = "PrevMessage",
      ["<m-n>"] = "NextMessage",
      ["<m-r>"] = "ResetMessage",
    },
    commit_editor_I = {
      ["<c-c><c-c>"] = "Submit",
      ["<c-c><c-k>"] = "Abort",
    },
    rebase_editor = {
      ["p"] = "Pick",
      ["r"] = "Reword",
      ["e"] = "Edit",
      ["s"] = "Squash",
      ["f"] = "Fixup",
      ["x"] = "Execute",
      ["d"] = "Drop",
      ["b"] = "Break",
      ["q"] = "Close",
      ["<cr>"] = "OpenCommit",
      ["gk"] = "MoveUp",
      ["gj"] = "MoveDown",
      ["<c-c><c-c>"] = "Submit",
      ["<c-c><c-k>"] = "Abort",
      ["[c"] = "OpenOrScrollUp",
      ["]c"] = "OpenOrScrollDown",
    },
    rebase_editor_I = {
      ["<c-c><c-c>"] = "Submit",
      ["<c-c><c-k>"] = "Abort",
    },
    finder = {
      ["<cr>"] = "Select",
      ["<c-c>"] = "Close",
      ["<esc>"] = "Close",
      ["<c-n>"] = "Next",
      ["<c-p>"] = "Previous",
      ["<down>"] = "Next",
      ["<up>"] = "Previous",
      ["<tab>"] = "InsertCompletion",
      ["<c-y>"] = "CopySelection",
      ["<space>"] = "MultiselectToggleNext",
      ["<s-space>"] = "MultiselectTogglePrevious",
      ["<c-j>"] = "NOP",
      ["<ScrollWheelDown>"] = "ScrollWheelDown",
      ["<ScrollWheelUp>"] = "ScrollWheelUp",
      ["<ScrollWheelLeft>"] = "NOP",
      ["<ScrollWheelRight>"] = "NOP",
      ["<LeftMouse>"] = "MouseClick",
      ["<2-LeftMouse>"] = "NOP",
    },
    -- Setting any of these to `false` will disable the mapping.
    popup = {
      ["?"] = "HelpPopup",
      ["A"] = "CherryPickPopup",
      ["d"] = "DiffPopup",
      ["M"] = "RemotePopup",
      ["P"] = "PushPopup",
      ["X"] = "ResetPopup",
      ["Z"] = "StashPopup",
      ["i"] = "IgnorePopup",
      ["t"] = "TagPopup",
      ["b"] = "BranchPopup",
      ["B"] = "BisectPopup",
      ["w"] = "WorktreePopup",
      ["c"] = "CommitPopup",
      ["f"] = "FetchPopup",
      ["l"] = "LogPopup",
      ["m"] = "MergePopup",
      ["p"] = "PullPopup",
      ["r"] = "RebasePopup",
      ["v"] = "RevertPopup",
    },
    status = {
      ["j"] = "MoveDown",
      ["k"] = "MoveUp",
      ["o"] = "OpenTree",
      ["q"] = "Close",
      ["I"] = "InitRepo",
      ["1"] = "Depth1",
      ["2"] = "Depth2",
      ["3"] = "Depth3",
      ["4"] = "Depth4",
      ["Q"] = "Command",
      ["<tab>"] = "Toggle",
      ["za"] = "Toggle",
      ["zo"] = "OpenFold",
      ["x"] = "Discard",
      ["s"] = "Stage",
      ["S"] = "StageUnstaged",
      ["<c-s>"] = "StageAll",
      ["u"] = "Unstage",
      ["K"] = "Untrack",
      ["U"] = "UnstageStaged",
      ["y"] = "ShowRefs",
      ["$"] = "CommandHistory",
      ["Y"] = "YankSelected",
      ["gp"] = "GoToParentRepo",
      ["<c-r>"] = "RefreshBuffer",
      ["<cr>"] = "GoToFile",
      ["<s-cr>"] = "PeekFile",
      ["<c-v>"] = "VSplitOpen",
      ["<c-x>"] = "SplitOpen",
      ["<c-t>"] = "TabOpen",
      ["{"] = "GoToPreviousHunkHeader",
      ["}"] = "GoToNextHunkHeader",
      ["[c"] = "OpenOrScrollUp",
      ["]c"] = "OpenOrScrollDown",
      ["<c-k>"] = "PeekUp",
      ["<c-j>"] = "PeekDown",
      ["<c-n>"] = "NextSection",
      ["<c-p>"] = "PreviousSection",
    },
  },
}

Popups

The following popup menus are available from all buffers:

Bisect
Branch + Branch Config
Cherry Pick
Commit
Diff
Fetch
Ignore
Log
Merge
Pull
Push
Rebase
Remote + Remote Config
Reset
Revert
Stash
Tag
Worktree

Many popups will use whatever is currently under the cursor or selected as input for an action. For example, to cherry-pick a range of commits from the log view, a linewise visual selection can be made, and using either apply or pick from the cherry-pick menu will use the selection.

This works for just about everything that has an object-ID in git, and if you find one that you think should work but doesn't, open an issue 😃

Highlight Groups

See the built-in documentation for a comprehensive list of highlight groups. If your theme doesn't style a particular group, we'll try our best to do a nice job.

Events

Neogit emits the following events:

Event	Description	Event Data
`NeogitStatusRefreshed`	Status has been reloaded	`{}`
`NeogitCommitComplete`	Commit has been created	`{}`
`NeogitPushComplete`	Push has completed	`{}`
`NeogitPullComplete`	Pull has completed	`{}`
`NeogitFetchComplete`	Fetch has completed	`{}`
`NeogitBranchCreate`	Branch was created, starting from `base`	`{ branch_name: string, base: string? }`
`NeogitBranchDelete`	Branch was deleted	`{ branch_name: string }`
`NeogitBranchCheckout`	Branch was checked out	`{ branch_name: string }`
`NeogitBranchReset`	Branch was reset to a commit/branch	`{ branch_name: string, resetting_to: string }`
`NeogitBranchRename`	Branch was renamed	`{ branch_name: string, new_name: string }`
`NeogitRebase`	A rebase finished	`{ commit: string, status: "ok"\|"conflict" }`
`NeogitReset`	A branch was reset to a certain commit	`{ commit: string, mode: "soft"\|"mixed"\|"hard"\|"keep"\|"index" }`
`NeogitTagCreate`	A tag was placed on a certain commit	`{ name: string, ref: string }`
`NeogitTagDelete`	A tag was removed	`{ name: string }`
`NeogitCherryPick`	One or more commits were cherry-picked	`{ commits: string[] }`
`NeogitMerge`	A merge finished	`{ branch: string, args = string[], status: "ok"\|"conflict" }`
`NeogitStash`	A stash finished	`{ success: boolean }`

Versioning

Neogit follows semantic versioning.

Compatibility

The master branch will always be compatible with the latest stable release of Neovim, and usually with the latest nightly build as well.

Contributing

See CONTRIBUTING.md for more details.

Contributors

Special Thanks

kolja for the Neogit Logo
gitgraph.nvim for the "kitty" git graph renderer
vim-flog for the "unicode" git graph renderer

MeanderingProgrammer/render-markdown.nvim

Improve viewing Markdown in Neovim

render-markdown.nvim

Improve viewing Markdown 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' },
        -- Number of lines from start/end to skip rendering background.
        background_inset = 1,
        -- 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',
        },
    },
    render = {
        -- Whether to render when window is in diff-mode.
        diff = false,
    },
    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 = '󱗖 ',
            -- Hide destination if there is an alias.
            conceal_destination = true,
            -- 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.
        -- | icon      | gets inlined before the link text                               |
        -- | pattern   | matched against the destination text                            |
        -- | kind      | optional determines how pattern is checked                      |
        -- |           | pattern | @see :h lua-patterns, is the default if not set       |
        -- |           | suffix  | @see :h vim.endswith()                                |
        -- |           | url     | similar to pattern with additional prefix checks      |
        -- | priority  | optional used when multiple match, uses pattern length if empty |
        -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
        -- stylua: ignore
        custom = {
            web = { icon = '󰖟 ', pattern = '^http' },
            apple = { icon = ' ', pattern = 'apple%.com', kind = 'url' },
            discord = { icon = '󰙯 ', pattern = 'discord%.com', kind = 'url' },
            github = { icon = '󰊤 ', pattern = 'github%.com', kind = 'url' },
            gitlab = { icon = '󰮠 ', pattern = 'gitlab%.com', kind = 'url' },
            google = { icon = '󰊭 ', pattern = 'google%.com', kind = 'url' },
            hackernews = { icon = ' ', pattern = 'ycombinator%.com', kind = 'url' },
            linkedin = { icon = '󰌻 ', pattern = 'linkedin%.com', kind = 'url' },
            microsoft = { icon = ' ', pattern = 'microsoft%.com', kind = 'url' },
            neovim = { icon = ' ', pattern = 'neovim%.io', kind = 'url' },
            reddit = { icon = '󰑍 ', pattern = 'reddit%.com', kind = 'url' },
            slack = { icon = '󰒱 ', pattern = 'slack%.com', kind = 'url' },
            stackoverflow = { icon = '󰓌 ', pattern = 'stackoverflow%.com', kind = 'url' },
            steam = { icon = ' ', pattern = 'steampowered%.com', kind = 'url' },
            twitter = { icon = ' ', pattern = 'twitter%.com', kind = 'url' },
            wikipedia = { icon = '󰖬 ', pattern = 'wikipedia%.org', kind = 'url' },
            x = { icon = ' ', pattern = 'x%.com', kind = 'url' },
            youtube = { icon = '󰗃 ', pattern = 'youtube[^.]*%.com', kind = 'url' },
            youtube_short = { icon = '󰗃 ', pattern = 'youtu%.be', kind = 'url' },
        },
    },
    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' },
        -- Number of lines from start/end to skip rendering background.
        background_inset = 1,
        -- 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 = '󱗖 ',
            -- Hide destination if there is an alias.
            conceal_destination = true,
            -- 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.
        -- | icon      | gets inlined before the link text                               |
        -- | pattern   | matched against the destination text                            |
        -- | kind      | optional determines how pattern is checked                      |
        -- |           | pattern | @see :h lua-patterns, is the default if not set       |
        -- |           | suffix  | @see :h vim.endswith()                                |
        -- |           | url     | similar to pattern with additional prefix checks      |
        -- | priority  | optional used when multiple match, uses pattern length if empty |
        -- | highlight | optional highlight for 'icon', uses fallback highlight if empty |
        -- stylua: ignore
        custom = {
            web = { icon = '󰖟 ', pattern = '^http' },
            apple = { icon = ' ', pattern = 'apple%.com', kind = 'url' },
            discord = { icon = '󰙯 ', pattern = 'discord%.com', kind = 'url' },
            github = { icon = '󰊤 ', pattern = 'github%.com', kind = 'url' },
            gitlab = { icon = '󰮠 ', pattern = 'gitlab%.com', kind = 'url' },
            google = { icon = '󰊭 ', pattern = 'google%.com', kind = 'url' },
            hackernews = { icon = ' ', pattern = 'ycombinator%.com', kind = 'url' },
            linkedin = { icon = '󰌻 ', pattern = 'linkedin%.com', kind = 'url' },
            microsoft = { icon = ' ', pattern = 'microsoft%.com', kind = 'url' },
            neovim = { icon = ' ', pattern = 'neovim%.io', kind = 'url' },
            reddit = { icon = '󰑍 ', pattern = 'reddit%.com', kind = 'url' },
            slack = { icon = '󰒱 ', pattern = 'slack%.com', kind = 'url' },
            stackoverflow = { icon = '󰓌 ', pattern = 'stackoverflow%.com', kind = 'url' },
            steam = { icon = ' ', pattern = 'steampowered%.com', kind = 'url' },
            twitter = { icon = ' ', pattern = 'twitter%.com', kind = 'url' },
            wikipedia = { icon = '󰖬 ', pattern = 'wikipedia%.org', kind = 'url' },
            x = { icon = ' ', pattern = 'x%.com', kind = 'url' },
            youtube = { icon = '󰗃 ', pattern = 'youtube[^.]*%.com', kind = 'url' },
            youtube_short = { icon = '󰗃 ', pattern = 'youtu%.be', kind = 'url' },
        },
    },
})

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 ↩︎

Kong/kong

🦍 The API and AI Gateway

Kong or Kong Gateway is a cloud-native, platform-agnostic, scalable API 𖧹 LLM 𖧹 MCP Gateway distinguished for its high performance and extensibility via plugins. It also provides advanced AI traffic capabilities with multi-LLM support, semantic security, MCP traffic security and analytics, and more.

By providing functionality for proxying, routing, load balancing, health checking, authentication (and more), Kong serves as the central layer for orchestrating microservices or conventional API traffic - and agentic LLM and MCP as well - with ease.

Kong runs natively on Kubernetes thanks to its official Kubernetes Ingress Controller.

Getting Started

If you prefer to use a cloud-hosted Kong, you can sign up for a free trial of Kong Konnect and get started in minutes. If not, you can follow the instructions below to get started with Kong on your own infrastructure.

Let’s test drive Kong by adding authentication to an API in under 5 minutes.

We suggest using the docker-compose distribution via the instructions below, but there is also a docker installation procedure if you’d prefer to run the Kong Gateway in DB-less mode.

Whether you’re running in the cloud, on bare metal, or using containers, you can find every supported distribution on our official installation page.

To start, clone the Docker repository and navigate to the compose folder.

  $ git clone https://github.com/Kong/docker-kong
  $ cd docker-kong/compose/

Start the Gateway stack using:

  $ KONG_DATABASE=postgres docker-compose --profile database up

The Gateway is now available on the following ports on localhost:

:8000 - send traffic to your service via Kong
:8001 - configure Kong using Admin API or via decK
:8002 - access Kong's management Web UI (Kong Manager) on localhost:8002

Next, follow the quick start guide to tour the Gateway features.

Getting started with AI Gateway for LLM and MCP

If you would like to get started with Kong AI Gateway capabilities including LLM and MCP features, please refer to the official AI documentation.

Features

By centralizing common API, AI and MCP functionality across all your organization's services, Kong Gateway creates more freedom for engineering teams to focus on the challenges that matter most.

The top Kong features include:

Advanced routing, load balancing, health checking - all configurable via a RESTful admin API or declarative configuration.
Authentication and authorization for APIs using methods like JWT, basic auth, OAuth, ACLs and more.
Universal LLM API to route across multiple providers like OpenAI, Anthropic, GCP Gemini, AWS Bedrock, Azure AI, Databricks, Mistral, Huggingface and more.
MCP traffic governance, MCP security and MCP observability in addition to MCP autogeneration from any RESTful API.
60+ AI features like AI observability, semantic security and caching, semantic routing and more.
Proxy, SSL/TLS termination, and connectivity support for L4 or L7 traffic.
Plugins for enforcing traffic controls, rate limiting, req/res transformations, logging, monitoring and including a plugin developer hub.
Sophisticated deployment models like Declarative Databaseless Deployment and Hybrid Deployment (control plane/data plane separation) without any vendor lock-in.
Native ingress controller support for serving Kubernetes.

Plugin Hub

Plugins provide advanced functionality that extends the use of the Gateway. Many of the Kong Inc. and community-developed plugins like AWS Lambda, Correlation ID, and Response Transformer are showcased at the Plugin Hub.

Contribute to the Plugin Hub and ensure your next innovative idea is published and available to the broader community!

Contributing

We ❤️ pull requests, and we’re continually working hard to make it as easy as possible for developers to contribute. Before beginning development with the Kong Gateway, please familiarize yourself with the following developer resources:

Community Pledge (COMMUNITY_PLEDGE.md) for our pledge to interact with you, the open source community.
Contributor Guide (CONTRIBUTING.md) to learn about how to contribute to Kong.
Development Guide (DEVELOPER.md): Setting up your development environment.
CODE_OF_CONDUCT and COPYRIGHT

Use the Plugin Development Guide for building new and creative plugins, or browse the online version of Kong's source code documentation in the Plugin Development Kit (PDK) Reference. Developers can build plugins in Lua, Go or JavaScript.

Releases

Please see the Changelog for more details about a given release. The SemVer Specification is followed when versioning Gateway releases.

Join the Community

Check out the docs
Join the Kong discussions forum
Join the Kong discussions at the Kong Nation forum: https://discuss.konghq.com/
Join our Community Slack
Read up on the latest happenings at our blog
Follow us on X
Subscribe to our YouTube channel
Visit our homepage to learn more

Konnect Cloud

Kong Inc. offers commercial subscriptions that enhance the Kong Gateway in a variety of ways. Customers of Kong's Konnect Cloud subscription take advantage of additional gateway functionality, commercial support, and access to Kong's managed (SaaS) control plane platform. The Konnect Cloud platform features include real-time analytics, a service catalog, developer portals, and so much more! Get started with Konnect Cloud.

License

Copyright 2016-2026 Kong Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Grokitach/Stalker_GAMMA

S.T.A.L.K.E.R. G.A.M.M.A. modpack for Anomaly

Description

G.A.M.M.A. stands for Grok's Automated Modular Modpack for Anomaly. This modpack for the 100% free and standalone STALKER Anomaly changes every aspect of the game, from the entire economy to the minute detail statistic of every gun and artefact.

From a technical point of view, the main motivation behind this project is to provide an easy to install, automatically updated and modular modding platform for Stalker Anomaly. From a gameplay point of view, the default parameters and mods activated with G.A.M.M.A. aim at providing a balanced survival, scavenging, cooking, crafting and repairing focused experience with a streamlined gameplay. GAMMA aims at creating a meaningful and enjoyable sense of progression in the sandbox Chernobyl Exclusion Zone of STALKER Anomaly.

The sense of progression in GAMMA is achieved through different aspects, that you can customise to some extent:

The more to the north you go, the more dangerous the Zone is (stronger stalkers, stronger mutants, more deadly anomalies, stronger radiations) but the better are the rewards (better gear, better toolkits, better artefacts).
Gear acquisition is locked behind getting toolkits that are obtained by visiting rare stashes acquired by accomplishing several maps.
Guns with green barrels will deal full damage and just need few parts of good quality to stop jamming (without the need of toolkits or repair kits).
The gear you find on enemies need to be repaired using repair kits crafted using toolkits.
The artefacts you find are immediately useable but need to be empowered by combining artefacts to achieve higher protection levels (using a specific tool buyable at Ecologists).
Access to the North of the Zone is locked behind completing the Miracle Machine and the Brain Scorcher.
GAMMA removes all gear trading, meaning you cannot buy or sell weapons or armor.
GAMMA removes random stash loot, so you can't just run to the meta stashes and have endgame equipment instantly.
The healing system uses multiple body parts that get damaged individually and that you heal by using first-aid kits/bandages/stimpacks followed by post-heal items such as antibiotics, antidotes, painkillers, and anti-inflammatory drugs.
GAMMA completely revamps the STALKER Anomaly graphics, gun models, animations, A-life, Combat AI and much more thanks to the many mods made by the community.

This modpack is 100% copyright free since it redistributes little to no copyrighted content developed by other modders. Indeed, G.A.M.M.A. downloads every add-on directly from moddb or github, and installs them automatically. You will thus directly support modders by installing G.A.M.M.A. On top of this, each addon original source (moddb or github page) is directly accessible from the Mod Organizer 2 instance by right-clicking addons > visit moddb.com.

Installation

S.T.A.L.K.E.R. G.A.M.M.A. can be installed following the wiki guide (short and concise) or the discord guide (in depth, with lot of images).

It can also be installed using GOG one-click mod install system (simplest installation procedure), which however requires to own one of the base games: https://www.gog.com/en/game/stalker_gamma

Contributing

Any Pull Request should be made to the dev2 branch. Anyone can contribute to this project.

Credits

S.T.A.L.K.E.R. G.A.M.M.A. is a fan-created modification for S.T.A.L.K.E.R. games, developed and wholly owned by GSC Game World. S.T.A.L.K.E.R. G.A.M.M.A. is not an official product of GSC Game World and is a derivative work based on their S.T.A.L.K.E.R. games.

You can support GSC by buying the original games here (although, they are not needed to play GAMMA):

Steam: https://store.steampowered.com/franchise/stalker GOG: https://www.gog.com/en/game/stalker_shadow_of_chernobyl | https://www.gog.com/en/game/stalker_clear_sky | https://www.gog.com/en/game/stalker_call_of_pripyat

GAMMA is a large project using the work of many talented modders, and each and everyone one of them are contributing to making Stalker Anomaly a better experience. You can check the entire modlist, modder names and mod pages link used by GAMMA here: https://stalker-gamma.com/api/list

I would like to thank all the modders involved in this project by making all the GAMMA addons free to use, edit and repost with modifications as long as the source is indicated (original addon author, from Stalker GAMMA). For numbered addons (105-), original authors must be contacted before repost and modifications. Repost of unmodified individual parts of this project are not recommended and may harm the community in the long run because updates happen quite often in this repository and it is thus better to directly post links to the relevant files stored here.

Other Projects

A similar logic was applied to a modpack built for Dragon's Dogma 2 called "Dragon's Dogamma", for whic the entire gear looting system as been remade to put more emphasis on exploration and boss hunting instead of buying gear from shops: https://github.com/Grokitach/Dragons-Dogamma

milanglacier/minuet-ai.nvim

💃 Dance with Intelligence in Your Code. Minuet offers code completion as-you-type from popular LLMs including OpenAI, Gemini, Claude, Ollama, Llama.cpp, Codestral, and more.

Minuet

Minuet: Dance with Intelligence in Your Code 💃.

Minuet brings the grace and harmony of a minuet to your coding process. Just as dancers move during a minuet.

Features

AI-powered code completion with dual modes:
- Specialized prompts and various enhancements for chat-based LLMs on code completion tasks.
- Fill-in-the-middle (FIM) completion for compatible models (DeepSeek, Codestral, Qwen, and others).
Support for multiple AI providers (OpenAI, Claude, Gemini, Codestral, Ollama, Llama-cpp, and OpenAI-compatible services).
Customizable configuration options.
Streaming support to enable completion delivery even with slower LLMs.
No proprietary binary running in the background. Just curl and your preferred LLM provider.
Support virtual-text, nvim-cmp, blink-cmp, built-in, mini.completion frontend.
Act as an in-process LSP server to provide completions (opt-in feature).
Accept multi-line suggestions line-by-line, so longer suggestions can be pulled in incrementally in your own pace.
When your typed text matches the start of a suggestion, Minuet keeps the completion in sync of your typed text rather than discarding it, to reduce unnecessary LLM requests and conserving resources.
Support next-edit prediction (NES) via Minuet duet commands. This feature is highly experimental.

With nvim-cmp / blink-cmp frontend:

With builtin completion frontend (requires nvim 0.11+):

With virtual text frontend:

https://github.com/user-attachments/assets/e0c4f2bd-0361-45b4-8eb4-0f49356bd7d9

With duet (next-edit prediction):

https://github.com/user-attachments/assets/b98699d5-b81d-4061-a1b3-d6f581c6b9b0

Requirements

Neovim 0.10+.
optional: nvim-cmp
optional: blink.cmp
An API key for at least one of the supported AI providers
~~plenary.nvim~~ Minuet now uses the builtin vim.system and no longer requires plenary.

Installation

Lazy.nvim:

specs = {
    {
        'milanglacier/minuet-ai.nvim',
        config = function()
            require('minuet').setup {
                -- Your configuration options here
            }
        end,
    },
    -- optional, if you are using virtual-text frontend, nvim-cmp is not
    -- required.
    { 'hrsh7th/nvim-cmp' },
    -- optional, if you are using virtual-text frontend, blink is not required.
    { 'Saghen/blink.cmp' },
}

Rocks.nvim:

Minuet is available on luarocks.org. Simply run Rocks install minuet-ai.nvim to install it like any other luarocks package.

Quick Start

Virtual Text Setup

require('minuet').setup {
    virtualtext = {
        auto_trigger_ft = {},
        keymap = {
            -- accept whole completion
            accept = '<A-A>',
            -- accept one line
            accept_line = '<A-a>',
            -- accept n lines (prompts for number)
            -- e.g. "A-z 2 CR" will accept 2 lines
            accept_n_lines = '<A-z>',
            -- Cycle to prev completion item, or manually invoke completion
            prev = '<A-[>',
            -- Cycle to next completion item, or manually invoke completion
            next = '<A-]>',
            dismiss = '<A-e>',
        },
    },
}

Nvim-cmp setup

require('cmp').setup {
    sources = {
        {
             -- Include minuet as a source to enable autocompletion
            { name = 'minuet' },
            -- and your other sources
        }
    },
    performance = {
        -- It is recommended to increase the timeout duration due to
        -- the typically slower response speed of LLMs compared to
        -- other completion sources. This is not needed when you only
        -- need manual completion.
        fetching_timeout = 2000,
    },
}


-- If you wish to invoke completion manually,
-- The following configuration binds `A-y` key
-- to invoke the configuration manually.
require('cmp').setup {
    mapping = {
        ["<A-y>"] = require('minuet').make_cmp_map()
        -- and your other keymappings
    },
}

Blink-cmp Setup

require('blink-cmp').setup {
    keymap = {
        -- Manually invoke minuet completion.
        ['<A-y>'] = require('minuet').make_blink_map(),
    },
    sources = {
         -- Enable minuet for autocomplete
        default = { 'lsp', 'path', 'buffer', 'snippets', 'minuet' },
        -- For manual completion only, remove 'minuet' from default
        providers = {
            minuet = {
                name = 'minuet',
                module = 'minuet.blink',
                async = true,
                -- Should match minuet.config.request_timeout * 1000,
                -- since minuet.config.request_timeout is in seconds
                timeout_ms = 3000,
                score_offset = 50, -- Gives minuet higher priority among suggestions
            },
        },
    },
    -- Recommended to avoid unnecessary request
    completion = { trigger = { prefetch_on_insert = false } },
}

In-Process LSP for Built-in Completion and Inline Completion

Requirements:

Neovim version 0.11 or higher is necessary for built-in completion.
Neovim version 0.12 or higher is necessary for vim.lsp.inline_completion.

Note:

config.lsp.completion.enable and config.lsp.inline_completion.enable are setup-time options. Minuet decides which LSP capabilities to expose when require('minuet').setup() runs, so changing either option later will not enable the feature for an already-running Minuet LSP server.

If you might want to use one of these features later in the same session, enable it during setup first, then control only its per-buffer auto-trigger behavior at runtime.

Completion

require('minuet').setup {
    lsp = {
        enabled_ft = { 'toml', 'lua', 'cpp' },
        completion = {
            -- Enables automatic completion triggering using `vim.lsp.completion.enable`
            enabled_auto_trigger_ft = { 'cpp', 'lua' },
        },
    }
}

The completion.enabled_auto_trigger_ft setting is relevant only for built-in completion (vim.lsp.completion). Mini.Completion users can ignore this option, as Mini.Completion uses all available LSPs for auto-triggered completion.

For manually triggered completion, ensure vim.bo.omnifunc is set to v:lua.vim.lsp.omnifunc and use <C-x><C-o> in Insert mode.

Recommendation:

For users of blink-cmp and nvim-cmp, it is recommended to use the native source rather than through LSP for two main reasons:

blink-cmp and nvim-cmp offer better sorting and async management when Minuet is utilized as a separate source rather than alongside a regular LSP such as clangd.
With blink-cmp and nvim-cmp native sources, it's possible to configure Minuet for manual completion only, disabling automatic completion. However, when Minuet operates as an LSP server, it is impossible to determine whether completion is triggered automatically or manually.

The LSP protocol specification defines three triggerKind values: Invoked, TriggerCharacter, and TriggerForIncompleteCompletions. However, none of these specifically differentiates between manual and automatic completion requests.

Note:

An upstream issue (tracked here) may cause unexpected indentation behavior when accepting multi-line completions.

Currently, Minuet offers the config option config.lsp.completion.adjust_indentation (enabled by default) as a temporary workaround. However, the author acknowledges that this solution is incomplete and may introduce additional edge cases when enabled.

Therefore, consider the following practices when using built-in completion:
- Ensure config.add_single_line_entry = true and only accept single-line completions.
- Avoid using Minuet and built-in completion with languages where indentation affects semantics, such as Python.
Users might call vim.lsp.completion.enable {autotrigger = true} during the LspAttach event when the client supports completion. However, this is not the desired behavior for Minuet. As an LLM completion source, Minuet can face significant rate limits during automatic triggering.

Therefore, it's recommended to enable Minuet for automatic triggering using the config.lsp.completion.enabled_auto_trigger_ft setting.

For users who uses LspAttach event, it is recommeded to verify that the server is not the Minuet server before enabling autotrigger. An example configuration is shown below:

vim.api.nvim_create_autocmd('LspAttach', {
    callback = function(args)
        local client_id = args.data.client_id
        local bufnr = args.buf
        local client = vim.lsp.get_client_by_id(client_id)
        if not client then
            return
        end

        if client.server_capabilities.completionProvider and client.name ~= 'minuet' then
            vim.lsp.completion.enable(true, client_id, bufnr, { autotrigger = true })
        end
    end,
    desc = 'Enable built-in auto completion',
})

Inline completion

Minuet can also expose suggestions through Neovim's built-in vim.lsp.inline_completion interface:

require('minuet').setup {
    lsp = {
        enabled_ft = { 'toml', 'lua', 'cpp' },
        -- It is recommended to disable completion when use inline_completion
        completion = { enable = false },
        inline_completion = {
            enable = true,
            enabled_auto_trigger_ft = { 'cpp', 'lua' },
        },
    },
}

vim.keymap.set('i', '<A-x>', function()
    vim.lsp.inline_completion.get()
end, { desc = 'accept' })
vim.keymap.set('i', '<A-c>', function()
    vim.lsp.inline_completion.select { count = 1 }
end, { desc = 'cycle to next' })
vim.keymap.set('i', '<A-v>', function()
    vim.lsp.inline_completion.select { count = -1 }
end, { desc = 'cycle to prev' })

If you prefer not to use inline completion at startup but still want the option to enable it for specific buffers later, set config.lsp.inline_completion.enable = true during setup and leave config.lsp.inline_completion.enabled_auto_trigger_ft empty. You can then enable it at runtime for the current buffer with: :Minuet lsp inline_completion enable_auto_trigger.

Recommendation:

If you want inline suggestions, Minuet's own virtualtext frontend is still the recommended choice. Neovim's built-in inline_completion support is a useful baseline, but in practice it only covers automatic triggering. Minuet's virtualtext frontend supports a much more comprehensive workflow: it supports both manual invocation and automatic triggering, keeps suggestions in sync as you continue typing, and lets you accept longer suggestions incrementally, including accepting only part of a completion instead of the entire suggestion at once.

When using LSP inline completion, avoid enabling Minuet virtualtext at the same time.

LLM Provider Examples

Openrouter deepseek-v4-flash

require('minuet').setup {
    provider = 'openai_compatible',
    request_timeout = 2.5,
    throttle = 1500, -- Increase to reduce costs and avoid rate limits
    debounce = 600, -- Increase to reduce costs and avoid rate limits
    provider_options = {
        openai_compatible = {
            api_key = 'OPENROUTER_API_KEY',
            end_point = 'https://openrouter.ai/api/v1/chat/completions',
            model = 'deepseek/deepseek-v4-flash',
            name = 'Openrouter',
            optional = {
                max_tokens = 56,
                top_p = 0.9,
                provider = {
                     -- Prioritize throughput for faster completion
                    sort = 'throughput',
                },
                -- disable thinking to avoid first token latency
                reasoning_effort = 'none'
            },
        },
    },
}

Opencode Go deepseek-v4-flash

require('minuet').setup {
    provider = 'openai_compatible',
    request_timeout = 2.5,
    throttle = 1500, -- Increase to reduce costs and avoid rate limits
    debounce = 600, -- Increase to reduce costs and avoid rate limits
    provider_options = {
        openai_compatible = {
            api_key = 'OPENCODE_GO_API_KEY',
            end_point = 'https://opencode.ai/zen/go/v1/chat/completions',
            model = 'deepseek-v4-flash',
            name = 'Opencode',
            optional = {
                max_tokens = 56,
                top_p = 0.9,
                -- disable thinking to avoid first token latency
                thinking = { type = 'disabled' },
            },
        },
    },
}

Deepseek deepseek-v4-flash

require('minuet').setup {
    provider = 'openai_fim_compatible',
    provider_options = {
        openai_fim_compatible = {
            api_key = 'DEEPSEEK_API_KEY',
            name = 'deepseek',
            optional = {
                max_tokens = 256,
                top_p = 0.9,
            },
        },
    },
}

Ollama Qwen-2.5-coder:7b

require('minuet').setup {
    provider = 'openai_fim_compatible',
    n_completions = 1, -- recommend for local model for resource saving
    -- I recommend beginning with a small context window size and incrementally
    -- expanding it, depending on your local computing power. A context window
    -- of 512, serves as an good starting point to estimate your computing
    -- power. Once you have a reliable estimate of your local computing power,
    -- you should adjust the context window to a larger value.
    context_window = 512,
    provider_options = {
        openai_fim_compatible = {
            -- For Windows users, TERM may not be present in environment variables.
            -- Consider using APPDATA instead.
            api_key = 'TERM',
            name = 'Ollama',
            end_point = 'http://localhost:11434/v1/completions',
            model = 'qwen2.5-coder:7b',
            optional = {
                max_tokens = 56,
                top_p = 0.9,
            },
        },
    },
}

Llama.cpp Qwen-2.5-coder:1.5b

First, launch the llama-server with your chosen model.

Here's an example of a bash script to start the server if your system has less than 8GB of VRAM:

llama-server \
    -hf ggml-org/Qwen2.5-Coder-1.5B-Q8_0-GGUF \
    --port 8012 -ngl 99 -fa -ub 1024 -b 1024 \
    --ctx-size 0 --cache-reuse 256

require('minuet').setup {
    provider = 'openai_fim_compatible',
    n_completions = 1, -- recommend for local model for resource saving
    -- I recommend beginning with a small context window size and incrementally
    -- expanding it, depending on your local computing power. A context window
    -- of 512, serves as an good starting point to estimate your computing
    -- power. Once you have a reliable estimate of your local computing power,
    -- you should adjust the context window to a larger value.
    context_window = 512,
    provider_options = {
        openai_fim_compatible = {
            -- For Windows users, TERM may not be present in environment variables.
            -- Consider using APPDATA instead.
            api_key = 'TERM',
            name = 'Llama.cpp',
            end_point = 'http://localhost:8012/v1/completions',
            -- The model is set by the llama-cpp server and cannot be altered
            -- post-launch.
            model = 'PLACEHOLDER',
            optional = {
                max_tokens = 56,
                top_p = 0.9,
            },
            -- Llama.cpp does not support the `suffix` option in FIM completion.
            -- Therefore, we must disable it and manually populate the special
            -- tokens required for FIM completion.
            template = {
                prompt = function(context_before_cursor, context_after_cursor, _)
                    return '<|fim_prefix|>'
                        .. context_before_cursor
                        .. '<|fim_suffix|>'
                        .. context_after_cursor
                        .. '<|fim_middle|>'
                end,
                suffix = false,
            },
        },
    },
}

NOTE: Special tokens such as <|fim_prefix|> vary across different models. The example code provided uses the tokens specific to Qwen-2.5-coder. If you intend to use a different model, ensure the llama-cpp template is updated to reflect the corresponding special tokens for your chosen model.

For additional example bash scripts to run llama.cpp based on your local computing power, please refer to recipes.md.

Selecting a Provider or Model

The gemini-2.0-flash and codestral models offer high-quality output with free and fast processing. The deepseek-v4-flash model, used with the openai_fim_compatible provider, is an alternative for low-cost APIs and fast inference. For local LLM inference, you can deploy either qwen-2.5-coder or deepseek-coder-v2 through Ollama using the openai-fim-compatible provider.

We do not recommend using thinking models, as this mode significantly increases latency—even with the fastest models. However, if you choose to use thinking models, please ensure that their thinking capabilities are disabled. Refer to the following examples for guidance on how to disable the thinking feature.

Understanding Model Speed

For cloud-based providers, Openrouter offers a valuable resource for comparing the speed of both closed-source and open-source models hosted by various cloud inference providers.

When assessing model speed, two key metrics are latency (time to first token) and throughput (tokens per second). Latency is often a more critical factor than throughput.

Ideally, one would aim for a latency of less than 1 second and a throughput exceeding 100 tokens per second.

For local LLM, llama.cpp#4167 provides valuable data on model speed for 7B models running on Apple M-series chips. The two crucial metrics are Q4_0 PP [t/s], which measures latency (tokens per second to process the KV cache, equivalent to the time to generate the first token), and Q4_0 TG [t/s], which indicates the tokens per second generation speed.

Configuration

Minuet AI comes with the following defaults:

default_config = {
    -- Enable or disable auto-completion. Note that you still need to add
    -- Minuet to your cmp/blink sources. This option controls whether cmp/blink
    -- will attempt to invoke minuet when minuet is included in cmp/blink
    -- sources. This setting has no effect on manual completion; Minuet will
    -- always be enabled when invoked manually. You can use the command
    -- `Minuet cmp/blink toggle` to toggle this option.
    cmp = {
        enable_auto_complete = true,
    },
    blink = {
        enable_auto_complete = true,
    },
    -- LSP is recommended only for built-in completion. If you are using
    -- `cmp` or `blink`, utilizing LSP for code completion from Minuet is *not*
    -- recommended.
    lsp = {
        enabled_ft = {},
        -- Filetypes excluded from LSP activation. Useful when `enabled_ft` = { '*' }
        disabled_ft = {},
        completion = {
            enable = true,
            -- if true, warn the user that they should use the native source
            -- instead when the user is using blink or nvim-cmp.
            warn_on_blink_or_cmp = true,
            -- See README In-Process LSP section for more details on this option.
            adjust_indentation = true,
            -- Enables automatic completion triggering using `vim.lsp.completion.enable`
            enabled_auto_trigger_ft = {},
            -- Filetypes excluded from autotriggering. Useful when `enabled_auto_trigger_ft` = { '*' }
            disabled_auto_trigger_ft = {},
        },
        -- Minuet's own virtualtext frontend is recommended **over** lsp.inline_completion
        inline_completion = {
            enable = false,
            -- if true, warn when LSP inline completion is enabled while
            -- Minuet virtual text is also configured for use.
            warn_on_virtualtext = true,
            -- if true, warn when both LSP completion and inline completion
            -- are enabled. Enabling only one of them is recommended.
            warn_on_lsp_completion = true,
            -- Enables automatic inline completion using `vim.lsp.inline_completion.enable`
            -- for these filetypes.
            enabled_auto_trigger_ft = {},
            -- Filetypes excluded from inline completion autotriggering.
            disabled_auto_trigger_ft = {},
        },
    },
    virtualtext = {
        -- Specify the filetypes to enable automatic virtual text completion,
        -- e.g., { 'python', 'lua' }. Note that you can still invoke manual
        -- completion even if the filetype is not on your auto_trigger_ft list.
        auto_trigger_ft = {},
        -- specify file types where automatic virtual text completion should be
        -- disabled. This option is useful when auto-completion is enabled for
        -- all file types i.e., when auto_trigger_ft = { '*' }
        auto_trigger_ignore_ft = {},
        keymap = {
            accept = nil,
            accept_line = nil,
            accept_n_lines = nil,
            -- Cycle to next completion item, or manually invoke completion
            next = nil,
            -- Cycle to prev completion item, or manually invoke completion
            prev = nil,
            dismiss = nil,
        },
        -- Whether show virtual text suggestion when the completion menu
        -- (nvim-cmp or blink-cmp) is visible.
        show_on_completion_menu = false,
    },
    provider = 'codestral',
    -- the maximum total characters of the context before and after the cursor
    -- 16000 characters typically equate to approximately 4,000 tokens for
    -- LLMs.
    context_window = 16000,
    -- when the total characters exceed the context window, the ratio of
    -- context before cursor and after cursor, the larger the ratio the more
    -- context before cursor will be used. This option should be between 0 and
    -- 1, context_ratio = 0.75 means the ratio will be 3:1.
    context_ratio = 0.75,
    throttle = 1000, -- only send the request every x milliseconds, use 0 to disable throttle.
    -- debounce the request in x milliseconds, set to 0 to disable debounce
    debounce = 400,
    -- Control notification display for request status
    -- Notification options:
    -- false: Disable all notifications (use boolean false, not string "false")
    -- "debug": Display all notifications (comprehensive debugging)
    -- "verbose": Display most notifications
    -- "warn": Display warnings and errors only
    -- "error": Display errors only
    notify = 'warn',
    -- The request timeout, measured in seconds. When streaming is enabled
    -- (stream = true), setting a shorter request_timeout allows for faster
    -- retrieval of completion items, albeit potentially incomplete.
    -- Conversely, with streaming disabled (stream = false), a timeout
    -- occurring before the LLM returns results will yield no completion items.
    request_timeout = 3,
    -- Command used to make HTTP requests.
    curl_cmd = 'curl',
    -- Extra arguments passed to curl (list of strings).
    curl_extra_args = {},
    -- If completion item has multiple lines, create another completion item
    -- only containing its first line. This option only has impact for cmp and
    -- blink. For virtualtext, no single line entry will be added.
    add_single_line_entry = true,
    -- The number of completion items encoded as part of the prompt for the
    -- chat LLM. For FIM model, this is the number of requests to send. It's
    -- important to note that when 'add_single_line_entry' is set to true, the
    -- actual number of returned items may exceed this value. Additionally, the
    -- LLM cannot guarantee the exact number of completion items specified, as
    -- this parameter serves only as a prompt guideline.
    n_completions = 3,
    --  Length of context after cursor used to filter completion text.
    --
    -- This setting helps prevent the language model from generating redundant
    -- text.  When filtering completions, the system compares the suffix of a
    -- completion candidate with the text immediately following the cursor.
    --
    -- If the length of the longest common substring between the end of the
    -- candidate and the beginning of the post-cursor context exceeds this
    -- value, that common portion is trimmed from the candidate.
    --
    -- For example, if the value is 15, and a completion candidate ends with a
    -- 20-character string that exactly matches the 20 characters following the
    -- cursor, the candidate will be truncated by those 20 characters before
    -- being delivered.
    after_cursor_filter_length = 15,
    -- Similar to after_cursor_filter_length but trim the completion item from
    -- prefix instead of suffix.
    before_cursor_filter_length = 2,
    -- proxy port to use
    proxy = nil,
    -- **List** of functions to execute. If any function returns `false`, Minuet
    -- will not trigger auto-completion. Manual completion can still be invoked,
    -- even if these functions evaluate to `false`, when using `nvim-cmp`,
    -- `blink-cmp`, or virtual text (excluding LSP).
    -- When this list is empty (the default), it always evaluates to `true`.
    -- Note that this is called each time Minuet attempts to trigger
    -- auto-completion, so ensure the functions in this list are highly efficient.
    enable_predicates = {},
    provider_options = {
        -- see the documentation in each provider in the following part.
    },
    -- see the documentation in the `Prompt` section
    default_system = {
        template = '...',
        prompt = '...',
        guidelines = '...',
        n_completion_template = '...',
    },
    default_system_prefix_first = {
        template = '...',
        prompt = '...',
        guidelines = '...',
        n_completion_template = '...',
    },
    default_fim_template = {
        prompt = '...',
        suffix = '...',
    },
    default_few_shots = { '...' },
    default_chat_input = { '...' },
    default_few_shots_prefix_first = { '...' },
    default_chat_input_prefix_first = { '...' },
    -- Config options for `Minuet change_preset` command
    presets = {}
}

API Keys

Minuet AI requires API keys to function. Set the following environment variables:

OPENAI_API_KEY for OpenAI
GEMINI_API_KEY for Gemini
ANTHROPIC_API_KEY for Claude
CODESTRAL_API_KEY for Codestral
Custom environment variable for OpenAI-compatible services (as specified in your configuration)

Note: Provide the name of the environment variable to Minuet, not the actual value. For instance, pass OPENAI_API_KEY to Minuet, not the value itself (e.g., sk-xxxx).

If using Ollama, you need to assign an arbitrary, non-null environment variable as a placeholder for it to function.

Alternatively, you can provide a function that returns the API key. This function should return the result instantly as it will be called for each completion request.

require('minuet').setup {
    provider_options = {
        openai_compatible = {
            -- good
            api_key = 'FIREWORKS_API_KEY', -- will read the environment variable FIREWORKS_API_KEY
            -- good
            api_key = function() return 'sk-xxxx' end,
            -- bad
            api_key = 'sk-xxxx',
        }
    }
}

Prompt

See prompt for the default prompt used by minuet and instructions on customization.

Note that minuet employs two distinct prompt systems:

A system designed for chat-based LLMs (OpenAI, OpenAI-Compatible, Claude, and Gemini)
A separate system designed for Codestral and OpenAI-FIM-compatible models

Prefix-First vs. Suffix-First

When use chat-based LLMs, there are two ways for constructing the prompt: placing the prefix (context before the cursor) before the suffix (context after the cursor), or placing the suffix before the prefix.

By default, minuet uses the prefix-first style for the OpenAI, Gemini, and OpenAI-Compatible (with deepseek-v4-flash as the default model) providers, and the suffix-first style for Claude providers. It is recommended that you experiment with both strategies to determine which yields the best results, particularly if you are using an OpenAI-compatible provider with various models.

Below is an example code snippet demonstrating how to switch between these two prompt construction methods:

local mc = require 'minuet.config'

-- Prefix-first style
require('minuet').setup {
    provider_options = {
        openai_compatible = {
            system = mc.default_system_prefix_first,
            chat_input = mc.default_chat_input_prefix_first,
            few_shots = mc.default_few_shots_prefix_first,
        },
    },
}

-- Suffix-first style
require('minuet').setup {
    provider_options = {
        openai_compatible = {
            system = mc.default_system,
            few_shots = mc.default_few_shots,
            chat_input = mc.default_chat_input,
        },
    },
}

Providers

You need to set the field provider in the config, the default provider is codestral. For example:

require('minuet').setup {
    provider = 'gemini'
}

OpenAI

the following is the default configuration for OpenAI:

provider_options = {
    openai = {
        model = 'gpt-5.4-nano',
        end_point = 'https://api.openai.com/v1/chat/completions',
        system = "see [Prompt] section for the default value",
        few_shots = "see [Prompt] section for the default value",
        chat_input = "See [Prompt Section for default value]",
        stream = true,
        api_key = 'OPENAI_API_KEY',
        optional = {
            -- pass any additional parameters you want to send to OpenAI request,
            -- e.g.
            -- stop = { 'end' },
            -- max_completion_tokens = 256,
            -- top_p = 0.9,
            -- reasoning_effort = 'minimal'
            -- reasoning_effort = 'none'
        },
        -- a list of functions to transform the endpoint, header, and request body
        transform = {},
    },
}

The following configuration is not the default, but recommended to prevent request timeout from outputing too many tokens.

provider_options = {
	openai = {
		optional = {
			max_completion_tokens = 128,
			-- for thinking models
			reasoning_effort = 'none'
			-- reasoning_effort = "minimal",
			-- Set to "minimal" if your chosen model doesn't support "none"
		},
	},
}

Note: If you intend to use GPT-5 series models (e.g., gpt-5-mini or gpt-5.4-nano), keep the following points in mind:

Use max_completion_tokens instead of max_tokens.
These models do not support top_p or temperature adjustments.
Disable thinking by setting reasoning_effort to none, or use minimal if your chosen model does not support none.

Claude

the following is the default configuration for Claude:

provider_options = {
    claude = {
        max_tokens = 256,
        model = 'claude-haiku-4.5',
        system = "see [Prompt] section for the default value",
        few_shots = "see [Prompt] section for the default value",
        chat_input = "See [Prompt Section for default value]",
        stream = true,
        api_key = 'ANTHROPIC_API_KEY',
        end_point = 'https://api.anthropic.com/v1/messages',
        optional = {
            -- pass any additional parameters you want to send to claude request,
            -- e.g.
            -- stop_sequences = nil,
        },
        -- a list of functions to transform the endpoint, header, and request body
        transform = {},
    },
}

Codestral

Codestral is a text completion model, not a chat model, so the system prompt and few shot examples does not apply. Note that you should use the CODESTRAL_API_KEY, not the MISTRAL_API_KEY, as they are using different endpoint. To use the Mistral endpoint, simply modify the end_point and api_key parameters in the configuration.

the following is the default configuration for Codestral:

provider_options = {
    codestral = {
        model = 'codestral-latest',
        end_point = 'https://codestral.mistral.ai/v1/fim/completions',
        api_key = 'CODESTRAL_API_KEY',
        stream = true,
        template = {
            prompt = "See [Prompt Section for default value]",
            suffix = "See [Prompt Section for default value]",
        },
        optional = {
            stop = nil, -- the identifier to stop the completion generation
            max_tokens = nil,
        },
    },
}

The following configuration is not the default, but recommended to prevent request timeout from outputing too many tokens.

provider_options = {
    codestral = {
        optional = {
            max_tokens = 256,
            stop = { '\n\n' },
        },
    },
}

Mercury Coder

Developed by Inception, Mercury Coder is described as a diffusion-based large language model that accelerates code generation through iterative refinement rather than autoregressive token prediction. According to the claim, this approach is intended to deliver faster and more efficient code completions. To begin, obtain an API key from the Inception Platform and configure it as the INCEPTION_API_KEY environment variable.

You can access Mercury Coder via the OpenAI compatible FIM endpoint using the following configuration:

provider_options = {
    openai_fim_compatible = {
        model = "mercury-coder",
        end_point = "https://api.inceptionlabs.ai/v1/fim/completions",
        api_key = "INCEPTION_API_KEY", -- environment variable name
        stream = true,
    },
}

Gemini

You should register the account and use the service from Google AI Studio instead of Google Cloud. You can get an API key via their Google API page.

The following config is the default.

provider_options = {
    gemini = {
        model = 'gemini-2.0-flash',
        system = "see [Prompt] section for the default value",
        few_shots = "see [Prompt] section for the default value",
        chat_input = "See [Prompt Section for default value]",
        stream = true,
        api_key = 'GEMINI_API_KEY',
        end_point = 'https://generativelanguage.googleapis.com/v1beta/models',
        optional = {},
        -- a list of functions to transform the endpoint, header, and request body
        transform = {},
    },
}

The following configuration is not the default, but recommended to prevent request timeout from outputing too many tokens. You can also adjust the safety settings following the example:

provider_options = {
    gemini = {
        optional = {
            generationConfig = {
                maxOutputTokens = 256,
                thinkingConfig = {
                    -- Disable thinking for gemini 2.5 models
                    thinkingBudget = 0,
                    -- Disable thinking for gemini 3.x models
                    thinkingLevel = 'minimal',
                    -- Setting only one of the above options is sufficient.
                },
            },
            safetySettings = {
                {
                    -- HARM_CATEGORY_HATE_SPEECH,
                    -- HARM_CATEGORY_HARASSMENT
                    -- HARM_CATEGORY_SEXUALLY_EXPLICIT
                    category = 'HARM_CATEGORY_DANGEROUS_CONTENT',
                    -- BLOCK_NONE
                    threshold = 'BLOCK_ONLY_HIGH',
                },
            },
        },
    },
}

We recommend using gemini-2.0-flash over gemini-2.5-flash, as the 2.0 version offers significantly lower costs with comparable performance. The primary improvement in version 2.5 lies in its extended thinking mode, which provides minimal value for code completion scenarios. Furthermore, the thinking mode substantially increases latency, so we recommend disabling it entirely.

OpenAI-compatible

Use any providers compatible with OpenAI's chat completion API.

For example, you can set the end_point to http://localhost:11434/v1/chat/completions to use ollama.

Note that not all openAI compatible services has streaming support, you should change stream=false to disable streaming in case your services do not support it.

The following config is the default.

provider_options = {
    openai_compatible = {
        model = 'deepseek/deepseek-v4-flash',
        system = "see [Prompt] section for the default value",
        few_shots = "see [Prompt] section for the default value",
        chat_input = "See [Prompt Section for default value]",
        stream = true,
        end_point = 'https://openrouter.ai/api/v1/chat/completions',
        api_key = 'OPENROUTER_API_KEY',
        name = 'Openrouter',
        optional = {
            stop = nil,
            max_tokens = nil,
        },
        -- a list of functions to transform the endpoint, header, and request body
        transform = {},
    }
}

Disabling thinking for reasoning models:

Provider	Configuration
OpenRouter	`reasoning = { effort = 'none' }` (or `'minimal'`, depending on the model)
DeepSeek API	`thinking = { type = 'disabled' }`
Various Provider	`reasoning_effort = 'none'`

provider_options = {
    openai_compatible = {
        optional = {
            -- Disable thinking for reasoning models
            reasoning = { effort = 'none' }, -- or "minimal", depending on the model (OpenRouter)
            -- reasoning_effort = 'none', -- or "minimal", depending on the model (various providers)
            -- thinking = { type = 'disabled' } -- DeepSeek API
        },
    },
}

OpenAI-FIM-compatible

Use any provider compatible with OpenAI's completion API. This request uses the text /completions endpoint, not /chat/completions endpoint, so system prompts and few-shot examples are not applicable.

For example, you can set the end_point to http://localhost:11434/v1/completions to use ollama, http://localhost:8012/v1/completions to use llama.cpp.

Cmdline completion is available for models supported by these providers: deepseek, ollama, and siliconflow.

Refer to the Completions Legacy section of the OpenAI documentation for details.

Please note that not all OpenAI-compatible services support streaming. If your service does not support streaming, you should set stream=false to disable it.

Additionally, for Ollama users, it is essential to verify whether the model's template supports FIM completion. For example, qwen2.5-coder offers FIM support, as suggested in its template. However it may come as a surprise to some users that, deepseek-coder does not support the FIM template, and you should use deepseek-coder-v2 instead.

For example bash scripts to run llama.cpp based on your local computing power, please refer to recipes.md. Note that the model for llama.cpp must be determined when you launch the llama.cpp server and cannot be changed thereafter.

provider_options = {
    openai_fim_compatible = {
        model = 'deepseek-v4-flash',
        end_point = 'https://api.deepseek.com/beta/completions',
        api_key = 'DEEPSEEK_API_KEY',
        name = 'Deepseek',
        stream = true,
        template = {
            prompt = "See [Prompt Section for default value]",
            suffix = "See [Prompt Section for default value]",
        },
        -- a list of functions to transform the endpoint, header, and request body
        transform = {},
        -- Custom function to extract LLM-generated text from JSON output
        get_text_fn = {}
        optional = {
            stop = nil,
            max_tokens = nil,
        },
    }
}

The following configuration is not the default, but recommended to prevent request timeout from outputing too many tokens.

provider_options = {
    openai_fim_compatible = {
        optional = {
            max_tokens = 256,
            stop = { '\n\n' },
        },
    },
}

Non-OpenAI-FIM-Compatible APIs

For providers like DeepInfra FIM (https://api.deepinfra.com/v1/inference/), refer to recipes.md for advanced configuration instructions.

Commands

`Minuet change_provider`, `Minuet change_model`

The change_provider command allows you to change the provider after Minuet has been setup.

Example usage: Minuet change_provider claude

The change_model command allows you to change both the provider and model in one command. When called without arguments, it will open an interactive selection menu using vim.ui.select to choose from available models. When called with an argument, the format is provider:model.

Example usage:

Minuet change_model - Opens interactive model selection
Minuet change_model gemini:gemini-1.5-pro-latest - Directly sets the model

Note: For openai_compatible and openai_fim_compatible providers, the model completions in cmdline are determined by the name field in your configuration. For example, if you configured:

provider_options.openai_compatible.name = 'Fireworks'

When entering Minuet change_model openai_compatible: in the cmdline, you'll see model completions specific to the Fireworks provider.

`Minuet change_preset`

The change_preset command allows you to switch between config presets that were defined during initial setup. Presets provide a convenient way to toggle between different config sets. This is particularly useful when you need to:

Switch between different cloud providers (such as Fireworks or Groq) for the openai_compatible provider
Apply different throttle and debounce settings for different providers

When called, the command merges the selected preset with the current config table to create an updated configuration.

Usage syntax: Minuet change_preset preset_1

Presets can be configured during the initial setup process.

require('minuet').setup {
    presets = {
        preset_1 = {
            -- Configuration for cloud-based requests with large context window
            context_window = 20000,
            request_timeout = 4,
            throttle = 3000,
            debounce = 1000,
            provider = 'openai_compatible',
            provider_options = {
                openai_compatible = {
                    model = 'llama-3.3-70b-versatile',
                    api_key = 'GROQ_API_KEY',
                    name = 'Groq'
                }
            }
        },
        preset_2 = {
            -- Configuration for local model with smaller context window
            provider = 'openai_fim_compatible',
            context_window = 2000,
            throttle = 400,
            debounce = 100,
            provider_options = {
                openai_fim_compatible = {
                    api_key = 'TERM',
                    name = 'Ollama',
                    end_point = 'http://localhost:11434/v1/completions',
                    model = 'qwen2.5-coder:7b',
                    optional = {
                        max_tokens = 256,
                        top_p = 0.9
                    }
                }
            }
        }
    }
}

`Minuet blink`, `Minuet cmp`

Enable or disable autocompletion for nvim-cmp or blink.cmp. While Minuet must be added to your cmp/blink sources, this command only controls whether Minuet is triggered during autocompletion. The command does not affect manual completion behavior - Minuet remains active and available when manually invoked.

Example usage: Minuet blink toggle, Minuet blink enable, Minuet blink disable

`Minuet virtualtext`

Enable or disable the automatic display of virtual-text completion in the current buffer.

Example usage: Minuet virtualtext toggle, Minuet virtualtext enable, Minuet virtualtext disable.

`Minuet duet`

The Minuet duet command provides manual next-edit prediction controls:

:Minuet duet predict: Request an NES prediction for the current editable region and show it as a preview.
:Minuet duet apply: Apply the current duet prediction.
:Minuet duet dismiss: Dismiss the current duet prediction preview.

`Minuet lsp`

The Minuet LSP command provides commands for managing the in-process LSP server:

:Minuet lsp attach: Attach the Minuet LSP server to the current buffer.
:Minuet lsp detach: Detach the Minuet LSP server from the current buffer.
:Minuet lsp completion enable_auto_trigger: Enable auto-triggered vim.lsp.completion for the current buffer.
:Minuet lsp completion disable_auto_trigger: Disable auto-triggered vim.lsp.completion for the current buffer.
:Minuet lsp inline_completion enable_auto_trigger: Enable vim.lsp.inline_completion auto-triggering for the current buffer.
:Minuet lsp inline_completion disable_auto_trigger: Disable vim.lsp.inline_completion auto-triggering for the current buffer.

Duet (Next Edit Prediction)

Minuet duet is Minuet's highly experimental next-edit prediction (NES) feature.

Basic usage is manual. Bind the duet commands to your preferred keymaps, then:

Trigger :Minuet duet predict to request a prediction for the current edit.
Review the preview rendered in the buffer.
Apply it with :Minuet duet apply or discard it with :Minuet duet dismiss.

Example keymaps:

vim.keymap.set('n', '<leader>mp', '<cmd>Minuet duet predict<cr>', { desc = 'Minuet duet predict' })
vim.keymap.set('n', '<leader>ma', '<cmd>Minuet duet apply<cr>', { desc = 'Minuet duet apply' })
vim.keymap.set('n', '<leader>md', '<cmd>Minuet duet dismiss<cr>', { desc = 'Minuet duet dismiss' })
vim.keymap.set('i', '<A-z>', '<cmd>Minuet duet predict<cr>', { desc = 'Minuet duet predict' })
vim.keymap.set('i', '<A-a>', '<cmd>Minuet duet apply<cr>', { desc = 'Minuet duet apply' })
vim.keymap.set('i', '<A-x>', '<cmd>Minuet duet dismiss<cr>', { desc = 'Minuet duet dismiss' })

The recommended model at the moment is gemini-3-flash-preview.

require('minuet').setup {
    duet = {
        provider = 'gemini',
        provider_options = {
            gemini = {
                model = 'gemini-3-flash-preview',
                optional = {
                    generationConfig = {
                        thinkingConfig = {
                            -- Disable thinking is recommended
                            thinkingLevel = 'minimal',
                        },
                    },
                },
            },
            openai_compatible = {
                model = 'google/gemini-3.1-flash-lite',
                optional = {
                    -- Disable thinking is recommended.
                    reasoning_effort = 'none',
                    -- prioritize throughput for faster completion
                    provider = {
                        sort = 'throughput',
                    },
                },
            },
        },
    },
}

This feature is highly experimental:

It only targets general-purpose LLMs rather than NES-specialized models, as I lack local GPU resources for testing.
Comparable small models from competitors of Google—claude-haiku-4.5 and gpt-5.4-mini—perform poorly.
Given completion latency constraints, automatic duet prediction is not implemented.

It is recommended to configure the thinking levels of the models; refer to the provider sections for guidance on managing thinking settings for each provider.

Avoid setting a small max_tokens or max_completion_tokens limit for duet requests. Duet expects the model to return the complete rewritten editable region, including the cursor marker; if the response is truncated, the parser will reject it. Leave the limit unset when the provider allows that, or set it large enough to cover the full rewritten region.

TODO

Implement a proper diff mechanism to include recent edit changes in prompts.
Add support for specialized NES models (Zeta, Sweep).
Integrate with Inception's hosted API.
Implement automatically triggered duet prediction.

Default Config

require('minuet').setup {
    duet = {
        provider = 'gemini', -- Provider used by `:Minuet duet predict`.
        request_timeout = 15, -- Timeout in seconds for a single duet request.
        editable_region = {
            lines_before = 8, -- Number of editable lines included before the cursor.
            lines_after = 15, -- Number of editable lines included after the cursor.
            before_region_filter_length = 30, -- Trim duplicated text from the start of the model output when it repeats non-editable text before the region.
            after_region_filter_length = 30, -- Trim duplicated text from the end of the model output when it repeats non-editable text after the region.
        },
        non_editable_region = {
            context_window = 40000, -- Maximum characters of non-editable context included around the editable region.
            context_ratio = 0.75, -- Ratio of non-editable context before vs. after the editable region when truncation is needed.
        },
        markers = {
            editable_region_start = '<editable_region>', -- Marker that wraps the start of the editable region in prompts and responses.
            editable_region_end = '</editable_region>', -- Marker that wraps the end of the editable region in prompts and responses.
            cursor_position = '<cursor_position/>', -- Marker the model must preserve exactly once to indicate the final cursor position.
        },
        preview = {
            cursor = '', -- Virtual marker shown at the predicted cursor location in the preview.
        },
        provider_options = {
            openai = {
                model = 'gpt-5.4-mini', -- Default OpenAI model for duet requests.
                api_key = 'OPENAI_API_KEY', -- Environment variable name, or a function that returns the API key.
                end_point = 'https://api.openai.com/v1/chat/completions', -- OpenAI chat completions endpoint.
                system = { ... }, -- Duet system prompt config; keep the default unless you need a custom rewrite prompt.
                few_shots = { ... }, -- Example user/assistant turns used to steer the rewrite.
                chat_input = { ... }, -- Template that serializes editable and non-editable buffer regions.
                optional = {}, -- Extra request body fields passed through to the OpenAI API.
                transform = {}, -- Optional endpoint/header/body transforms applied before sending the request.
            },
            claude = {
                model = 'claude-haiku-4-5',
                api_key = 'ANTHROPIC_API_KEY',
                end_point = 'https://api.anthropic.com/v1/messages',
                system = { ... },
                few_shots = { ... },
                chat_input = { ... },
                max_tokens = 8192,
                optional = {},
                transform = {},
            },
            gemini = {
                model = 'gemini-3-flash-preview', -- Recommended duet model at the moment.
                api_key = 'GEMINI_API_KEY',
                end_point = 'https://generativelanguage.googleapis.com/v1beta/models',
                system = { ... },
                few_shots = { ... },
                chat_input = { ... },
                optional = {},
                transform = {},
            },
            openai_compatible = {
                model = 'google/gemini-3.1-flash-lite',
                api_key = 'OPENROUTER_API_KEY',
                end_point = 'https://openrouter.ai/api/v1/chat/completions',
                name = 'Openrouter',
                system = { ... },
                few_shots = { ... },
                chat_input = { ... },
                optional = {},
                transform = {},
            },
        },
    },
}

API

Virtual Text

minuet-ai.nvim offers the following functions to customize your key mappings:

{
    -- accept whole completion
    require('minuet.virtualtext').action.accept,
    -- accept by line
    require('minuet.virtualtext').action.accept_line,
    -- accept n lines (prompts for number)
    require('minuet.virtualtext').action.accept_n_lines,
    require('minuet.virtualtext').action.next,
    require('minuet.virtualtext').action.prev,
    require('minuet.virtualtext').action.dismiss,
    -- whether the virtual text is visible in current buffer
    require('minuet.virtualtext').action.is_visible,
}

Duet

The duet module provides functions to programmatically control duet prediction:

{
    require('minuet.duet').action.predict,
    require('minuet.duet').action.apply,
    require('minuet.duet').action.dismiss,
    -- Check if a duet preview is currently visible in the current buffer
    require('minuet.duet').action.is_visible,
}

Lualine

Minuet provides a Lualine component that displays the current status of Minuet requests. This component shows:

The name of the active provider and model
The current request count (e.g., "1/3")
An animated spinner while processing

To use the Minuet Lualine component, add it to your Lualine configuration:

require('lualine').setup {
    sections = {
        lualine_x = {
            {
                require 'minuet.lualine',
                -- the follwing is the default configuration
                -- the name displayed in the lualine. Set to "provider", "model" or "both"
                -- display_name = 'both',
                -- separator between provider and model name for option "both"
                -- provider_model_separator = ':',
                -- whether show display_name when no completion requests are active
                -- display_on_idle = false,
            },
            'encoding',
            'fileformat',
            'filetype',
        },
    },
}

Minuet Event

Standard Completion Events

MinuetRequestStartedPre: Triggered before a completion request is initiated. This allows for pre-request operations, such as logging or updating the user interface.
MinuetRequestStarted: Triggered immediately after the completion request is dispatched, signaling that the request is in progress.
MinuetRequestFinished: Triggered upon completion of the request.

Duet Events

MinuetDuetRequestStartedPre: Triggered before a duet request is initiated.
MinuetDuetRequestStarted: Triggered immediately after the duet request is dispatched.
MinuetDuetRequestFinished: Triggered upon completion of the duet request.

Event Data

Each event includes a data field containing the following properties:

provider: A string indicating the provider type (e.g., 'openai_compatible').
name: A string specifying the provider's name (e.g., 'OpenAI', 'Groq', 'Ollama').
model: A string containing the model name (e.g., 'gemini-2.0-flash').
n_requests: The number of requests encompassed in this completion cycle.
request_idx (optional): The index of the current request, applicable when providers make multiple requests.
timestamp: A Unix timestamp representing the start of the request cycle (corresponding to the MinuetRequestStartedPre event).

FAQ

Customize `cmp` ui for source icon and kind icon

You can configure the icons of completion items returned by minuet by using the following snippet (referenced from cmp's wiki):

local kind_icons = {
    Number = '󰎠',
    Array = '',
    Variable = '',
    -- and other icons
    -- LLM Provider icons
    claude = '󰋦',
    openai = '󱢆',
    codestral = '󱎥',
    gemini = '',
    Groq = '',
    Openrouter = '󱂇',
    Ollama = '󰳆',
    ['Llama.cpp'] = '󰳆',
    Deepseek = ''
    -- FALLBACK
    fallback = '',
}

local source_icons = {
    minuet = '󱗻',
    nvim_lsp = '',
    lsp = '',
    buffer = '',
    luasnip = '',
    snippets = '',
    path = '',
    git = '',
    tags = '',
    -- FALLBACK
    fallback = '󰜚',
}

local cmp = require 'cmp'
cmp.setup {
    formatting = {
        format = function(entry, vim_item)
            -- Kind icons
            -- This concatenates the icons with the name of the item kind
            vim_item.kind = string.format('%s %s', kind_icons[vim_item.kind] or kind_icons.fallback, vim_item.kind)
            -- Source
            vim_item.menu = source_icons[entry.source.name] or source_icons.fallback
            return vim_item
        end,
    },
}

Customize `blink` ui for source icon and kind icon

You can configure the icons of completion items returned by minuet by the following snippet:

To customize the kind icons:

local kind_icons = {
    -- LLM Provider icons
    claude = '󰋦',
    openai = '󱢆',
    codestral = '󱎥',
    gemini = '',
    Groq = '',
    Openrouter = '󱂇',
    Ollama = '󰳆',
    ['Llama.cpp'] = '󰳆',
    Deepseek = ''
}

require('blink-cmp').setup {
    appearance = {
        use_nvim_cmp_as_default = true,
        nerd_font_variant = 'normal',
        kind_icons = kind_icons
    },
}

To customize the source icons:

local source_icons = {
    minuet = '󱗻',
    orgmode = '',
    otter = '󰼁',
    nvim_lsp = '',
    lsp = '',
    buffer = '',
    luasnip = '',
    snippets = '',
    path = '',
    git = '',
    tags = '',
    cmdline = '󰘳',
    latex_symbols = '',
    cmp_nvim_r = '󰟔',
    codeium = '󰩂',
    -- FALLBACK
    fallback = '󰜚',
}

require('blink-cmp').setup {
    appearance = {
        use_nvim_cmp_as_default = true,
        nerd_font_variant = 'normal',
        kind_icons = kind_icons
    },
    completion = {
        menu = {
            draw = {
                columns = {
                    { 'label', 'label_description', gap = 1 },
                    { 'kind_icon', 'kind' },
                    { 'source_icon' },
                },
                components = {
                    source_icon = {
                        -- don't truncate source_icon
                        ellipsis = false,
                        text = function(ctx)
                            return source_icons[ctx.source_name:lower()] or source_icons.fallback
                        end,
                        highlight = 'BlinkCmpSource',
                    },
                },
            },
        },
    }
}

Significant Input Delay When Moving to a New Line with `nvim-cmp`

When using Minuet with auto-complete enabled, you may occasionally experience a noticeable delay when pressing <CR> to move to the next line. This occurs because Minuet triggers autocompletion at the start of a new line, while cmp blocks the <CR> key, awaiting Minuet's response.

To address this issue, consider the following solutions:

Unbind the <CR> key from your cmp keymap.
Utilize cmp's internal API to avoid blocking calls, though be aware that this API may change without prior notice.

Here's an example of the second approach using Lua:

local cmp = require 'cmp'
opts.mapping = {
    ['<CR>'] = cmp.mapping(function(fallback)
        -- use the internal non-blocking call to check if cmp is visible
        if cmp.core.view:visible() then
            cmp.confirm { select = true }
        else
            fallback()
        end
    end),
}

Integration with `lazyvim`

With nvim-cmp:

{
    'milanglacier/minuet-ai.nvim',
    config = function()
        require('minuet').setup {
            -- Your configuration options here
        }
    end
},
{
    'nvim-cmp',
    optional = true,
    opts = function(_, opts)
        -- if you wish to use autocomplete
        table.insert(opts.sources, 1, {
            name = 'minuet',
            group_index = 1,
            priority = 100,
        })

        opts.performance = {
            -- It is recommended to increase the timeout duration due to
            -- the typically slower response speed of LLMs compared to
            -- other completion sources. This is not needed when you only
            -- need manual completion.
            fetching_timeout = 2000,
        }

        opts.mapping = vim.tbl_deep_extend('force', opts.mapping or {}, {
            -- if you wish to use manual complete
            ['<A-y>'] = require('minuet').make_cmp_map(),
        })
    end,
}

With blink-cmp:

-- set the following line in your config/options.lua
vim.g.lazyvim_blink_main = true

{
    'milanglacier/minuet-ai.nvim',
    config = function()
        require('minuet').setup {
            -- Your configuration options here
        }
    end,
},
{
    'saghen/blink.cmp',
    optional = true,
    opts = {
        keymap = {
            ['<A-y>'] = {
                function(cmp)
                    cmp.show { providers = { 'minuet' } }
                end,
            },
        },
        sources = {
            -- if you want to use auto-complete
            default =  { 'minuet' },
            providers = {
                minuet = {
                    name = 'minuet',
                    module = 'minuet.blink',
                    score_offset = 100,
                },
            },
        },
    },
}

Enhancement

RAG (Experimental)

You can enhance the content sent to the LLM for code completion by leveraging RAG support through the VectorCode package.

VectorCode contains two main components. The first is a standalone CLI program written in Python, available for installation via PyPI. This program is responsible for creating the vector database and processing RAG queries. The second component is a Neovim plugin that provides utility functions to send queries and manage buffer-related RAG information within Neovim.

We offer two example recipes demonstrating VectorCode integration: one for chat-based LLMs (Gemini) and another for the FIM model (Qwen-2.5-Coder), available in recipes.md.

For detailed instructions on setting up and using VectorCode, please refer to the official VectorCode documentation.

Troubleshooting

If your setup failed, there are two most likely reasons:

You may set the API key incorrectly. Checkout the API Key section to see how to correctly specify the API key.
You are using a model or a context window that is too large, causing completion items to timeout before returning any tokens. This is particularly common with local LLM. It is recommended to start with the following settings to have a better understanding of your provider's inference speed.
- Begin by testing with manual completions.
- Use a smaller context window (e.g., config.context_window = 768)
- Use a smaller model
- Set a longer request timeout (e.g., config.request_timeout = 5)

To diagnose issues, set config.notify = debug and examine the output.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgement

cmp-ai: Reference for the integration with nvim-cmp.
continue.dev: not a neovim plugin, but I find a lot LLM models from here.
copilot.lua: Reference for the virtual text frontend.
llama.vim: Reference for CLI parameters used to launch the llama-cpp server.
crates.nvim: Reference for in-process LSP implemtation to provide completion.

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

overextended/ox_inventory

Slot-based inventory with metadata.

ox_inventory

A complete inventory system for FiveM, implementing items, weapons, shops, and more without any strict framework dependency.

📚 Documentation

https://overextended.dev/ox_inventory

💾 Download

https://github.com/overextended/ox_inventory/releases/latest/download/ox_inventory.zip

Supported frameworks

We do not guarantee compatibility or support for third-party resources.

✨ Features

Server-side security ensures interactions with items, shops, and stashes are all validated.
Logging for important events, such as purchases, item movement, and item creation or removal.
Supports player-owned vehicles, licenses, and group systems implemented by frameworks.
Fully synchronised, allowing multiple players to access the same inventory.

Items

Inventory items are stored per-slot, with customisable metadata to support item uniqueness.
Overrides default weapon-system with weapons as items.
Weapon attachments and ammo system, including special ammo types.
Durability, allowing items to be depleted or removed overtime.
Internal item system provides secure and easy handling for item use effects.
Compatibility with 3rd party framework item registration.

Shops

Restricted access based on groups and licenses.
Support different currency for items (black money, poker chips, etc).

Stashes

Personal stashes, linking a stash with a specific identifier or creating per-player instances.
Restricted access based on groups.
Registration of new stashes from any resource.
Containers allow access to stashes when using an item, like a paperbag or backpack.
Access gloveboxes and trunks for any vehicle.
Random item generation inside dumpsters and unowned vehicles.

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

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 2.3.0
    -- [Advanced setting]
    -- The registries to source system packages from. Accepts multiple entries. Should a package with the same name exist in
    -- multiple registries, the registry listed first will be used.
    system_registries = {
        "github:mason-org/mason-system-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 = {},
    },

    npm = {
        ---@since 2.3.0
        -- These args will be added to `npm install` calls. Note that setting extra args might impact intended behavior
        -- and is not recommended.
        --
        -- Example: { "--registry", "https://registry.npmjs.org/" }
        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!}

lewis6991/gitsigns.nvim

Git integration for buffers

gitsigns.nvim

Deep buffer integration for Git

👀 Preview

Hunk Actions	Line Blame

✨ Features

Signs

Adds signs to the sign column to indicate added, changed, and deleted lines.
Supports different signs for staged changes.
Add counts to signs.

Hunk Actions

Stage/unstage hunks with :Gitsigns stage_hunk.
Reset hunks with :Gitsigns reset_hunk.
Also works on partial hunks in visual mode.
Preview hunks inline with :Gitsigns preview_hunk_inline
Preview hunks in popup with :Gitsigns preview_hunk
Navigate between hunks with :Gitsigns nav_hunk next/prev.

Blame

Show blame of current buffer using :Gitsigns blame.
Show blame information for the current line in popup with :Gitsigns blame_line.
Show blame information for the current line in virtual text.
- Enable with setup({ current_line_blame = true }).
- Toggle with :Gitsigns toggle_current_line_blame

Diff

Change the revision for the signs with :Gitsigns change_base <REVISION>.
Show the diff of the current buffer with the index or any revision with :Gitsigns diffthis <REVISION>.
Show intra-line word-diff in the buffer.
- Enable with setup({ word_diff = true }).
- Toggle with :Gitsigns toggle_word_diff.

Show hunks Quickfix/Location List

Set the quickfix/location list with changes with :Gitsign setqflist/setloclist.

Can show hunks for:
- whole repository (target=all)
- attached buffers (target=attached)
- a specific buffer (target=[integer]).

Text Object

Select hunks as a text object.
Can use vim.keymap.set({'o', 'x'}, 'ih', '<Cmd>Gitsigns select_hunk<CR>')

Status Line Integration

Use b:gitsigns_status or b:gitsigns_status_dict. b:gitsigns_status is formatted using config.status_formatter. b:gitsigns_status_dict is a dictionary with the keys added, removed, changed and head.

Example:

set statusline+=%{get(b:,'gitsigns_status','')}

For the current branch use the variable b:gitsigns_head.

Show different revisions of buffers

Use :Gitsigns show <REVISION> to :edit the current buffer at <REVISION>

📋 Requirements

Neovim >= 0.9.0

Tip

If your version of Neovim is too old, then you can use a past release.

Warning

If you are running a development version of Neovim (aka master), then breakage may occur if your build is behind latest.

Newish version of git. Older versions may not work with some features.

🛠️ Installation & Usage

Install using your package manager of choice. No setup required.

Optional configuration can be passed to the setup function. Here is an example with most of the default settings:

require('gitsigns').setup {
  signs = {
    add          = { text = '┃' },
    change       = { text = '┃' },
    delete       = { text = '_' },
    topdelete    = { text = '‾' },
    changedelete = { text = '~' },
    untracked    = { text = '┆' },
  },
  signs_staged = {
    add          = { text = '┃' },
    change       = { text = '┃' },
    delete       = { text = '_' },
    topdelete    = { text = '‾' },
    changedelete = { text = '~' },
    untracked    = { text = '┆' },
  },
  signs_staged_enable = true,
  signcolumn = true,  -- Toggle with `:Gitsigns toggle_signs`
  numhl      = false, -- Toggle with `:Gitsigns toggle_numhl`
  linehl     = false, -- Toggle with `:Gitsigns toggle_linehl`
  word_diff  = false, -- Toggle with `:Gitsigns toggle_word_diff`
  watch_gitdir = {
    follow_files = true
  },
  auto_attach = true,
  attach_to_untracked = false,
  current_line_blame = false, -- Toggle with `:Gitsigns toggle_current_line_blame`
  current_line_blame_opts = {
    virt_text = true,
    virt_text_pos = 'eol', -- 'eol' | 'overlay' | 'right_align'
    delay = 1000,
    ignore_whitespace = false,
    virt_text_priority = 100,
    use_focus = true,
  },
  current_line_blame_formatter = '<author>, <author_time:%R> - <summary>',
  blame_formatter = nil, -- Use default
  sign_priority = 6,
  update_debounce = 100,
  status_formatter = nil, -- Use default
  max_file_length = 40000, -- Disable if file is longer than this (in lines)
  preview_config = {
    -- Options passed to nvim_open_win
    style = 'minimal',
    relative = 'cursor',
    row = 0,
    col = 1
  },
}

For information on configuring Neovim via lua please see nvim-lua-guide.

🎹 Keymaps

Gitsigns provides an on_attach callback which can be used to setup buffer mappings.

Here is a suggested example:

require('gitsigns').setup{
  ...
  on_attach = function(bufnr)
    local gitsigns = require('gitsigns')

    local function map(mode, l, r, opts)
      opts = opts or {}
      opts.buffer = bufnr
      vim.keymap.set(mode, l, r, opts)
    end

    -- Navigation
    map('n', ']c', function()
      if vim.wo.diff then
        vim.cmd.normal({']c', bang = true})
      else
        gitsigns.nav_hunk('next')
      end
    end)

    map('n', '[c', function()
      if vim.wo.diff then
        vim.cmd.normal({'[c', bang = true})
      else
        gitsigns.nav_hunk('prev')
      end
    end)

    -- Actions
    map('n', '<leader>hs', gitsigns.stage_hunk)
    map('n', '<leader>hr', gitsigns.reset_hunk)

    map('v', '<leader>hs', function()
      gitsigns.stage_hunk({ vim.fn.line('.'), vim.fn.line('v') })
    end)

    map('v', '<leader>hr', function()
      gitsigns.reset_hunk({ vim.fn.line('.'), vim.fn.line('v') })
    end)

    map('n', '<leader>hS', gitsigns.stage_buffer)
    map('n', '<leader>hR', gitsigns.reset_buffer)
    map('n', '<leader>hp', gitsigns.preview_hunk)
    map('n', '<leader>hi', gitsigns.preview_hunk_inline)

    map('n', '<leader>hb', function()
      gitsigns.blame_line({ full = true })
    end)

    map('n', '<leader>hd', gitsigns.diffthis)

    map('n', '<leader>hD', function()
      gitsigns.diffthis('~')
    end)

    map('n', '<leader>hQ', function() gitsigns.setqflist('all') end)
    map('n', '<leader>hq', gitsigns.setqflist)

    -- Toggles
    map('n', '<leader>tb', gitsigns.toggle_current_line_blame)
    map('n', '<leader>tw', gitsigns.toggle_word_diff)

    -- Text object
    map({'o', 'x'}, 'ih', gitsigns.select_hunk)
  end
}

🔗 Plugin Integrations

vim-fugitive

When viewing revisions of a file (via :0Gclog for example), Gitsigns will attach to the fugitive buffer with the base set to the commit immediately before the commit of that revision. This means the signs placed in the buffer reflect the changes introduced by that revision of the file.

trouble.nvim

If installed and enabled (via config.trouble; defaults to true if installed), :Gitsigns setqflist or :Gitsigns setloclist will open Trouble instead of Neovim's built-in quickfix or location list windows.

🚫 Non-Goals

Implement every feature in vim-fugitive

This plugin is actively developed and by one of the most well regarded vim plugin developers. Gitsigns will only implement features of this plugin if: it is simple, or, the technologies leveraged by Gitsigns (LuaJIT, Libuv, Neovim's API, etc) can provide a better experience.

Support for other VCS

There aren't any active developers of this plugin who use other kinds of VCS, so adding support for them isn't feasible. However a well written PR with a commitment of future support could change this.

🔌 Similar plugins

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

stevearc/conform.nvim

Lightweight yet powerful formatter plugin for Neovim

conform.nvim

Lightweight yet powerful formatter plugin for Neovim

Requirements

Neovim 0.10+ (for older versions, use a nvim-0.x branch)

Features

Preserves extmarks and folds - Most formatters replace the entire buffer, which clobbers extmarks and folds, and can cause the viewport and cursor to jump unexpectedly. Conform calculates minimal diffs and applies them using the built-in LSP format utilities.
Fixes bad-behaving LSP formatters - Some LSP servers are lazy and simply replace the entire buffer, leading to the problems mentioned above. Conform hooks into the LSP handler and turns these responses into proper piecewise changes.
Enables range formatting for all formatters - Since conform calculates minimal diffs, it can perform range formatting even if the underlying formatter doesn't support it.
Simple API - Conform exposes a simple, imperative API modeled after vim.lsp.buf.format().
Formats embedded code blocks - Can format code blocks inside markdown files or similar (see injected language formatting)

Installation

conform.nvim supports all the usual plugin managers

lazy.nvim

{
  'stevearc/conform.nvim',
  opts = {},
}

For a more thorough configuration involving lazy-loading, see Lazy loading with lazy.nvim.

Packer

require("packer").startup(function()
  use({
    "stevearc/conform.nvim",
    config = function()
      require("conform").setup()
    end,
  })
end)

Paq

require("paq")({
  { "stevearc/conform.nvim" },
})

vim-plug

Plug 'stevearc/conform.nvim'

dein

call dein#add('stevearc/conform.nvim')

Pathogen

git clone --depth=1 https://github.com/stevearc/conform.nvim.git ~/.vim/bundle/

Neovim native package

git clone --depth=1 https://github.com/stevearc/conform.nvim.git \
  "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/conform/start/conform.nvim

Setup

At a minimum, you will need to set up some formatters by filetype

require("conform").setup({
  formatters_by_ft = {
    lua = { "stylua" },
    -- Conform will run multiple formatters sequentially
    python = { "isort", "black" },
    -- You can customize some of the format options for the filetype (:help conform.format)
    rust = { "rustfmt", lsp_format = "fallback" },
    -- Conform will run the first available formatter
    javascript = { "prettierd", "prettier", stop_after_first = true },
  },
})

Then you can use conform.format() just like you would vim.lsp.buf.format(). For example, to format on save:

vim.api.nvim_create_autocmd("BufWritePre", {
  pattern = "*",
  callback = function(args)
    require("conform").format({ bufnr = args.buf })
  end,
})

As a shortcut, conform will optionally set up this format-on-save autocmd for you

require("conform").setup({
  format_on_save = {
    -- These options will be passed to conform.format()
    timeout_ms = 500,
    lsp_format = "fallback",
  },
})

See conform.format() for more details about the parameters.

Conform also provides a formatexpr, same as the LSP client:

vim.o.formatexpr = "v:lua.require'conform'.formatexpr()"

To view configured and available formatters, as well as to see the log file, run :ConformInfo

Formatters

You can view this list in vim with :help conform-formatters

Expand to see all formatters

air - R formatter and language server.
alejandra - The Uncompromising Nix Code Formatter.
ansible-lint - ansible-lint with --fix.
asmfmt - Go Assembler Formatter
ast-grep - A CLI tool for code structural search, lint and rewriting. Written in Rust.
astyle - A Free, Fast, and Small Automatic Formatter for C, C++, C++/CLI, Objective-C, C#, and Java Source Code.
auto_optional - Adds the Optional type-hint to arguments where the default value is None.
autocorrect - A linter and formatter to help you to improve copywriting, correct spaces, words, and punctuations between CJK.
autoflake - Removes unused imports and unused variables as reported by pyflakes.
autopep8 - A tool that automatically formats Python code to conform to the PEP 8 style guide.
bake - A Makefile formatter and linter.
bean-format - Reformat Beancount files to right-align all the numbers at the same, minimal column.
beautysh - A Bash beautifier for the masses.
bibtex-tidy - Cleaner and Formatter for BibTeX files.
bicep - Bicep is a Domain Specific Language (DSL) for deploying Azure resources declaratively.
biome - A toolchain for web projects, aimed to provide functionalities to maintain them. This config runs formatting only. See biome-check or biome-organize-imports for other options.
biome-check - A toolchain for web projects, aimed to provide functionalities to maintain them. This config runs formatting, linting and import sorting. See biome or biome-organize-imports for other options.
biome-organize-imports - A toolchain for web projects, aimed to provide functionalities to maintain them. This config runs import sorting only. See biome or biome-check for other options.
black - The uncompromising Python code formatter.
blade-formatter - An opinionated blade template formatter for Laravel that respects readability.
blue - The slightly less uncompromising Python code formatter.
bpfmt - Android Blueprint file formatter.
bsfmt - A code formatter for BrighterScript (and BrightScript).
buf - A new way of working with Protocol Buffers.
buildifier - buildifier is a tool for formatting bazel BUILD and .bzl files with a standard convention.
cabal_fmt - Format cabal files with cabal-fmt.
caramel_fmt - Format Caramel code.
cbfmt - A tool to format codeblocks inside markdown and org documents.
cedar - Formats cedar policies.
clang-format - Tool to format C/C++/… code according to a set of rules and heuristics.
cljfmt - cljfmt is a tool for detecting and fixing formatting errors in Clojure code.
cljstyle - Formatter for Clojure code.
cmake_format - Parse cmake listfiles and format them nicely.
codeql - Format queries and libraries with CodeQL.
codespell - Check code for common misspellings.
commitmsgfmt - Formats commit messages better than fmt(1) and Vim.
crlfmt - Formatter for CockroachDB's additions to the Go style guide.
crystal - Format Crystal code.
csharpier - The opinionated C# code formatter.
css_beautify - Beautifier for css.
cue_fmt - Format CUE files using cue fmt command.
d2 - D2 is a modern diagram scripting language that turns text to diagrams.
darker - Run black only on changed lines.
dart_format - Replace the whitespace in your program with formatting that follows Dart guidelines.
dcm_fix - Fixes issues produced by dcm analyze, dcm check-unused-code or dcm check-dependencies commands.
dcm_format - Formats .dart files.
deno_fmt - Use Deno to format TypeScript, JavaScript/JSON and markdown.
dfmt - Formatter for D source code.
dioxus - Format rsx! snippets in Rust files.
djlint - ✨ HTML Template Linter and Formatter. Django - Jinja - Nunjucks - Handlebars - GoLang.
docformatter - docformatter automatically formats docstrings to follow a subset of the PEP 257 conventions.
dockerfmt - Dockerfile formatter. a modern dockfmt.
docstrfmt - reStructuredText formatter.
doctoc - Generates table of contents for markdown files inside local git repository.
dprint - Pluggable and configurable code formatting platform written in Rust.
easy-coding-standard - ecs - Use Coding Standard with 0-knowledge of PHP-CS-Fixer and PHP_CodeSniffer.
efmt - Erlang code formatter.
elm_format - elm-format formats Elm source code according to a standard set of rules based on the official Elm Style Guide.
erb_format - Format ERB files with speed and precision.
erlfmt - An automated code formatter for Erlang.
eslint_d - Like ESLint, but faster.
fantomas - F# source code formatter.
findent - Indent, relabel and convert Fortran sources.
fish_indent - Indent or otherwise prettify a piece of fish code.
fixjson - JSON Fixer for Humans using (relaxed) JSON5.
fnlfmt - A formatter for Fennel code.
forge_fmt - Forge is a command-line tool that ships with Foundry. Forge tests, builds, and deploys your smart contracts.
format-dune-file - Auto-formatter for Dune files.
fourmolu - A fork of ormolu that uses four space indentation and allows arbitrary configuration.
fprettify - Auto-formatter for modern fortran source code.
gawk - Format awk programs with gawk.
gci - GCI, a tool that controls Go package import order and makes it always deterministic.
gdformat - A formatter for Godot's gdscript.
gdscript-formatter - A faster code formatter for GDScript and Godot 4.
gersemi - A formatter to make your CMake code the real treasure.
ghdl - Open-source analyzer, compiler, simulator and synthesizer for VHDL.
ghokin - Parallelized formatter with no external dependencies for gherkin.
gleam - ⭐️ A friendly language for building type-safe, scalable systems!
gluon_fmt - Code formatting for the gluon programming language.
gn - gn build system.
gofmt - Formats go programs.
gofumpt - Enforce a stricter format than gofmt, while being backwards compatible. That is, gofumpt is happy with a subset of the formats that gofmt is happy with.
goimports - Updates your Go import lines, adding missing ones and removing unreferenced ones.
goimports-reviser - Right imports sorting & code formatting tool (goimports alternative).
gojq - Pure Go implementation of jq.
golangci-lint - Fast linters runner for Go (with formatter).
golines - A golang formatter that fixes long lines.
google-java-format - Reformats Java source code according to Google Java Style.
grain_format - Code formatter for the grain programming language.
hcl - A formatter for HCL files.
hindent - Haskell pretty printer.
hledger-fmt - An opinionated hledger's journal files formatter.
html_beautify - Beautifier for html.
htmlbeautifier - A normaliser/beautifier for HTML that also understands embedded Ruby. Ideal for tidying up Rails templates.
hurlfmt - Formats hurl files.
imba_fmt - Code formatter for the Imba programming language.
indent - GNU Indent.
injected - Format treesitter injected languages.
inko - A language for building concurrent software with confidence
isort - Python utility / library to sort imports alphabetically and automatically separate them into sections and by type.
janet-format - A formatter for Janet code.
joker - Small Clojure interpreter, linter and formatter.
jq - Command-line JSON processor.
js_beautify - Beautifier for javascript.
json_repair - A python module to repair invalid JSON from LLMs.
jsonnetfmt - jsonnetfmt is a command line tool to format jsonnet files.
just - Format Justfile.
kcl - The KCL Format tool modifies the files according to the KCL code style.
kdlfmt - A formatter for kdl documents.
keep-sorted - keep-sorted is a language-agnostic formatter that sorts lines between two markers in a larger file.
ktfmt - Reformats Kotlin source code to comply with the common community standard conventions.
ktlint - An anti-bikeshedding Kotlin linter with built-in formatter.
kulala-fmt - An opinionated .http and .rest files linter and formatter.
latexindent - A perl script for formatting LaTeX files that is generally included in major TeX distributions.
leptosfmt - A formatter for the Leptos view! macro.
liquidsoap-prettier - A binary to format Liquidsoap scripts
llf - A LaTeX reformatter / beautifier.
lua-format - Code formatter for Lua.
mago_format - Mago is a toolchain for PHP that aims to provide a set of tools to help developers write better code.
mago_lint - Mago is a toolchain for PHP that aims to provide a set of tools to help developers write better code.
markdown-toc - API and CLI for generating a markdown TOC (table of contents) for a README or any markdown files.
markdownfmt - Like gofmt, but for Markdown.
markdownlint - A Node.js style checker and lint tool for Markdown/CommonMark files.
markdownlint-cli2 - A fast, flexible, configuration-based command-line interface for linting Markdown/CommonMark files with the markdownlint library.
mdformat - An opinionated Markdown formatter.
mdsf - Format markdown code blocks using your favorite code formatters.
mdslw - Prepare your markdown for easy diff'ing by adding line breaks after every sentence.
meson - Format meson source files.
mh_style - A simple coding style checker and code formatter for MATLAB or Octave code.
mix - Format Elixir files using the mix format command.
mojo_format - Official Formatter for The Mojo Programming Language
nginxfmt - nginx config file formatter/beautifier written in Python with no additional dependencies.
nickel - Code formatter for the Nickel programming language.
nimpretty - nimpretty is a Nim source code beautifier that follows the official style guide.
nixfmt - The official formatter for Nix code.
nixpkgs_fmt - nixpkgs-fmt is a Nix code formatter for nixpkgs.
nomad_fmt - The fmt commands check the syntax and rewrites Nomad configuration and jobspec files to canonical format.
nph - An opinionated code formatter for Nim.
npm-groovy-lint - Lint, format and auto-fix your Groovy / Jenkinsfile / Gradle files using command line.
nufmt - The nushell formatter.
ocamlformat - Auto-formatter for OCaml code.
ocp-indent - Automatic indentation of OCaml source files.
odinfmt - Auto-formatter for the Odin programming language.
opa_fmt - Format Rego files using opa fmt command.
openapi-format - Format an OpenAPI document by ordering, formatting and filtering fields.
ormolu - A formatter for Haskell source code.
oxfmt - A Prettier-compatible code formatter.
oxlint - An oxidized replacement for ESLint that fixes lint errors.
packer_fmt - The packer fmt Packer command is used to format HCL2 configuration files to a canonical format and style.
palantir-java-format - A modern, lambda-friendly, 120 character Java formatter.
panache - A formatter, linter, and language server for Markdown, Quarto, and R Markdown.
panache-fix - Linter for Markdown, Quarto, and R Markdown. Applies auto-fixable rule violations.
pangu - Insert whitespace between CJK and half-width characters.
pasfmt - Delphi code formatter.
perlimports - Make implicit Perl imports explicit.
perltidy - Perl::Tidy, a source code formatter for Perl.
pg_format - PostgreSQL SQL syntax beautifier.
php_cs_fixer - The PHP Coding Standards Fixer.
phpcbf - PHP Code Beautifier and Fixer fixes violations of a defined coding standard.
phpinsights - The perfect starting point to analyze the code quality of your PHP projects.
pint - Laravel Pint is an opinionated PHP code style fixer for minimalists.
pkl - Official canonical formatter for Pkl.
prettier - Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary.
prettierd - prettier, as a daemon, for ludicrous formatting speed.
pretty-php - The opinionated PHP code formatter.
prettypst - Formatter for Typst.
prolog - Language Server Protocol server and formatter for SWI-Prolog.
pruner - A language-agnostic, treesitter powered formatter.
puppet-lint - Check that your Puppet manifests conform to the style guide.
purs-tidy - A syntax tidy-upper for PureScript.
pycln - A Python formatter for finding and removing unused import statements.
pyink - A Python formatter, forked from Black with a few different formatting behaviors.
pymarkdownlnt - A markdown linter and formatter.
pyproject-fmt - Apply a consistent format to your pyproject.toml file with comment support.
python-ly - A Python package and commandline tool to manipulate LilyPond files.
pyupgrade - A tool to automatically upgrade syntax for newer versions of Python.
qmlformat - A tool that automatically formats QML files.
racketfmt - Racket language formatter.
reformat-gherkin - Formatter for Gherkin language.
reorder-python-imports - Rewrites source to reorder python imports
rescript-format - The built-in ReScript formatter.
roc - A fast, friendly, functional language.
rstfmt - A formatter for reStructuredText.
rubocop - Ruby static code analyzer and formatter, based on the community Ruby style guide.
rubyfmt - Ruby Autoformatter! (Written in Rust)
ruff_fix - An extremely fast Python linter, written in Rust. Fix lint errors.
ruff_format - An extremely fast Python linter, written in Rust. Formatter subcommand.
ruff_organize_imports - An extremely fast Python linter, written in Rust. Organize imports.
rufo - Rufo is an opinionated ruby formatter.
rumdl - Markdown Linter and Formatter written in Rust.
runic - Julia code formatter.
rustfmt - A tool for formatting rust code according to style guidelines.
rustywind - A tool for formatting Tailwind CSS classes.
scalafmt - Code formatter for Scala.
shellcheck - A static analysis tool for shell scripts.
shellharden - The corrective bash syntax highlighter.
shfmt - A shell parser, formatter, and interpreter with bash support.
sleek - Sleek is a CLI tool for formatting SQL.
smlfmt - A custom parser and code formatter for Standard ML.
snakefmt - a formatting tool for Snakemake files following the design of Black.
spotless_gradle - Spotless plugin for Gradle.
spotless_maven - Spotless plugin for Maven.
sql_formatter - A whitespace formatter for different query languages.
sqlfluff - A modular SQL linter and auto-formatter with support for multiple dialects and templated code.
sqlfmt - sqlfmt formats your dbt SQL files so you don't have to. It is similar in nature to Black, gofmt, and rustfmt (but for SQL)
sqruff - sqruff is a SQL linter and formatter written in Rust.
squeeze_blanks - Squeeze repeated blank lines into a single blank line via cat -s.
standard-clj - A JavaScript library to format Clojure code according to Standard Clojure Style.
standardjs - JavaScript Standard style guide, linter, and formatter.
standardrb - Ruby's bikeshed-proof linter and formatter.
stylelint - A mighty CSS linter that helps you avoid errors and enforce conventions.
styler - R formatter and linter.
stylish-haskell - Haskell code prettifier.
stylua - An opinionated code formatter for Lua.
superhtml - HTML Language Server and Templating Language Library.
swift - Official Swift formatter. Requires Swift 6.0 or later.
swift_format - Official Swift formatter. For Swift 6.0 or later prefer setting the swift formatter instead.
swiftformat - SwiftFormat is a code library and command-line tool for reformatting swift code on macOS or Linux.
swiftlint - A tool to enforce Swift style and conventions.
syntax_tree - Syntax Tree is a suite of tools built on top of the internal CRuby parser.
taplo - A TOML toolkit written in Rust.
tclfmt - A formatter for Tcl scripts, part of the tclint project.
templ - Formats templ template files.
terraform_fmt - The terraform-fmt command rewrites terraform configuration files to a canonical format and style.
terragrunt_hclfmt - Format hcl files into a canonical format.
tex-fmt - An extremely fast LaTeX formatter written in Rust.
tlint - Tighten linter for Laravel conventions with support for auto-formatting.
tofu_fmt - The tofu-fmt command rewrites OpenTofu configuration files to a canonical format and style.
tombi - TOML Formatter / Linter.
treefmt - one CLI to format your repo.
trim_newlines - Trim empty lines at the end of the file.
trim_whitespace - Trim trailing whitespace.
trunk - Trunk universal formatter.
twig-cs-fixer - Automatically fix Twig Coding Standards issues
txtpbfmt - txtpbfmt parses, edits and formats text proto files in a way that preserves comments.
typespec - TypeSpec compiler and CLI.
typos - Source code spell checker
typstyle - Beautiful and reliable typst code formatter.
ufmt - Safe, atomic formatting with black and µsort.
uncrustify - A source code beautifier for C, C++, C#, ObjectiveC, D, Java, Pawn and Vala.
usort - Safe, minimal import sorting for Python projects.
v - V language formatter.
verible - The SystemVerilog formatter.
vsg - Style guide enforcement for VHDL.
xmlformatter - xmlformatter is an Open Source Python package, which provides formatting of XML documents.
xmllint - Despite the name, xmllint can be used to format XML files as well as lint them.
xmlstarlet - XMLStarlet is a command-line XML toolkit that can be used to format XML files.
yamlfix - A configurable YAML formatter that keeps comments.
yamlfmt - yamlfmt is an extensible command line tool or library to format yaml files.
yapf - Yet Another Python Formatter.
yew-fmt - Code formatter for the Yew framework.
yq - YAML/JSON processor
zigfmt - Reformat Zig source into canonical form.
ziggy - A data serialization language for expressing clear API messages, config files, etc.
ziggy_schema - A data serialization language for expressing clear API messages, config files, etc.
zprint - Formatter for Clojure and EDN.

Customizing formatters

You can override/add to the default values of formatters

require("conform").setup({
  formatters = {
    yamlfix = {
      -- Change where to find the command
      command = "local/path/yamlfix",
      -- Adds environment args to the yamlfix formatter
      env = {
        YAMLFIX_SEQUENCE_STYLE = "block_style",
      },
    },
  },
})

-- These can also be set directly
require("conform").formatters.yamlfix = {
  env = {
    YAMLFIX_SEQUENCE_STYLE = "block_style",
  },
}

-- This can also be a function that returns the config,
-- which can be useful if you're doing lazy loading
require("conform").formatters.yamlfix = function(bufnr)
  return {
    command = require("conform.util").find_executable({
      "local/path/yamlfix",
    }, "yamlfix"),
  }
end

In addition to being able to override any of the original properties on the formatter, there is another property for easily adding additional arguments to the format command

require("conform").formatters.shfmt = {
  append_args = { "-i", "2" },
  -- The base args are { "-filename", "$FILENAME" } so the final args will be
  -- { "-filename", "$FILENAME", "-i", "2" }
}
-- append_args can be a function, just like args
require("conform").formatters.shfmt = {
  append_args = function(self, ctx)
    return { "-i", "2" }
  end,
}

If you want to overwrite the entire formatter definition and not merge with the default values, pass inherit = false. This is also the default behavior if there is no built-in formatter with the given name, which can be used to add your own custom formatters.

require("conform").formatters.shfmt = {
  inherit = false,
  command = "shfmt",
  args = { "-filename", "$FILENAME", "-i", "2" },
}

You can also specify which formatter to inherit from. This can be useful if you want to define multiple variants of a single formatter with slightly different options.

require("conform").formatters.deno_fmt_markdown = {
  inherit = "deno_fmt",
  append_args = { "--indent-width", "4" },
}

Magic strings

The following magic strings are available in args and range_args. They will be dynamically replaced at runtime with the relevant value.

$FILENAME - absolute path to the file
$DIRNAME - absolute path to the directory that contains the file
$RELATIVE_FILEPATH - relative path to the file
$EXTENSION - the file extension, e.g. .py

Recipes

Debugging

Advanced topics

Options

A complete list of all configuration options

require("conform").setup({
  -- Map of filetype to formatters
  formatters_by_ft = {
    lua = { "stylua" },
    -- Conform will run multiple formatters sequentially
    go = { "goimports", "gofmt" },
    -- You can also customize some of the format options for the filetype
    rust = { "rustfmt", lsp_format = "fallback" },
    -- You can use a function here to determine the formatters dynamically
    python = function(bufnr)
      if require("conform").get_formatter_info("ruff_format", bufnr).available then
        return { "ruff_format" }
      else
        return { "isort", "black" }
      end
    end,
    -- Use the "*" filetype to run formatters on all filetypes.
    ["*"] = { "codespell" },
    -- Use the "_" filetype to run formatters on filetypes that don't
    -- have other formatters configured.
    ["_"] = { "trim_whitespace" },
  },
  -- Set this to change the default values when calling conform.format()
  -- This will also affect the default values for format_on_save/format_after_save
  default_format_opts = {
    lsp_format = "fallback",
  },
  -- If this is set, Conform will run the formatter on save.
  -- It will pass the table to conform.format().
  -- This can also be a function that returns the table.
  format_on_save = {
    -- I recommend these options. See :help conform.format for details.
    lsp_format = "fallback",
    timeout_ms = 500,
  },
  -- If this is set, Conform will run the formatter asynchronously after save.
  -- It will pass the table to conform.format().
  -- This can also be a function that returns the table.
  format_after_save = {
    lsp_format = "fallback",
  },
  -- Set the log level. Use `:ConformInfo` to see the location of the log file.
  log_level = vim.log.levels.ERROR,
  -- Conform will notify you when a formatter errors
  notify_on_error = true,
  -- Conform will notify you when no formatters are available for the buffer
  notify_no_formatters = true,
  -- Custom formatters and overrides for built-in formatters
  formatters = {
    my_formatter = {
      -- This can be a string or a function that returns a string.
      -- When defining a new formatter, this is the only field that is required
      command = "my_cmd",
      -- A list of strings, or a function that returns a list of strings
      -- Return a single string instead of a list to run the command in a shell
      args = { "--stdin-from-filename", "$FILENAME" },
      -- If the formatter supports range formatting, create the range arguments here
      range_args = function(self, ctx)
        return { "--line-start", ctx.range.start[1], "--line-end", ctx.range["end"][1] }
      end,
      -- Send file contents to stdin, read new contents from stdout (default true)
      -- When false, will create a temp file (will appear in "$FILENAME" args). The temp
      -- file is assumed to be modified in-place by the format command.
      stdin = true,
      -- A function that calculates the directory to run the command in
      cwd = require("conform.util").root_file({ ".editorconfig", "package.json" }),
      -- When cwd is not found, don't run the formatter (default false)
      require_cwd = true,
      -- When stdin=false, use this template to generate the temporary file that gets formatted
      tmpfile_format = ".conform.$RANDOM.$FILENAME",
      -- When returns false, the formatter will not be used
      condition = function(self, ctx)
        return vim.fs.basename(ctx.filename) ~= "README.md"
      end,
      -- Exit codes that indicate success (default { 0 })
      exit_codes = { 0, 1 },
      -- Environment variables. This can also be a function that returns a table.
      env = {
        VAR = "value",
      },
      -- Set to false to disable merging the config with the base definition.
      -- Can also be set to the name of the formatter to merge with (e.g. inherit = "black")
      inherit = true,
      -- When inherit = true, add these additional arguments to the beginning of the command.
      -- This can also be a function, like args
      prepend_args = { "--use-tabs" },
      -- When inherit = true, add these additional arguments to the end of the command.
      -- This can also be a function, like args
      append_args = { "--trailing-comma" },
    },
    -- These can also be a function that returns the formatter
    other_formatter = function(bufnr)
      return {
        command = "my_cmd",
      }
    end,
  },
})

-- You can set formatters_by_ft and formatters directly
require("conform").formatters_by_ft.lua = { "stylua" }
require("conform").formatters.my_formatter = {
  command = "my_cmd",
}

Formatter options

API

setup(opts)

setup(opts)

Param	Type	Desc
opts	`nil\|conform.setupOpts`
>formatters_by_ft	`nil\|table<string, conform.FiletypeFormatter>`	Map of filetype to formatters
>format_on_save	`nil\|conform.FormatOpts\|fun(bufnr: integer): nil\|conform.FormatOpts`	If this is set, Conform will run the formatter on save. It will pass the table to conform.format(). This can also be a function that returns the table.
>default_format_opts	`nil\|conform.DefaultFormatOpts`	The default options to use when calling conform.format()
>>timeout_ms	`nil\|integer`	Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true.
>>lsp_format	`nil\|conform.LspFormatOpts`	Configure if and when LSP should be used for formatting. Defaults to "never".
	`"never"`	never use the LSP for formatting (default)
	`"fallback"`	LSP formatting is used when no other formatters are available
	`"prefer"`	use only LSP formatting when available
	`"first"`	LSP formatting is used when available and then other formatters
	`"last"`	other formatters are used then LSP formatting when available
>>quiet	`nil\|boolean`	Don't show any notifications for warnings or failures. Defaults to false.
>>stop_after_first	`nil\|boolean`	Only run the first available formatter in the list. Defaults to false.
>format_after_save	`nil\|conform.FormatOpts\|fun(bufnr: integer): nil\|conform.FormatOpts`	, nil
>log_level	`nil\|integer`	Set the log level (e.g. `vim.log.levels.DEBUG`). Use `:ConformInfo` to see the location of the log file.
>notify_on_error	`nil\|boolean`	Conform will notify you when a formatter errors (default true).
>notify_no_formatters	`nil\|boolean`	Conform will notify you when no formatters are available for the buffer (default true).
>formatters	`nil\|table<string, conform.FormatterConfigOverride\|fun(bufnr: integer): nil\|conform.FormatterConfigOverride>`	Custom formatters and overrides for built-in formatters.

format(opts, callback)

format(opts, callback): boolean
Format a buffer

Param	Type	Desc
opts	`nil\|conform.FormatOpts`
>timeout_ms	`nil\|integer`	Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true.
>bufnr	`nil\|integer`	Format this buffer (default 0)
>async	`nil\|boolean`	If true the method won't block. Defaults to false. If the buffer is modified before the formatter completes, the formatting will be discarded.
>dry_run	`nil\|boolean`	If true don't apply formatting changes to the buffer
>undojoin	`nil\|boolean`	Use undojoin to merge formatting changes with previous edit (default false)
>formatters	`nil\|string[]`	List of formatters to run. Defaults to all formatters for the buffer filetype.
>lsp_format	`nil\|conform.LspFormatOpts`	Configure if and when LSP should be used for formatting. Defaults to "never".
	`"never"`	never use the LSP for formatting (default)
	`"fallback"`	LSP formatting is used when no other formatters are available
	`"prefer"`	use only LSP formatting when available
	`"first"`	LSP formatting is used when available and then other formatters
	`"last"`	other formatters are used then LSP formatting when available
>stop_after_first	`nil\|boolean`	Only run the first available formatter in the list. Defaults to false.
>quiet	`nil\|boolean`	Don't show any notifications for warnings or failures. Defaults to false.
>range	`nil\|conform.Range`	Range to format. Table must contain `start` and `end` keys with {row, col} tuples using (1,0) indexing. Defaults to current selection in visual mode
>>start	`integer[]`
>>end	`integer[]`
>id	`nil\|integer`	Passed to vim.lsp.buf.format when using LSP formatting
>name	`nil\|string`	Passed to vim.lsp.buf.format when using LSP formatting
>filter	`nil\|fun(client: table): boolean`	Passed to vim.lsp.buf.format when using LSP formatting
>formatting_options	`nil\|table`	Passed to vim.lsp.buf.format when using LSP formatting
callback	`nil\|fun(err: nil\|string, did_edit: nil\|boolean)`	Called once formatting has completed

Returns:

Type	Desc
boolean	True if any formatters were attempted

Examples:

-- Synchronously format the current buffer
conform.format({ lsp_format = "fallback" })
-- Asynchronously format the current buffer; will not block the UI
conform.format({ async = true }, function(err, did_edit)
  -- called after formatting
end)
-- Format the current buffer with a specific formatter
conform.format({ formatters = { "ruff_fix" } })

list_formatters(bufnr)

list_formatters(bufnr): conform.FormatterInfo[]
Retrieve the available formatters for a buffer

Param	Type	Desc
bufnr	`nil\|integer`

list_formatters_to_run(bufnr)

list_formatters_to_run(bufnr): conform.FormatterInfo[], boolean
Get the exact formatters that will be run for a buffer.

Param	Type	Desc
bufnr	`nil\|integer`

Returns:

Type	Desc
conform.FormatterInfo[]
boolean	lsp Will use LSP formatter

Note:

This accounts for stop_after_first, lsp fallback logic, etc.

list_all_formatters()

list_all_formatters(): conform.FormatterInfo[]
List information about all filetype-configured formatters

get_formatter_info(formatter, bufnr)

get_formatter_info(formatter, bufnr): conform.FormatterInfo
Get information about a formatter (including availability)

Param	Type	Desc
formatter	`string`	The name of the formatter
bufnr	`nil\|integer`

FAQ

Q: Instead of passing lsp_format = "...", could you just define a lsp formatter?
A: No. #61

Q: Is it possible to define a custom formatter that runs a lua function?
A: Yes, but with some very strict constraints. #653

Q: Can I run a command like :EslintFixAll or a LSP code action as a formatter?
A: No. #502, #466, #222

Acknowledgements

Thanks to

nvim-lint for providing inspiration for the config and API. It's an excellent plugin that balances power and simplicity.
null-ls for formatter configurations and being my formatter/linter of choice for a long time.

coder/claudecode.nvim

🧩 Claude Code Neovim IDE Extension

claudecode.nvim

The first Neovim IDE integration for Claude Code — bringing Anthropic's AI coding assistant to your favorite editor with a pure Lua implementation.

🎯 TL;DR: When Anthropic released Claude Code with VS Code and JetBrains support, I reverse-engineered their extension and built this Neovim plugin. This plugin implements the same WebSocket-based MCP protocol, giving Neovim users the same AI-powered coding experience.

https://github.com/user-attachments/assets/9c310fb5-5a23-482b-bedc-e21ae457a82d

What Makes This Special

When Anthropic released Claude Code, they only supported VS Code and JetBrains. As a Neovim user, I wanted the same experience — so I reverse-engineered their extension and built this.

🚀 Pure Lua, Zero Dependencies — Built entirely with vim.loop and Neovim built-ins
🔌 100% Protocol Compatible — Same WebSocket MCP implementation as official extensions
🎓 Fully Documented Protocol — Learn how to build your own integrations (see PROTOCOL.md)
⚡ First to Market — Beat Anthropic to releasing Neovim support
🛠️ Built with AI — Used Claude to reverse-engineer Claude's own protocol

Installation

{
  "coder/claudecode.nvim",
  dependencies = { "folke/snacks.nvim" },
  config = true,
  keys = {
    { "<leader>a", nil, desc = "AI/Claude Code" },
    { "<leader>ac", "<cmd>ClaudeCode<cr>", desc = "Toggle Claude" },
    { "<leader>af", "<cmd>ClaudeCodeFocus<cr>", desc = "Focus Claude" },
    { "<leader>ar", "<cmd>ClaudeCode --resume<cr>", desc = "Resume Claude" },
    { "<leader>aC", "<cmd>ClaudeCode --continue<cr>", desc = "Continue Claude" },
    { "<leader>am", "<cmd>ClaudeCodeSelectModel<cr>", desc = "Select Claude model" },
    { "<leader>ab", "<cmd>ClaudeCodeAdd %<cr>", desc = "Add current buffer" },
    { "<leader>as", "<cmd>ClaudeCodeSend<cr>", mode = "v", desc = "Send to Claude" },
    {
      "<leader>as",
      "<cmd>ClaudeCodeTreeAdd<cr>",
      desc = "Add file",
      ft = { "NvimTree", "neo-tree", "oil", "minifiles", "netrw" },
    },
    -- Diff management
    { "<leader>aa", "<cmd>ClaudeCodeDiffAccept<cr>", desc = "Accept diff" },
    { "<leader>ad", "<cmd>ClaudeCodeDiffDeny<cr>", desc = "Deny diff" },
  },
}

That's it! The plugin will auto-configure everything else.

Requirements

Neovim >= 0.8.0
Claude Code CLI installed
folke/snacks.nvim for enhanced terminal support

Local Installation Configuration

If you've used Claude Code's migrate-installer command to move to a local installation, you'll need to configure the plugin to use the local path.

What is a Local Installation?

Claude Code offers a claude migrate-installer command that:

Moves Claude Code from a global npm installation to ~/.claude/local/
Avoids permission issues with system directories
Creates shell aliases but these may not be available to Neovim

Detecting Your Installation Type

Check your installation type:

# Check where claude command points
which claude

# Global installation shows: /usr/local/bin/claude (or similar)
# Local installation shows: alias to ~/.claude/local/claude

# Verify installation health
claude doctor

Configuring for Local Installation

If you have a local installation, configure the plugin with the direct path:

{
  "coder/claudecode.nvim",
  dependencies = { "folke/snacks.nvim" },
  opts = {
    terminal_cmd = "~/.claude/local/claude", -- Point to local installation
  },
  config = true,
  keys = {
    -- Your keymaps here
  },
}

Native Binary Installation (Alpha)

Claude Code also offers an experimental native binary installation method currently in alpha testing. This provides a single executable with no Node.js dependencies.

Installation Methods

Install the native binary using one of these methods:

# Fresh install (recommended)
curl -fsSL claude.ai/install.sh | bash

# From existing Claude Code installation
claude install

Platform Support

macOS: Full support for Intel and Apple Silicon
Linux: x64 and arm64 architectures
Windows: Via WSL (Windows Subsystem for Linux)

Benefits

Zero Dependencies: Single executable file with no external requirements
Cross-Platform: Consistent experience across operating systems
Secure Installation: Includes checksum verification and automatic cleanup

Configuring for Native Binary

The exact binary path depends on your shell integration. To find your installation:

# Check where claude command points
which claude

# Verify installation type and health
claude doctor

Configure the plugin with the detected path:

{
  "coder/claudecode.nvim",
  dependencies = { "folke/snacks.nvim" },
  opts = {
    terminal_cmd = "/path/to/your/claude", -- Use output from 'which claude'
  },
  config = true,
  keys = {
    -- Your keymaps here
  },
}

Note: If Claude Code was installed globally via npm, you can use the default configuration without specifying terminal_cmd.

Quick Demo

" Launch Claude Code in a split
:ClaudeCode

" Claude now sees your current file and selections in real-time!

" Send visual selection as context
:'<,'>ClaudeCodeSend

" Claude can open files, show diffs, and more

Usage

Launch Claude: Run :ClaudeCode to open Claude in a split terminal
Send context:
- Select text in visual mode and use <leader>as to send it to Claude
- In nvim-tree/neo-tree/oil.nvim/mini.nvim, press <leader>as on a file to add it to Claude's context
Let Claude work: Claude can now:
- See your current file and selections in real-time
- Open files in your editor
- Show diffs with proposed changes
- Access diagnostics and workspace info

Key Commands

:ClaudeCode - Toggle the Claude Code terminal window
:ClaudeCodeFocus - Smart focus/toggle Claude terminal
:ClaudeCodeSelectModel - Select Claude model and open terminal with optional arguments
:ClaudeCodeSend - Send current visual selection to Claude
:ClaudeCodeAdd <file-path> [start-line] [end-line] - Add specific file to Claude context with optional line range
:ClaudeCodeDiffAccept - Accept diff changes
:ClaudeCodeDiffDeny - Reject diff changes

Working with Diffs

When Claude proposes changes, the plugin opens a native Neovim diff view:

Accept: :w (save) or <leader>aa
Reject: :q or <leader>ad

You can edit Claude's suggestions before accepting them.

How It Works

This plugin creates a WebSocket server that Claude Code CLI connects to, implementing the same protocol as the official VS Code extension. When you launch Claude, it automatically detects Neovim and gains full access to your editor.

The protocol uses a WebSocket-based variant of MCP (Model Context Protocol) that:

Creates a WebSocket server on a random port
Writes a lock file to ~/.claude/ide/[port].lock (or $CLAUDE_CONFIG_DIR/ide/[port].lock if CLAUDE_CONFIG_DIR is set) with connection info
Sets environment variables that tell Claude where to connect
Implements MCP tools that Claude can call

📖 Read the full reverse-engineering story → 🔧 Complete protocol documentation →

Architecture

Built with pure Lua and zero external dependencies:

WebSocket Server - RFC 6455 compliant implementation using vim.loop
MCP Protocol - Full JSON-RPC 2.0 message handling
Lock File System - Enables Claude CLI discovery
Selection Tracking - Real-time context updates
Native Diff Support - Seamless file comparison

For deep technical details, see ARCHITECTURE.md.

Advanced Configuration

{
  "coder/claudecode.nvim",
  dependencies = { "folke/snacks.nvim" },
  opts = {
    -- Server Configuration
    port_range = { min = 10000, max = 65535 },
    auto_start = true,
    log_level = "info", -- "trace", "debug", "info", "warn", "error"
    terminal_cmd = nil, -- Custom terminal command (default: "claude")
                        -- For local installations: "~/.claude/local/claude"
                        -- For native binary: use output from 'which claude'

    -- Send/Focus Behavior
    -- When true, successful sends will focus the Claude terminal if already connected
    focus_after_send = false,

    -- Selection Tracking
    track_selection = true,
    visual_demotion_delay_ms = 50,

    -- Terminal Configuration
    terminal = {
      split_side = "right", -- "left" or "right"
      split_width_percentage = 0.30,
      provider = "auto", -- "auto", "snacks", "native", "external", "none", or custom provider table
      auto_close = true,
      snacks_win_opts = {}, -- Opts to pass to `Snacks.terminal.open()` - see Floating Window section below

      -- Provider-specific options
      provider_opts = {
        -- Command for external terminal provider. Can be:
        -- 1. String with %s placeholder: "alacritty -e %s" (backward compatible)
        -- 2. String with two %s placeholders: "alacritty --working-directory %s -e %s" (cwd, command)
        -- 3. Function returning command: function(cmd, env) return "alacritty -e " .. cmd end
        external_terminal_cmd = nil,
      },
    },

    -- Diff Integration
    diff_opts = {
      layout = "vertical", -- "vertical" or "horizontal"
      open_in_new_tab = false,
      keep_terminal_focus = false, -- If true, moves focus back to terminal after diff opens
      hide_terminal_in_new_tab = false,
      -- on_new_file_reject = "keep_empty", -- "keep_empty" or "close_window"

      -- Legacy aliases (still supported):
      -- vertical_split = true,
      -- open_in_current_tab = true,
    },
  },
  keys = {
    -- Your keymaps here
  },
}

Working Directory Control

You can fix the Claude terminal's working directory regardless of autochdir and buffer-local cwd changes. Options (precedence order):

cwd_provider(ctx): function that returns a directory string. Receives { file, file_dir, cwd }.
cwd: static path to use as working directory.
git_repo_cwd = true: resolves git root from the current file directory (or cwd if no file).

Examples:

require("claudecode").setup({
  -- Top-level aliases are supported and forwarded to terminal config
  git_repo_cwd = true,
})

require("claudecode").setup({
  terminal = {
    cwd = vim.fn.expand("~/projects/my-app"),
  },
})

require("claudecode").setup({
  terminal = {
    cwd_provider = function(ctx)
      -- Prefer repo root; fallback to file's directory
      local cwd = require("claudecode.cwd").git_root(ctx.file_dir or ctx.cwd) or ctx.file_dir or ctx.cwd
      return cwd
    end,
  },
})

Floating Window Configuration

The snacks_win_opts configuration allows you to create floating Claude Code terminals with custom positioning, sizing, and key bindings. Here are several practical examples:

Basic Floating Window with Ctrl+, Toggle

local toggle_key = "<C-,>"
return {
  {
    "coder/claudecode.nvim",
    dependencies = { "folke/snacks.nvim" },
    keys = {
      { toggle_key, "<cmd>ClaudeCodeFocus<cr>", desc = "Claude Code", mode = { "n", "x" } },
    },
    opts = {
      terminal = {
        ---@module "snacks"
        ---@type snacks.win.Config|{}
        snacks_win_opts = {
          position = "float",
          width = 0.9,
          height = 0.9,
          keys = {
            claude_hide = {
              toggle_key,
              function(self)
                self:hide()
              end,
              mode = "t",
              desc = "Hide",
            },
          },
        },
      },
    },
  },
}

Alternative with Meta+, (Alt+,) Toggle

local toggle_key = "<M-,>"  -- Alt/Meta + comma
return {
  {
    "coder/claudecode.nvim",
    dependencies = { "folke/snacks.nvim" },
    keys = {
      { toggle_key, "<cmd>ClaudeCodeFocus<cr>", desc = "Claude Code", mode = { "n", "x" } },
    },
    opts = {
      terminal = {
        snacks_win_opts = {
          position = "float",
          width = 0.8,
          height = 0.8,
          border = "rounded",
          keys = {
            claude_hide = { toggle_key, function(self) self:hide() end, mode = "t", desc = "Hide" },
          },
        },
      },
    },
  },
}

Centered Floating Window with Custom Styling

require("claudecode").setup({
  terminal = {
    snacks_win_opts = {
      position = "float",
      width = 0.6,
      height = 0.6,
      border = "double",
      backdrop = 80,
      keys = {
        claude_hide = { "<Esc>", function(self) self:hide() end, mode = "t", desc = "Hide" },
        claude_close = { "q", "close", mode = "n", desc = "Close" },
      },
    },
  },
})

Multiple Key Binding Options

{
  "coder/claudecode.nvim",
  dependencies = { "folke/snacks.nvim" },
  keys = {
    { "<C-,>", "<cmd>ClaudeCodeFocus<cr>", desc = "Claude Code (Ctrl+,)", mode = { "n", "x" } },
    { "<M-,>", "<cmd>ClaudeCodeFocus<cr>", desc = "Claude Code (Alt+,)", mode = { "n", "x" } },
    { "<leader>tc", "<cmd>ClaudeCodeFocus<cr>", desc = "Toggle Claude", mode = { "n", "x" } },
  },
  opts = {
    terminal = {
      snacks_win_opts = {
        position = "float",
        width = 0.85,
        height = 0.85,
        border = "rounded",
        keys = {
          -- Multiple ways to hide from terminal mode
          claude_hide_ctrl = { "<C-,>", function(self) self:hide() end, mode = "t", desc = "Hide (Ctrl+,)" },
          claude_hide_alt = { "<M-,>", function(self) self:hide() end, mode = "t", desc = "Hide (Alt+,)" },
          claude_hide_esc = { "<C-\\><C-n>", function(self) self:hide() end, mode = "t", desc = "Hide (Ctrl+\\)" },
        },
      },
    },
  },
}

Window Position Variations

-- Bottom floating (like a drawer)
snacks_win_opts = {
  position = "bottom",
  height = 0.4,
  width = 1.0,
  border = "single",
}

-- Side floating panel
snacks_win_opts = {
  position = "right",
  width = 0.4,
  height = 1.0,
  border = "rounded",
}

-- Small centered popup
snacks_win_opts = {
  position = "float",
  width = 120,  -- Fixed width in columns
  height = 30,  -- Fixed height in rows
  border = "double",
  backdrop = 90,
}

For complete configuration options, see:

Terminal Providers

None (No-Op) Provider

Run Claude Code without any terminal management inside Neovim. This is useful for advanced setups where you manage the CLI externally (tmux, kitty, separate terminal windows) while still using the WebSocket server and tools.

You have to take care of launching CC and connecting it to the IDE yourself. (e.g. claude --ide or launching claude and then selecting the IDE using the /ide command)

{
  "coder/claudecode.nvim",
  opts = {
    terminal = {
      provider = "none", -- no UI actions; server + tools remain available
    },
  },
}

Notes:

No windows/buffers are created. :ClaudeCode and related commands will not open anything.
The WebSocket server still starts and broadcasts work as usual. Launch the Claude CLI externally when desired.

External Terminal Provider

Run Claude Code in a separate terminal application outside of Neovim:

-- Using a string template (simple)
{
  "coder/claudecode.nvim",
  opts = {
    terminal = {
      provider = "external",
      provider_opts = {
        external_terminal_cmd = "alacritty -e %s", -- %s is replaced with claude command
        -- Or with working directory: "alacritty --working-directory %s -e %s" (first %s = cwd, second %s = command)
      },
    },
  },
}

-- Using a function for dynamic command generation (advanced)
{
  "coder/claudecode.nvim",
  opts = {
    terminal = {
      provider = "external",
      provider_opts = {
        external_terminal_cmd = function(cmd, env)
          -- You can build complex commands based on environment or conditions
          if vim.fn.has("mac") == 1 then
            return { "osascript", "-e", string.format('tell app "Terminal" to do script "%s"', cmd) }
          else
            return "alacritty -e " .. cmd
          end
        end,
      },
    },
  },
}

Custom Terminal Providers

You can create custom terminal providers by passing a table with the required functions instead of a string provider name:

require("claudecode").setup({
  terminal = {
    provider = {
      -- Required functions
      setup = function(config)
        -- Initialize your terminal provider
      end,

      open = function(cmd_string, env_table, effective_config, focus)
        -- Open terminal with command and environment
        -- focus parameter controls whether to focus terminal (defaults to true)
      end,

      close = function()
        -- Close the terminal
      end,

      simple_toggle = function(cmd_string, env_table, effective_config)
        -- Simple show/hide toggle
      end,

      focus_toggle = function(cmd_string, env_table, effective_config)
        -- Smart toggle: focus terminal if not focused, hide if focused
      end,

      get_active_bufnr = function()
        -- Return terminal buffer number or nil
        return 123 -- example
      end,

      is_available = function()
        -- Return true if provider can be used
        return true
      end,

      -- Optional functions (auto-generated if not provided)
      toggle = function(cmd_string, env_table, effective_config)
        -- Defaults to calling simple_toggle for backward compatibility
      end,

      _get_terminal_for_test = function()
        -- For testing only, defaults to return nil
        return nil
      end,
    },
  },
})

Custom Provider Example

Here's a complete example using a hypothetical my_terminal plugin:

local my_terminal_provider = {
  setup = function(config)
    -- Store config for later use
    self.config = config
  end,

  open = function(cmd_string, env_table, effective_config, focus)
    if focus == nil then focus = true end

    local my_terminal = require("my_terminal")
    my_terminal.open({
      cmd = cmd_string,
      env = env_table,
      width = effective_config.split_width_percentage,
      side = effective_config.split_side,
      focus = focus,
    })
  end,

  close = function()
    require("my_terminal").close()
  end,

  simple_toggle = function(cmd_string, env_table, effective_config)
    require("my_terminal").toggle()
  end,

  focus_toggle = function(cmd_string, env_table, effective_config)
    local my_terminal = require("my_terminal")
    if my_terminal.is_focused() then
      my_terminal.hide()
    else
      my_terminal.focus()
    end
  end,

  get_active_bufnr = function()
    return require("my_terminal").get_bufnr()
  end,

  is_available = function()
    local ok, _ = pcall(require, "my_terminal")
    return ok
  end,
}

require("claudecode").setup({
  terminal = {
    provider = my_terminal_provider,
  },
})

The custom provider will automatically fall back to the native provider if validation fails or is_available() returns false.

Note: If your command or working directory may contain spaces or special characters, prefer returning a table of args from a function (e.g., { "alacritty", "--working-directory", cwd, "-e", "claude", "--help" }) to avoid shell-quoting issues.

Community Extensions

The following are third-party community extensions that complement claudecode.nvim. These extensions are not affiliated with Coder and are maintained independently by community members. We do not ensure that these extensions work correctly or provide support for them.

🔍 claude-fzf.nvim

Integrates fzf-lua's file selection with claudecode.nvim's context management:

Batch file selection with fzf-lua multi-select
Smart search integration with grep → Claude
Tree-sitter based context extraction
Support for files, buffers, git files

📚 claude-fzf-history.nvim

Provides convenient Claude interaction history management and access for enhanced workflow continuity.

Disclaimer: These community extensions are developed and maintained by independent contributors. The authors and their extensions are not affiliated with Coder. Use at your own discretion and refer to their respective repositories for installation instructions, documentation, and support.

Auto-Save Plugin Issues

Using auto-save plugins can cause diff windows opened by Claude to immediately accept without waiting for input. You can avoid this using a custom condition:

Pocco81/auto-save.nvim

opts = {
  -- ... other options
  condition = function(buf)
    local fn = vim.fn
    local utils = require("auto-save.utils.data")

    -- First check the default conditions
    if not (fn.getbufvar(buf, "&modifiable") == 1 and utils.not_in(fn.getbufvar(buf, "&filetype"), {})) then
      return false
    end

    -- Exclude claudecode diff buffers by buffer name patterns
    local bufname = vim.api.nvim_buf_get_name(buf)
    if bufname:match("%(proposed%)") or
       bufname:match("%(NEW FILE %- proposed%)") or
       bufname:match("%(New%)") then
      return false
    end

    -- Exclude by buffer variables (claudecode sets these)
    if vim.b[buf].claudecode_diff_tab_name or
       vim.b[buf].claudecode_diff_new_win or
       vim.b[buf].claudecode_diff_target_win then
      return false
    end

    -- Exclude by buffer type (claudecode diff buffers use "acwrite")
    local buftype = fn.getbufvar(buf, "&buftype")
    if buftype == "acwrite" then
      return false
    end

    return true -- Safe to auto-save
  end,
},

okuuva/auto-save.nvim

opts = {
  -- ... other options
  condition = function(buf)
    -- Exclude claudecode diff buffers by buffer name patterns
    local bufname = vim.api.nvim_buf_get_name(buf)
    if bufname:match('%(proposed%)') or bufname:match('%(NEW FILE %- proposed%)') or bufname:match('%(New%)') then
      return false
    end

    -- Exclude by buffer variables (claudecode sets these)
    if
      vim.b[buf].claudecode_diff_tab_name
      or vim.b[buf].claudecode_diff_new_win
      or vim.b[buf].claudecode_diff_target_win
    then
      return false
    end

    -- Exclude by buffer type (claudecode diff buffers use "acwrite")
    local buftype = vim.fn.getbufvar(buf, '&buftype')
    if buftype == 'acwrite' then
      return false
    end

    return true -- Safe to auto-save
  end,
},

Troubleshooting

Claude not connecting? Check :ClaudeCodeStatus and verify lock file exists in ~/.claude/ide/ (or $CLAUDE_CONFIG_DIR/ide/ if CLAUDE_CONFIG_DIR is set)
Need debug logs? Set log_level = "debug" in opts
Terminal issues? Try provider = "native" if using snacks.nvim
Local installation not working? If you used claude migrate-installer, set terminal_cmd = "~/.claude/local/claude" in your config. Check which claude vs ls ~/.claude/local/claude to verify your installation type.
Native binary installation not working? If you used the alpha native binary installer, run claude doctor to verify installation health and use which claude to find the binary path. Set terminal_cmd = "/path/to/claude" with the detected path in your config.

Contributing

See DEVELOPMENT.md for build instructions and development guidelines. Tests can be run with make test.

License

MIT

Acknowledgements

Claude Code CLI by Anthropic
Inspired by analyzing the official VS Code extension
Built with assistance from AI (how meta!)

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

rebelot/kanagawa.nvim

NeoVim dark colorscheme inspired by the colors of the famous painting by Katsushika Hokusai.

🌊 KANAGAWA.nvim 🌊

NeoVim dark colorscheme inspired by the colors of the famous painting by Katsushika Hokusai.

Features

Extensive support for TreeSitter syntax highlighting, and many popular plugins
Compilation to lua byte code for super fast startup times

Installation

Download with your favorite package manager.

use "rebelot/kanagawa.nvim"

Requirements

neovim latest
truecolor terminal support
undercurl terminal support (optional)

Usage

As simple as writing (pasting)

colorscheme kanagawa

vim.cmd("colorscheme kanagawa")

Configuration

There is no need to call setup if you are ok with the defaults.

-- Default options:
require('kanagawa').setup({
    compile = false,             -- enable compiling the colorscheme
    undercurl = true,            -- enable undercurls
    commentStyle = { italic = true },
    functionStyle = {},
    keywordStyle = { italic = true},
    statementStyle = { bold = true },
    typeStyle = {},
    transparent = false,         -- do not set background color
    dimInactive = false,         -- dim inactive window `:h hl-NormalNC`
    terminalColors = true,       -- define vim.g.terminal_color_{0,17}
    colors = {                   -- add/modify theme and palette colors
        palette = {},
        theme = { wave = {}, lotus = {}, dragon = {}, all = {} },
    },
    overrides = function(colors) -- add/modify highlights
        return {}
    end,
    theme = "wave",              -- Load "wave" theme
    background = {               -- map the value of 'background' option to a theme
        dark = "wave",           -- try "dragon" !
        light = "lotus"
    },
})

-- setup must be called before loading
vim.cmd("colorscheme kanagawa")

NOTE 1: If you enable compilation, make sure to run :KanagawaCompile command every time you make changes to your config.

" 1. Modify your config
" 2. Restart nvim
" 3. Run this command:
:KanagawaCompile

NOTE 2: Kanagawa adjusts to the value of some options. Make sure that the options 'laststatus' and 'cmdheight' are set before calling setup.

Themes

Kanagawa comes in three variants:

wave the default heart-warming theme,
dragon for those late-night sessions
lotus for when you're out in the open.

Themes can be changed in three ways:

Setting config.theme to the desired theme.
Using the background option: Any change to the value of vim.o.background will select the theme mapped by config.background.

Loading the colorscheme directly with:

vim.cmd("colorscheme kanagawa-wave")
vim.cmd("colorscheme kanagawa-dragon")
vim.cmd("colorscheme kanagawa-lotus")

require("kanagawa").load("wave")

Customization

In kanagawa, there are two kinds of colors: PaletteColors and ThemeColors; PaletteColors are defined directly as RGB Hex strings, and have arbitrary names that recall their actual color. Conversely, ThemeColors are named and grouped semantically on the basis of their actual function.

In short, a palette defines all the available colors, while a theme maps the PaletteColors to specific ThemeColors and the same palette color may be assigned to multiple theme colors.

You can change both theme or palette colors using config.colors. All the palette color names can be found here, while their usage by each theme can be found here.

require('kanagawa').setup({
    ...,
    colors = {
        palette = {
            -- change all usages of these colors
            sumiInk0 = "#000000",
            fujiWhite = "#FFFFFF",
        },
        theme = {
            -- change specific usages for a certain theme, or for all of them
            wave = {
                ui = {
                    float = {
                        bg = "none",
                    },
                },
            },
            dragon = {
                syn = {
                    parameter = "yellow",
                },
            },
            all = {
                ui = {
                    bg_gutter = "none"
                }
            }
        }
    },
    ...
})

You can also conveniently add/modify any hlgroups using the config.overrides option, allowing you to customize the looks of specific built-in elements, or any other external plugins that provides hlgroups. (See :help highlight for more information on hlgroups.) Supported keywords are the same for :h nvim_set_hl {val} parameter.

require('kanagawa').setup({
    ...,
    overrides = function(colors)
        return {
            -- Assign a static color to strings
            String = { fg = colors.palette.carpYellow, italic = true },
            -- theme colors will update dynamically when you change theme!
            SomePluginHl = { fg = colors.theme.syn.type, bold = true },
        }
    end,
    ...
})

Common customizations

Remove gutter background

Remove the background of LineNr, {Sign,Fold}Column and friends

colors = {
    theme = {
        all = {
            ui = {
                bg_gutter = "none"
            }
        }
    }
}

Transparent Floating Windows

This will make floating windows look nicer with default borders.

overrides = function(colors)
    local theme = colors.theme
    return {
        NormalFloat = { bg = "none" },
        FloatBorder = { bg = "none" },
        FloatTitle = { bg = "none" },

        -- Save an hlgroup with dark background and dimmed foreground
        -- so that you can use it where your still want darker windows.
        -- E.g.: autocmd TermOpen * setlocal winhighlight=Normal:NormalDark
        NormalDark = { fg = theme.ui.fg_dim, bg = theme.ui.bg_m3 },

        -- Popular plugins that open floats will link to NormalFloat by default;
        -- set their background accordingly if you wish to keep them dark and borderless
        LazyNormal = { bg = theme.ui.bg_m3, fg = theme.ui.fg_dim },
        MasonNormal = { bg = theme.ui.bg_m3, fg = theme.ui.fg_dim },
    }
end,

If you'd like to keep the floating windows darker, but you're unhappy with how borders are rendered, consider using characters that are drawn at the edges of the box:

{ "🭽", "▔", "🭾", "▕", "🭿", "▁", "🭼", "▏" }

Borderless Telescope

Block-like modern Telescope UI

overrides = function(colors)
    local theme = colors.theme
    return {
        TelescopeTitle = { fg = theme.ui.special, bold = true },
        TelescopePromptNormal = { bg = theme.ui.bg_p1 },
        TelescopePromptBorder = { fg = theme.ui.bg_p1, bg = theme.ui.bg_p1 },
        TelescopeResultsNormal = { fg = theme.ui.fg_dim, bg = theme.ui.bg_m1 },
        TelescopeResultsBorder = { fg = theme.ui.bg_m1, bg = theme.ui.bg_m1 },
        TelescopePreviewNormal = { bg = theme.ui.bg_dim },
        TelescopePreviewBorder = { bg = theme.ui.bg_dim, fg = theme.ui.bg_dim },
    }
end,

Dark completion (popup) menu

More uniform colors for the popup menu.

overrides = function(colors)
    local theme = colors.theme
    return {
        Pmenu = { fg = theme.ui.shade0, bg = theme.ui.bg_p1 },  -- add `blend = vim.o.pumblend` to enable transparency
        PmenuSel = { fg = "NONE", bg = theme.ui.bg_p2 },
        PmenuSbar = { bg = theme.ui.bg_m1 },
        PmenuThumb = { bg = theme.ui.bg_p2 },
    }
end,

Tint background of diagnostic messages with their foreground color

This immitates a style of diagnostic messages seen, for example, in tokyonight.nvim.

overrides = function(colors)
  local theme = colors.theme
  local makeDiagnosticColor = function(color)
    local c = require("kanagawa.lib.color")
    return { fg = color, bg = c(color):blend(theme.ui.bg, 0.95):to_hex() }
  end

  return {
    DiagnosticVirtualTextHint  = makeDiagnosticColor(theme.diag.hint),
    DiagnosticVirtualTextInfo  = makeDiagnosticColor(theme.diag.info),
    DiagnosticVirtualTextWarn  = makeDiagnosticColor(theme.diag.warning),
    DiagnosticVirtualTextError = makeDiagnosticColor(theme.diag.error),
  }
end

Integration

Get palette and theme colors

-- Get the colors for the current theme
local colors = require("kanagawa.colors").setup()
local palette_colors = colors.palette
local theme_colors = colors.theme

-- Get the colors for a specific theme
local wave_colors = require("kanagawa.colors").setup({ theme = 'wave' })

Terminal integration

The following example provides a snippet to automatically change the theme for the Kitty terminal emulator.

vim.api.nvim_create_autocmd("ColorScheme", {
    pattern = "kanagawa",
    callback = function()
        if vim.o.background == "light" then
            vim.fn.system("kitty +kitten themes Kanagawa_light")
        elseif vim.o.background == "dark" then
            vim.fn.system("kitty +kitten themes Kanagawa_dragon")
        else
            vim.fn.system("kitty +kitten themes Kanagawa")
        end
    end,
})

Color palette

Name	Hex	Usage
fujiWhite	`#DCD7BA`	Default foreground
oldWhite	`#C8C093`	Dark foreground (statuslines)
sumiInk0	`#16161D`	Dark background (statuslines and floating windows)
sumiInk1	`#1F1F28`	Default background
sumiInk2	`#2A2A37`	Lighter background (colorcolumn, folds)
sumiInk3	`#363646`	Lighter background (cursorline)
sumiInk4	`#54546D`	Darker foreground (line numbers, fold column, non-text characters), float borders
waveBlue1	`#223249`	Popup background, visual selection background
waveBlue2	`#2D4F67`	Popup selection background, search background
winterGreen	`#2B3328`	Diff Add (background)
winterYellow	`#49443C`	Diff Change (background)
winterRed	`#43242B`	Diff Deleted (background)
winterBlue	`#252535`	Diff Line (background)
autumnGreen	`#76946A`	Git Add
autumnRed	`#C34043`	Git Delete
autumnYellow	`#DCA561`	Git Change
samuraiRed	`#E82424`	Diagnostic Error
roninYellow	`#FF9E3B`	Diagnostic Warning
waveAqua1	`#6A9589`	Diagnostic Info
dragonBlue	`#658594`	Diagnostic Hint
fujiGray	`#727169`	Comments
springViolet1	`#938AA9`	Light foreground
oniViolet	`#957FB8`	Statements and Keywords
crystalBlue	`#7E9CD8`	Functions and Titles
springViolet2	`#9CABCA`	Brackets and punctuation
springBlue	`#7FB4CA`	Specials and builtin functions
lightBlue	`#A3D4D5`	Not used
waveAqua2	`#7AA89F`	Types
springGreen	`#98BB6C`	Strings
boatYellow1	`#938056`	Not used
boatYellow2	`#C0A36E`	Operators, RegEx
carpYellow	`#E6C384`	Identifiers
sakuraPink	`#D27E99`	Numbers
waveRed	`#E46876`	Standout specials 1 (builtin variables)
peachRed	`#FF5D62`	Standout specials 2 (exception handling, return)
surimiOrange	`#FFA066`	Constants, imports, booleans
katanaGray	`#717C7C`	Deprecated

Accessibility

The colors maintain a 4.5:1 contrast ratio, complying with WCAG 2.1 | Level AA.

Extras

Alacritty
Alfred
Base16
Broot
Emacs
Fish
Foot
iTerm
Kitty
Mintty
Pywal
Sway
Wezterm
Windows Terminal
Ghostty
Xresources
tmTheme (Sublime Text, bat and delta)
JSON compatible with many terminals Check Gogh for the list of supported terminals.
🎉 Bonus! You win a tiny python script🐍 to extract color palettes 🎨 from any image! 🥳

Acknowledgements

Donate

Buy me coffee and support my work 😉

sphamba/smear-cursor.nvim

🌠 Neovim plugin to animate the cursor with a smear effect in all terminals

Smear cursor for Neovim

Neovim plugin to animate the cursor with a smear effect in all terminals. Inspired by Neovide's animated cursor.

This plugin is intended for terminals/GUIs that can only display text and do not have graphical capabilities (unlike Neovide, or the Kitty terminal). Also, check out the karb94/neoscroll.nvim plugin for smooth scrolling!

🚀 Demo

Demo

Some configuration examples:

Default	Faster

Smooth cursor without smear	Smooth caret

Fire hazard

📦 Installation

Note

After enabling the plugin in your configuration, you can toggle the smear cursor on and off with the :SmearCursorToggle command or with :lua require("smear_cursor").toggle().

Minimum requirements

Neovim 0.10.2

Using vim.pack

In your ~/.config/nvim/init.lua, add:

vim.pack.add({
  "https://github.com/sphamba/smear-cursor.nvim",
})

require('smear_cursor').setup({
  -- Your options
})

Using lazy.nvim

In ~/.config/nvim/lua/plugins/smear_cursor.lua, add:

return {
  "sphamba/smear-cursor.nvim",
  opts = {},
}

Using vim-plug

In your init.vim, add:

call plug#begin()
Plug 'sphamba/smear-cursor.nvim'
call plug#end()

lua require('smear_cursor').enabled = true

⚙ Configuration

Using lazy.nvim

Here are the default configuration options:

return {
  "sphamba/smear-cursor.nvim",

  opts = {
    -- Smear cursor when switching buffers or windows.
    smear_between_buffers = true,

    -- Smear cursor when moving within line or to neighbor lines.
    -- Use `min_horizontal_distance_smear` and `min_vertical_distance_smear` for finer control
    smear_between_neighbor_lines = true,

    -- Draw the smear in buffer space instead of screen space when scrolling
    scroll_buffer_space = true,

    -- Set to `true` if your font supports legacy computing symbols (block unicode symbols).
    -- Smears and particles will look a lot less blocky.
    legacy_computing_symbols_support = false,

    -- Smear cursor in insert mode.
    -- See also `vertical_bar_cursor_insert_mode` and `distance_stop_animating_vertical_bar`.
    smear_insert_mode = true,
  },
}

Refer to lua/smear_cursor/config.lua and lua/smear_cursor/color.lua for the full list of configuration options that can be set with opts.

Tip

Some terminals override the cursor color set by Neovim. If that is the case, manually put the actual cursor color in your config to get a matching smear color:

  opts = {
    -- Smear cursor color. Defaults to Cursor GUI color if not set.
    -- Set to "none" to match the text color at the target cursor position.
    -- Can be a hex color code, or a highlight group name.
    cursor_color = "#d3cdc3",
  }

Note

Fonts with legacy computing symbols support seems to be rare. One notable example is Cascadia Code. You can still use smear-cursor.nvim without such a font.

Examples

Tip

See videos at the top for visual examples.

🔥 Faster smear

As an example of further configuration, you can tune the smear dynamics to be snappier:

  opts = {                                -- Default  Range
    stiffness = 0.8,                      -- 0.6      [0, 1]
    trailing_stiffness = 0.6,             -- 0.45     [0, 1]
    stiffness_insert_mode = 0.7,          -- 0.5      [0, 1]
    trailing_stiffness_insert_mode = 0.7, -- 0.5      [0, 1]
    damping = 0.95,                       -- 0.85     [0, 1]
    damping_insert_mode = 0.95,           -- 0.9      [0, 1]
    distance_stop_animating = 0.5,        -- 0.1      > 0
  },

If you notice a low framerate, you can try lowering the time interval between draws (default is 17ms):

  opts = {
    time_interval = 7, -- milliseconds
  },

You can also change the "bounciness" of the smear by adjusting the damping and damping_insert_mode parameters (default to 0.85 and 0.9 respectively). Decreasing them (e.g. to 0.65) will make the smear appear more elastic (overshooting target position).

🔥 FIRE HAZARD 🔥

Feel free to experiment with all the configuration options, but be aware that some combinations may cause your cursor to flicker or even catch fire. That can happen with the following settings:

 opts = {
   cursor_color = "#ff4000",
   particles_enabled = true,
   stiffness = 0.5,
   trailing_stiffness = 0.2,
   trailing_exponent = 5,
   damping = 0.6,
   gradient_exponent = 0,
   gamma = 1,
   never_draw_over_target = true, -- if you want to actually see under the cursor
   hide_target_hack = true,       -- same
   particle_spread = 1,
   particles_per_second = 500,
   particles_per_length = 50,
   particle_max_lifetime = 800,
   particle_max_initial_velocity = 20,
   particle_velocity_from_cursor = 0.5,
   particle_damping = 0.15,
   particle_gravity = -50,
   min_distance_emit_particles = 0,
}

█ Smooth cursor without smear

If you wish to only have a smoother cursor that keeps its rectangular shape (without the trail), you can set the following options:

  opts = {
    stiffness = 0.5,
    trailing_stiffness = 0.5,
    matrix_pixel_threshold = 0.5,
  },

🌌 Transparent background

Drawing the smear over a transparent background works better when using a font that supports legacy computing symbols, therefore setting the following option:

  opts = {
    legacy_computing_symbols_support = true,
  },

If your font does not support legacy computing symbols, there will be a shadow under the smear. You may set a color for this shadow to be less noticeable:

  opts = {
    transparent_bg_fallback_color = "#303030",
  },

🔲 No GUI colors

If you are not using termguicolors, you need to manually set a color gradient for the smear (it can be a single color):

  opts = {
    cterm_cursor_colors = { 240, 245, 250, 255 },
    cterm_bg = 235,
  }

If you are not using guicursor, and you notice the cursor getting duplicated (smear visible at the same time as the real cursor), try setting

  opts = {
    hide_target_hack = true,
    never_draw_over_target = true,
  }

Using `init.vim`

You can set the configuration variables in your init.vim file like this:

lua require('smear_cursor').setup({
    \cursor_color = '#d3cdc3',
\})

🤕 Known issues

There is a shadow around the smear (text become invisible). This is inherent to the way the smear is rendered, as Neovim is not able to render superimposed characters. The shadow is less noticeable when the smear is moving faster (see configuration options).
Likely not compatible with other plugins that modify the cursor.

👨‍💻 Contributing

Please feel free to open an issue or a pull request if you have any suggestions or improvements! This project uses pre-commit hooks to ensure code quality (with StyLua) and meaningful commit messages (following Conventional Commits)

Requirements

Neovim >= 0.10.2
Make
pre-commit (pip install pre-commit)

Setup

Clone the repository
Run make install to install the pre-commit hooks