feat: add workflow for vimdocs via panvimdoc

.github/workflows/docs.yaml

@@ -29,4 +29,4 @@ jobs:
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          command: pages deploy docs/.vitepress/dist --project-name=blink-cmp-main
+          command: pages deploy doc/.vitepress/dist --project-name=blink-cmp-main

.github/workflows/panvimdoc.yaml

@@ -0,0 +1,31 @@
+# TODO: doesn't handle `::: warning` blocks
+# TODO: doesn't handle links to other files
+
+name: Update vimdocs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - doc/**
+      - .github/workflows/panvimdoc.yaml
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: kdheepak/panvimdoc@main
+        with:
+          vimdoc: blink-cmp
+          pandoc: doc/vimdoc.md
+          version: NVIM v0.10.0
+          shiftheadinglevelby: 0
+          incrementheadinglevelby: 0
+      - uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "docs: update vimdocs"
+          branch: ${{ github.head_ref }}

.github/workflows/release.yaml

@@ -133,4 +133,4 @@ jobs:
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          command: pages deploy docs/.vitepress/dist --project-name=blink-cmp
+          command: pages deploy doc/.vitepress/dist --project-name=blink-cmp

README.md

@@ -3,7 +3,7 @@
 
 # Blink Completion (blink.cmp)
 
-**blink.cmp** is a completion plugin with support for LSPs and external sources that updates on every keystroke with minimal overhead (0.5-4ms async). It use a [custom fuzzy matcher](https://github.com/saghen/frizbee) to easily handle >20k items. It provides extensibility via pluggable sources (LSP, snippets, etc), component based rendering and scripting for the configuration.
+**blink.cmp** is a completion plugin with support for LSPs and external sources that updates on every keystroke with minimal overhead (0.5-4ms async). It use a [custom fuzzy matcher](https://github.com/saghen/frizbee) to easily handle 20k+ items. It provides extensibility via pluggable sources (LSP, snippets, etc), component based rendering and scripting for the configuration.
 
 <https://github.com/user-attachments/assets/9849e57a-3c2c-49a8-959c-dbb7fef78c80>
 

docs/.vitepress/theme/style.css → doc/.vitepress/theme/style.css

@@ -19,3 +19,17 @@ code {
   --vp-badge-info-bg: rgb(55, 77, 113); /* Darker version of --vp-c-brand-2 */
   --vp-badge-info-text: var(--vp-c-white);
 }
+
+/* Alerts */
+
+.custom-block.warning {
+  border-color: var(--vp-custom-block-important-border);
+  color: var(--vp-custom-block-important-text);
+  background-color: var(--vp-custom-block-important-bg);
+}
+
+.custom-block.info {
+  border-color: var(--vp-custom-block-note-border);
+  color: var(--vp-custom-block-note-text);
+  background-color: var(--vp-custom-block-note-bg);
+}

docs/configuration/appearance.md → doc/configuration/appearance.md

@@ -1,7 +1,7 @@
 ---
 title: Appearance
 ---
-# Appearance <Badge type="info"><a href="./reference#appearance">Go to default configuration</a></Badge>
+# Appearance<!-- panvimdoc-ignore-start --> <Badge type="info"><a href="./reference#appearance">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
 
 If you're looking for how to change the appearance of the completion menu, check out the [menu draw configuration](./completion#completion-menu-draw).
 

docs/configuration/completion.md → doc/configuration/completion.md

@@ -2,7 +2,9 @@
 
 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 <Badge type="info"><a href="./reference#completion-keyword">Go to default configuration</a></Badge>
+<!-- panvimdoc-include-comment The online documentation contains images and videos for each section. You may have a better experience viewing the docs on that website: https://cmp.saghen.dev/configuration/completion -->
+
+## Keyword <!-- panvimdoc-ignore-start --><Badge type="info"><a href="./reference#completion-keyword">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
 
 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.
 
@@ -13,7 +15,16 @@ Controls what the plugin considers to be a keyword, used for fuzzy matching and
 <img src="https://github.com/user-attachments/assets/3e082492-6a5d-4dba-b4ba-6a1bfca50351" />
 :::
 
-## Trigger <Badge type="info"><a href="./reference#completion-trigger">Go to default configuration</a></Badge>
+<!-- panvimdoc-include-comment
+```lua
+-- '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'
+completion.keyword.range = 'prefix' | 'full'
+```
+-->
+
+## Trigger <!-- panvimdoc-ignore-start --><Badge type="info"><a href="./reference#completion-trigger">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
 
 Controls when to request completion items from the sources and show the completion menu. The following options are available, excluding their `show_on` prefix:
 
@@ -64,7 +75,56 @@ completion.trigger.show_on_x_blocked_trigger_characters = { "'", '"', '(', '{',
 TODO: Find a case where this actually fires : )
 :::
 
-## List <Badge type="info"><a href="./reference#completion-list">Go to default configuration</a></Badge>
+<!-- panvimdoc-include-comment
+### Keyword
+
+Shows after typing a keyword, typically an alphanumeric character, `-` or `_`
+
+```lua
+completion.trigger.show_on_keyword = true
+```
+
+Video: https://github.com/user-attachments/assets/5e8f8f9f-bc6a-4d21-9cce-2e291b6a7de8
+
+### Trigger Character
+
+Shows after typing a trigger character, defined by the sources. For example for Lua or Rust, the LSP will define `.` as a trigger character.
+
+```lua
+completion.trigger.show_on_trigger_character = true
+-- Optionally, set a list of characters that will not trigger the completion window,
+-- even when sources request it. The following are the defaults:
+completion.trigger.show_on_blocked_trigger_characters = { ' ', '\n', '\t' }
+```
+
+Video: https://github.com/user-attachments/assets/b4ee0069-2de8-44e7-b3ca-51b10bc4cb4a
+
+### Insert on Trigger Character
+
+Shows after entering insert mode on top of a trigger character.
+
+```lua
+completion.trigger.show_on_insert_on_trigger_character = true
+-- Optionally, set a list of characters that will not trigger the completion window,
+-- even when sources request it. The following are the defaults:
+completion.trigger.show_on_x_blocked_trigger_characters = { "'", '"', '(', '{', '[' }
+```
+
+Video: https://github.com/user-attachments/assets/9e7aa3c2-4756-4a5e-a0e8-303d3ae0fda9
+
+### Accept on Trigger Character
+
+Shows after accepting a completion item, where the cursor ends up on top of a trigger character.
+
+```lua
+completion.trigger.show_on_accept_on_trigger_character = true
+-- Optionally, set a list of characters that will not trigger the completion window,
+-- even when sources request it. The following are the defaults:
+completion.trigger.show_on_x_blocked_trigger_characters = { "'", '"', '(', '{', '[' }
+```
+-->
+
+## List <!-- panvimdoc-ignore-start --><Badge type="info"><a href="./reference#completion-list">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
 
 Manages the completion list and its behavior when selecting items. The most commonly changed option is `selection.preselect/auto_insert`, which controls whether the list will automatically select the first item in the list, and whether a "preview" will be inserted on selection.
 
@@ -108,6 +168,51 @@ You may use the `show_and_insert` keymap to show the completion menu and select
 <video src="https://github.com/user-attachments/assets/4658b61d-1b95-404a-b6b5-3a4afbfb8112" muted autoplay loop />
 :::
 
+<!-- panvimdoc-include-comment
+### Preselect, Auto Insert (default)
+
+```lua
+completion.list.selection = { preselect = true, auto_insert = true }
+```
+
+Selects the first item automatically, and inserts a preview of the item on selection. The `cancel` keymap (default `<C-e>`) will close the menu and undo the preview.
+
+You may use the `show_and_insert` keymap to show the completion menu and select the first item, with `auto_insert`. The default keymap (`<C-space>`) uses the `show` command, which will have the first item selected, but will not `auto_insert`.
+
+Video: https://github.com/user-attachments/assets/ef295526-8332-4ad0-9a2a-e2f6484081b2
+
+### Preselect
+```lua
+completion.list.selection = { preselect = true, auto_insert = false }
+```
+
+Selects the first item automatically
+
+Video: https://github.com/user-attachments/assets/69079ced-43f1-437e-8a45-3cb13f841d61
+
+### Manual
+```lua
+completion.list.selection = { preselect = false, auto_insert = false }
+```
+
+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.
+
+You may use the `show_and_insert` keymap to show the completion menu and select the first item. The default keymap (`<C-space>`) uses the `show` command, which will not select the first item.
+
+Video: https://github.com/user-attachments/assets/09cd9b4b-18b3-456b-bb0a-074ae54e9d77
+
+### Manual, Auto Insert
+```lua
+completion.list.selection = { preselect = false, auto_insert = true }
+```
+
+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 will only trigger if an item is selected. The `cancel` keymap (default `<C-e>`) will close the menu and undo the preview.
+
+You may use the `show_and_insert` keymap to show the completion menu and select the first item, with `auto_insert`. The default keymap (`<C-space>`) uses the `show` command, which will not select the first item.
+
+Video: https://github.com/user-attachments/assets/4658b61d-1b95-404a-b6b5-3a4afbfb8112
+-->
+
 To control the selection behavior per mode, pass a function to `selection.preselect/auto_insert`:
 
 ```lua
@@ -124,24 +229,25 @@ completion.list.selection = {
 ```
 
 
-## Accept <Badge type="info"><a href="./reference#completion-accept">Go to default configuration</a></Badge>
+## Accept <!-- panvimdoc-ignore-start --><Badge type="info"><a href="./reference#completion-accept">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
 
 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
+::: info
+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 <Badge type="info"><a href="./reference#completion-menu">Go to default configuration</a></Badge>
+## Menu <!-- panvimdoc-ignore-start --><Badge type="info"><a href="./reference#completion-menu">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
 
 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 <Badge type="info"><a href="./reference#completion-menu-draw">Go to default configuration</a></Badge>
+### Menu Draw <!-- panvimdoc-ignore-start --><Badge type="info"><a href="./reference#completion-menu-draw">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
 
 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. 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.
 
@@ -174,7 +280,7 @@ completion.menu.draw.treesitter = { 'lsp' }
 
 The wonderful [colorful-menu.nvim](https://github.com/xzbdmw/colorful-menu.nvim) takes this a step further by including context around the item before highlighting.
 
-## Documentation <Badge type="info"><a href="./reference#completion-documentation">Go to default configuration</a></Badge>
+## Documentation <!-- panvimdoc-ignore-start --><Badge type="info"><a href="./reference#completion-documentation">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
 
 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.
 
@@ -187,9 +293,9 @@ completion.documentation = {
 
 If you're noticing high CPU usage or stuttering when opening the documentation, you may try setting `completion.documentation.treesitter_highlighting = false`. You may completely override the drawing of the window via `completion.documentation.draw`.
 
-## Ghost Text <Badge type="info"><a href="./reference#completion-ghost-text">Go to default configuration</a></Badge>
+## Ghost Text <!-- panvimdoc-ignore-start --><Badge type="info"><a href="./reference#completion-ghost-text">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
 
-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. 
+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

docs/configuration/general.md → doc/configuration/general.md

@@ -4,7 +4,9 @@ Blink cmp has *a lot* of configuration options, the following code block highlig
 
 For more common configurations, see the [recipes](../recipes.md).
 
-> [!IMPORTANT] Do not copy this entire configuration! It contains only non-default options
+::: warning
+**Do not copy this entire configuration! It contains only non-default options**
+:::
 
 ```lua
 {

docs/configuration/reference.md → doc/configuration/reference.md

@@ -1,7 +1,8 @@
 # Reference
 
-> [!IMPORTANT]
-> Do not copy the default configuration! Only include options you want to change in your configuration
+::: warning
+Do not copy the default configuration! Only include options you want to change in your configuration
+:::
 
 ```lua
 -- Enables keymaps, completions and signature help when true
@@ -583,8 +584,9 @@ cmdline = {
 
 ### Terminal
 
-> [!NOTE]
-> Terminal completions are nightly only! Known bugs in v0.10
+::: warning
+Terminal completions are nightly only! Known bugs in v0.10
+:::
 
 ```lua
 term = {

docs/configuration/signature.md → doc/configuration/signature.md

@@ -1,10 +1,11 @@
 ---
 title: Signature
 ---
-# Signature <Badge type="info"><a href="./reference#signature">Go to default configuration</a></Badge>
+# Signature<!-- panvimdoc-ignore-start --> <Badge type="info"><a href="./reference#signature">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
 
-> [!IMPORTANT]
-> This feature is *experimental*, contributions welcome!
+::: info
+This feature is *experimental*, [contributions welcome](https://github.com/Saghen/blink.cmp/issues/1071)!
+:::
 
 Blink supports signature help, automatically triggered when typing trigger characters, defined by the LSP, such as `(` for `lua`. The menu will be updated when pressing a retrigger character, such as `,`. Due to it being experimental, this feature is opt-in.
 

docs/configuration/snippets.md → doc/configuration/snippets.md

@@ -1,7 +1,7 @@
 ---
 title: Snippets
 ---
-# Snippets <Badge type="info"><a href="./reference#snippets">Go to default configuration</a></Badge>
+# Snippets<!-- panvimdoc-ignore-start --> <Badge type="info"><a href="./reference#snippets">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
 
 Blink uses the `vim.snippet` API by default for expanding and navigating snippets. The built-in `snippets` source will load [friendly-snippets](https://github.com/rafamadriz/friendly-snippets), if available, and load any snippets found at `~/.config/nvim/snippets/`. For use with Luasnip, see the [Luasnip section](#luasnip).
 

docs/configuration/sources.md → doc/configuration/sources.md

@@ -1,10 +1,10 @@
 ---
 title: Sources
 ---
-# Sources <Badge type="info"><a href="./reference#sources">Go to default configuration</a></Badge>
-
-> [!NOTE]
-> Check out the [recipes](../recipes.md) for some common configurations
+# Sources<!-- panvimdoc-ignore-start --> <Badge type="info"><a href="./reference#sources">Go to default configuration</a></Badge><!-- panvimdoc-ignore-end -->
+::: info
+Check out the [recipes](../recipes.md) for some common configurations
+:::
 
 Blink provides a sources interface, modelled after LSPs, for getting completion items, trigger characters, documentation and signature help. The `lsp`, `path`, `snippets`, `luasnip`, `buffer`, and `omni` sources are built-in. You may add additional [community sources](#community-sources) as well. Check out [writing sources](../development/writing-sources.md) to learn how to write your own!
 
@@ -53,8 +53,9 @@ sources.providers.lsp = {
 
 ## Terminal and Cmdline Sources
 
-> [!NOTE]
-> Terminal completions are nightly only! Known bugs in v0.10. Cmdline completions are supported on all versions
+::: info
+Terminal completions are nightly only! Known bugs in v0.10. Cmdline completions are supported on all versions
+:::
 
 You may use `cmdline` and `term` sources via the `cmdline.sources` and `term.sources` tables. You may see the defaults in the [reference](./reference.md#mode-specific). There's no source for shell completions at the moment, [contributions welcome](https://github.com/Saghen/blink.cmp/issues/1149)! 
 

docs/index.md → doc/index.md

@@ -1,9 +1,10 @@
-# Blink Completion (blink.cmp)
+# Introduction
 
-> [!IMPORTANT]
-> This plugin is *beta* quality. Expect breaking changes and many bugs
+::: warning
+This plugin is *beta* quality. Expect breaking changes and many bugs
+:::
 
-**blink.cmp** is a completion plugin with support for LSPs and external sources that updates on every keystroke with minimal overhead (0.5-4ms async). It use a [custom fuzzy matcher](https://github.com/saghen/frizbee) to easily handle >20k items. It provides extensibility via pluggable sources (LSP, snippets, etc), component based rendering and scripting for the configuration.
+**blink.cmp** is a completion plugin with support for LSPs and external sources that updates on every keystroke with minimal overhead (0.5-4ms async). It use a [custom fuzzy matcher](https://github.com/saghen/frizbee) to easily handle 20k+ items. It provides extensibility via pluggable sources (LSP, snippets, etc), component based rendering and scripting for the configuration.
 
 <video controls autoplay muted src="https://github.com/user-attachments/assets/9849e57a-3c2c-49a8-959c-dbb7fef78c80"></video>