Documentation

docs/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+.vitepress/cache
+.vitepress/dist

docs/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 120
+}

docs/.vitepress/config.mts

@@ -0,0 +1,55 @@
+import { defineConfig } from 'vitepress'
+import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
+import taskLists from 'markdown-it-task-lists'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: 'Blink Completion (blink.cmp)',
+  description: 'Performant, batteries-included completion plugin for Neovim',
+  sitemap: { hostname: 'https://cmp.saghen.dev/' },
+  head: [['link', { rel: 'icon', href: '/favicon.png' }]],
+  themeConfig: {
+    sidebar: [
+      { text: 'Introduction', link: '/' },
+      { text: 'Installation', link: '/installation' },
+      {
+        text: 'Configuration',
+        items: [
+          { text: 'General', link: '/configuration/general' },
+          { text: 'Appearance', link: '/configuration/appearance' },
+          { text: 'Completion', link: '/configuration/completion' },
+          { text: 'Keymap', link: '/configuration/keymap' },
+          { text: 'Signature', link: '/configuration/signature' },
+          { text: 'Sources', link: '/configuration/sources' },
+          { text: 'Snippets', link: '/configuration/snippets' },
+          { text: 'Reference', link: '/configuration/reference' },
+        ],
+      },
+      {
+        text: 'Development',
+        items: [
+          { text: 'Architecture', link: '/development/architecture' },
+          { text: 'Writing Sources', link: '/development/writing-sources' },
+          { text: 'LSP Tracker', link: '/development/lsp-tracker' },
+        ],
+      },
+    ],
+
+    socialLinks: [{ icon: 'github', link: 'https://github.com/saghen/blink.cmp' }],
+
+    search: {
+      provider: 'local',
+    },
+  },
+
+  markdown: {
+    theme: {
+      light: 'catppuccin-latte',
+      dark: 'catppuccin-mocha',
+    },
+    config(md) {
+      md.use(tabsMarkdownPlugin)
+      md.use(taskLists)
+    },
+  },
+})

docs/.vitepress/theme/index.ts

@@ -0,0 +1,14 @@
+// https://vitepress.dev/guide/custom-theme
+import DefaultTheme from 'vitepress/theme'
+import type { Theme } from 'vitepress'
+import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
+
+import '@catppuccin/vitepress/theme/mocha/blue.css'
+import './style.css'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    enhanceAppWithTabs(app)
+  },
+} satisfies Theme

docs/.vitepress/theme/style.css

@@ -0,0 +1,9 @@
+/* Wrap text in code blocks */
+code {
+  white-space: pre-wrap !important;
+  word-break: break-word !important;
+}
+
+.content-container {
+  max-width: 800px !important;
+}

docs/configuration/appearance.md

@@ -0,0 +1,29 @@
+# Appearance <a href="./reference#appearance"><Badge type="info" text="Go to default configuration" /></a>
+
+If you're looking for how to change the appearance of the completion menu, check out the [menu draw configuration](./completion#completion-menu-draw).
+
+## Highlight groups
+
+| Group | Default | Description |
+| ----- | ------- | ----------- |
+| `BlinkCmpMenu` | Pmenu | The completion menu window |
+| `BlinkCmpMenuBorder` | Pmenu | The completion menu window border |
+| `BlinkCmpMenuSelection` | PmenuSel | The completion menu window selected item |
+| `BlinkCmpScrollBarThumb` | PmenuThumb | The scrollbar thumb |
+| `BlinkCmpScrollBarGutter` | PmenuSbar | The scrollbar gutter |
+| `BlinkCmpLabel` | Pmenu | Label of the completion item |
+| `BlinkCmpLabelDeprecated` | NonText | Deprecated label of the completion item |
+| `BlinkCmpLabelMatch` | Pmenu | (Currently unused) Label of the completion item when it matches the query |
+| `BlinkCmpLabelDetail` | NonText | Label description of the completion item |
+| `BlinkCmpLabelDescription` | NonText | Label description of the completion item |
+| `BlinkCmpKind` | Special | Kind icon/text of the completion item |
+| `BlinkCmpKind<kind>` | Special | Kind icon/text of the completion item |
+| `BlinkCmpSource` | NonText | Source of the completion item |
+| `BlinkCmpGhostText` | NonText | Preview item with ghost text  |
+| `BlinkCmpDoc` | NormalFloat | The documentation window |
+| `BlinkCmpDocBorder` | NormalFloat | The documentation window border |
+| `BlinkCmpDocSeparator` | NormalFloat | The documentation separator between doc and detail |
+| `BlinkCmpDocCursorLine` | Visual | The documentation window cursor line |
+| `BlinkCmpSignatureHelp` | NormalFloat | The signature help window |
+| `BlinkCmpSignatureHelpBorder` | NormalFloat | The signature help window border |
+| `BlinkCmpSignatureHelpActiveParameter` | LspSignatureActiveParameter | Active parameter of the signature help |

docs/configuration/completion.md

@@ -0,0 +1,100 @@
+# Completion
+
+Blink cmp has *a lot* of configuration options, the following document tries to highlight the ones you'll likely care the most about for each section. For all options, click on the "Go to default configuration" button next to each header.
+
+## Keyword <a href="./reference#completion-keyword"><Badge type="info" text="Go to default configuration" /></a>
+
+Controls what the plugin considers to be a keyword, used for fuzzy matching and triggering completions. Most notably, the `range` option controls whether the keyword should match against the text before *and* after the cursor, or just before the cursor.
+
+:::tabs
+== Prefix
+<img src="https://github.com/user-attachments/assets/6398e470-58c7-4624-989a-bffe26c7f443" />
+== Full
+<img src="https://github.com/user-attachments/assets/3e082492-6a5d-4dba-b4ba-6a1bfca50351" />
+:::
+
+## Trigger <a href="./reference#completion-trigger"><Badge type="info" text="Go to default configuration" /></a>
+
+Controls when to request completion items from the sources and show the completion menu. The following options are available, excluding their `show_on` prefix:
+
+:::tabs
+== Keyword
+<video src="https://github.com/user-attachments/assets/5e8f8f9f-bc6a-4d21-9cce-2e291b6a7de8" muted autoplay loop />
+== Trigger Character
+<video src="https://github.com/user-attachments/assets/b4ee0069-2de8-44e7-b3ca-51b10bc4cb4a" muted autoplay loop />
+== Insert on Trigger Character
+<video src="https://github.com/user-attachments/assets/9e7aa3c2-4756-4a5e-a0e8-303d3ae0fda9" muted autoplay loop />
+== Accept on Trigger Character
+TODO: Find a case where this actually fires : )
+:::
+
+## List <a href="./reference#completion-list"><Badge type="info" text="Go to default configuration" /></a>
+
+Manages the completion list and its behavior when selecting items. The most commonly changed option is `completion.list.selection`, which controls whether the list will automatically select the first item in the list, and whether selection shows a preview:
+
+:::tabs
+== Preselect
+Selects the first item automatically
+
+<img src="https://github.com/user-attachments/assets/69079ced-43f1-437e-8a45-3cb13f841d61" />
+== Manual
+No item will be selected by default. You may use the `select_and_accept` keymap command to select the first item and accept it when there's no selection. The `accept` keymap command, on the other hand, will only trigger if an item is selected.
+
+<video src="https://github.com/user-attachments/assets/09cd9b4b-18b3-456b-bb0a-074ae54e9d77" muted autoplay loop />
+== Auto Insert
+No item will be selected by default, and selecting an item will insert a "preview" of the item automatically. You may use the `select_and_accept` keymap command to select the first item and accept it when there's no selection. The `accept` keymap command, on the other hand, will only trigger if an item is selected.
+
+<video src="https://github.com/user-attachments/assets/4658b61d-1b95-404a-b6b5-3a4afbfb8112" muted autoplay loop />
+:::
+
+## Accept <a href="./reference#completion-accept"><Badge type="info" text="Go to default configuration" /></a>
+
+Manages the behavior when accepting an item in the completion menu.
+
+### Auto Brackets
+
+> [!NOTE]
+> Some LSPs may add auto brackets themselves. You may be able to configure this behavior in your LSP client configuration
+
+LSPs provide a `kind` field for completion items, indicating whether the item is a function, method, variable, etc. The plugin will automatically add brackets for functions/methods and place the cursor inside the brackets. For items not marked as such, the plugin will asynchronously resolve the semantic tokens from the LSP and add brackets if marked as a function. A default list of brackets have been included in the default configuration, but you may add more in the configuration (contributions welcome!).
+
+If brackets are showing when you don't expect them, try disabling `kind_resolution` or `semantic_token_resolution` for that filetype (`echo &filetype`). If that fixes the issue, please open a PR setting this as the default!
+
+## Menu <a href="./reference#completion-menu"><Badge type="info" text="Go to default configuration" /></a>
+
+Manages the appearance of the completion menu. You may prevent the menu from automatically showing by setting `completion.menu.auto_show = false` and manually showing it with the `show` keymap command.
+
+### Menu Draw <a href="./reference#completion-menu-draw"><Badge type="info" text="Go to default configuration" /></a>
+
+blink.cmp uses a grid-based layout to render the completion menu. The components, defined in `draw.components[string]`, define `text` and `highlight` functions which are called for each completion item. The `highlight` function will be called only when the item appears on screen, so expensive operations such as Treesitter highlighting may be performed (contributions welcome!, [for example](https://www.reddit.com/r/neovim/comments/1ca4gm2/colorful_cmp_menu_powered_by_treesitter/)). The components may define their min and max width, where `ellipsis = true` (enabled by default), will draw the `…` character when the text is truncated. Setting `width.fill = true` will fill the remaining space, effectively making subsequent components right aligned, with respect to their column.
+
+Columns effectively allow you to vertically align a set of components. Each column, defined as an array in `draw.columns`, will be rendered for all of the completion items, where the longest rendered row will determine the width of the column. You may define `gap = number` in your column to insert a gap between components.
+
+For a setup similar to nvim-cmp, use the following config:
+
+```lua
+completion.menu.draw.columns = { { "label", "label_description", gap = 1 }, { "kind_icon", "kind" } },
+```
+
+## Documentation <a href="./reference#completion-documentation"><Badge type="info" text="Go to default configuration" /></a>
+
+By default, the documentation window will only show when triggered by the `show_documentation` keymap command. However, you may add the following configuration to show the documentation whenever an item is selected.
+
+```lua
+completion.documentation = {
+  auto_show = true,
+  auto_show_delay_ms = 500,
+}
+```
+
+If you're noticing high CPU usage or stuttering when opening the documentation, you may try setting `completion.documentation.treesitter_highlighting = false`.
+
+## Ghost Text <a href="./reference#completion-ghost-text"><Badge type="info" text="Go to default configuration" /></a>
+
+Ghost text shows a preview of the currently selected item as virtual text inline. You may want to try setting `completion.menu.auto_show = false` and enabling ghost text, or you may use both in parallel. 
+
+```lua
+completion.ghost_text.enabled = true
+```
+
+<img src="https://github.com/user-attachments/assets/1d30ef90-3ba4-43ca-a1a6-faa70f830e17" />

docs/configuration/fuzzy.md

@@ -0,0 +1,30 @@
+# Fuzzy
+
+Blink uses a SIMD fuzzy matcher called [frizbee](https://github.com/saghen/frizbee) which achieves ~6x the performance of fzf while ignoring typos. Check out the repo for more information!
+
+## Installation
+
+### Prebuilt binaries (default on a release tag)
+
+By default, Blink will download a prebuilt binary from the latest release, when you're on a release tag (via `version = '*'` on `lazy.nvim` for example). If you're not on a release tag, you may force a specific version via `fuzzy.prebuilt_binaries.force_version`. See [the latest release](https://github.com/saghen/blink.cmp/releases/latest) for supported systems. See `prebuilt_binaries` section of the [reference configuration](./reference.md#prebuilt-binaries) for more options.
+
+You may instead install the prebuilt binaries manually by downloading the appropriate binary from the [latest release](https://github.com/saghen/blink.cmp/releases/latest) and placing it at `$data/lazy/blink.cmp/target/release/libblink_cmp_fuzzy.$ext`. Get the `$data` path via `:echo stdpath('data')`. Use `.so` for linux, `.dylib` for mac, and `.dll` for windows. If you're unsure whether you want `-musl` or `-gnu` for linux, you very likely want `-gnu`.
+
+```sh
+# Linux
+~/.local/share/nvim/lazy/blink.cmp/target/release/libblink_cmp_fuzzy.so
+
+# Mac
+~/.local/share/nvim/lazy/blink.cmp/target/release/libblink_cmp_fuzzy.dylib
+
+# Windows
+~/Appdata/Local/nvim/lazy/blink.cmp/target/release/libblink_cmp_fuzzy.dll
+```
+
+### Build from source (recommended for `main`)
+
+When on `main`, it's highly recommended to build from source via `cargo build --release` (via `build = '...'` on `lazy.nvim` for example). This requires a nightly rust toolchain, which will be automatically downloaded when using `rustup`.
+
+## Configuration
+
+See the [fuzzy section of the reference configuration](./reference.md#fuzzy)

docs/configuration/general.md

@@ -0,0 +1,59 @@
+# General
+
+Blink cmp has *a lot* of configuration options, the following code block highlights some changes you're most likely to care about. For more information, check out the additional pages.
+
+For more common configurations, see the [recipes](./recipes.md).
+
+```lua
+{
+  -- Disable for some filetypes
+  enabled = function()
+    return not vim.tbl_contains({ "lua", "markdown" }, vim.bo.filetype)
+      and vim.bo.buftype ~= "prompt"
+      and vim.b.completion ~= false
+  end,
+
+  completion = {
+    -- 'prefix' will fuzzy match on the text before the cursor
+    -- 'full' will fuzzy match on the text before *and* after the cursor
+    -- example: 'foo_|_bar' will match 'foo_' for 'prefix' and 'foo__bar' for 'full'
+    keyword = { range = 'full' },
+
+    -- Disable auto brackets
+    -- NOTE: some LSPs may add auto brackets themselves anyway
+    accept = { auto_brackets = { enabled = false }, }
+
+    -- Insert completion item on selection, don't select by default
+    list = { selection = 'auto_insert' },
+
+    menu = {
+      -- Don't automatically show the completion menu
+      auto_show = false,
+
+      -- nvim-cmp style menu
+      draw = {
+        columns = {
+          { "label", "label_description", gap = 1 },
+          { "kind_icon", "kind" }
+        },
+      }
+    },
+
+    -- Show documentation when selecting a completion item
+    documentation = { auto_show = true, auto_show_delay_ms = 500 },
+
+    -- Display a preview of the selected item on the current line
+    ghost_text = { enabled = true },
+  },
+
+  sources = {
+    -- Remove 'buffer' if you don't want text completions, by default it's only enabled when LSP returns no items
+    default = { 'lsp', 'path', 'snippets', 'buffer' },
+    -- Disable cmdline completions
+    cmdline = {},
+  }
+
+  -- Experimental signature help support
+  signature = { enabled = true }
+}
+```