diff --git a/lsp/buf_ls.lua b/lsp/buf_ls.lua
index 2d2f5a7efd..a06ff0b089 100644
--- a/lsp/buf_ls.lua
+++ b/lsp/buf_ls.lua
@@ -4,11 +4,31 @@
 --- buf lsp included in the cli itself
 ---
 --- buf lsp is a Protobuf language server compatible with Buf modules and workspaces
+---
+--- buf lsp also supports Buf configuration files. The `buf-config` filetype is not
+--- detected automatically; register it manually (see below) or override the filetypes:
+---
+--- ```lua
+--- vim.filetype.add({
+---   filename = {
+---     ['buf.yaml'] = 'buf-config',
+---     ['buf.gen.yaml'] = 'buf-config',
+---     ['buf.policy.yaml'] = 'buf-config',
+---     ['buf.lock'] = 'buf-config',
+---   },
+--- })
+--- ```
+---
+--- Optionally, tell treesitter to treat buf config files as YAML for syntax highlighting:
+---
+--- ```lua
+--- vim.treesitter.language.register('yaml', 'buf-config')
+--- ```
 
 ---@type vim.lsp.Config
 return {
   cmd = { 'buf', 'lsp', 'serve', '--log-format=text' },
-  filetypes = { 'proto' },
+  filetypes = { 'proto', 'buf-config' },
   root_markers = { 'buf.yaml', '.git' },
   reuse_client = function(client, config)
     -- `buf lsp serve` is meant to be used with multiple workspaces.