docs: config example for special buf (xxx://) support

README.md

@@ -60,8 +60,9 @@
     - [Making a Source With Drop-Down Menus](#making-a-source-with-drop-down-menus)
     - [Default `on_click()` Callback](#default-on_click-callback)
     - [Lazy-Loading Expensive Fields](#lazy-loading-expensive-fields)
-    - [Practical Examples](#practical-examples)
-      - [Highlight File Name Using Custom Highlight Group `DropBarFileName`](#highlight-file-name-using-custom-highlight-group-dropbarfilename)
+- [Configuration Examples](#configuration-examples)
+  - [Highlight File Name Using Custom Highlight Group `DropBarFileName`](#highlight-file-name-using-custom-highlight-group-dropbarfilename)
+  - [Enable Path Source in Special Plugin Buffers, e.g. Oil or Fugitive](#enable-path-source-in-special-plugin-buffers-eg-oil-or-fugitive)
 - [Similar Projects](#similar-projects)
 <!--toc:end-->
 
@@ -1993,9 +1994,9 @@ local custom_source = {
 To see concrete examples of lazy-loading see
 [`lua/dropbar/sources`](lua/dropbar/sources).
 
-#### Practical Examples
+## Configuration Examples
 
-##### Highlight File Name Using Custom Highlight Group `DropBarFileName`
+### Highlight File Name Using Custom Highlight Group `DropBarFileName`
 
 ```lua
 local dropbar = require('dropbar')
@@ -2042,6 +2043,61 @@ dropbar.setup({
 })
 ```
 
+### Enable Path Source in Special Plugin Buffers, e.g. Oil or Fugitive
+
+```lua
+require('dropbar').setup({
+  bar = {
+    enable = function(buf, win, _)
+      if
+        not vim.api.nvim_buf_is_valid(buf)
+        or not vim.api.nvim_win_is_valid(win)
+        or vim.fn.win_gettype(win) ~= ''
+        or vim.wo[win].winbar ~= ''
+        or vim.bo[buf].ft == 'help'
+      then
+        return false
+      end
+
+      local stat = vim.uv.fs_stat(vim.api.nvim_buf_get_name(buf))
+      if stat and stat.size > 1024 * 1024 then
+        return false
+      end
+
+      return vim.bo[buf].ft == 'markdown'
+        or vim.bo[buf].ft == 'oil' -- enable in oil buffers
+        or vim.bo[buf].ft == 'fugitive' -- enable in fugitive buffers
+        or pcall(vim.treesitter.get_parser, buf)
+        or not vim.tbl_isempty(vim.lsp.get_clients({
+          bufnr = buf,
+          method = 'textDocument/documentSymbol',
+        }))
+    end,
+  },
+  sources = {
+    path = {
+      relative_to = function(buf, win)
+        -- Show full path in oil or fugitive buffers
+        local bufname = vim.api.nvim_buf_get_name(buf)
+        if
+          vim.startswith(bufname, 'oil://')
+          or vim.startswith(bufname, 'fugitive://')
+        then
+          local root = bufname:gsub('^%S+://', '', 1)
+          while root and root ~= vim.fs.dirname(root) do
+            root = vim.fs.dirname(root)
+          end
+          return root
+        end
+
+        local ok, cwd = pcall(vim.fn.getcwd, win)
+        return ok and cwd or vim.fn.getcwd()
+      end,
+    },
+  },
+})
+```
+
 ## Similar Projects
 
 - [nvim-navic](https://github.com/SmiteshP/nvim-navic)

doc/dropbar.txt

@@ -46,8 +46,8 @@ CONTENTS                                           *dropbar-table-of-contents*
     6.3.1 Making a source with drop-down menus |dropbar-developers-making-a-source-with-drop-down-menus|
     6.3.2 Default `on_click()` callback |dropbar-developers-default-on_click-callback|
     6.3.3 Lazy-loading expensive fields |dropbar-developers-lazy-loading-expensive-fields|
-    6.3.4 Practical Examples |dropbar-developers-making-a-new-source-practical-examples|
-7. Similar Projects                                 |dropbar-similar-projects|
+7. Configuration Examples |dropbar-developers-making-a-new-source-configuration-examples|
+8. Similar Projects                                 |dropbar-similar-projects|
 
 
 ==============================================================================
@@ -2804,8 +2804,8 @@ menu is opened: >lua
 <
 
 ..............................................................................
-PRACTICAL EXAMPLES
-*dropbar-developers-making-a-new-source-practical-examples*
+CONFIGURATION EXAMPLES
+*dropbar-developers-making-a-new-source-configuration-examples*
 
 Highlight file name using custom highlight group `DropBarFileName`: >lua
 
@@ -2858,6 +2858,60 @@ Highlight file name using custom highlight group `DropBarFileName`: >lua
 
 To see concrete examples of lazy-loading, see `lua/dropbar/sources`.
 
+Enable path source in special plugin buffers, e.g. `oil` or `fugitive`: >lua
+
+    require('dropbar').setup({
+      bar = {
+	enable = function(buf, win, _)
+	  if
+	    not vim.api.nvim_buf_is_valid(buf)
+	    or not vim.api.nvim_win_is_valid(win)
+	    or vim.fn.win_gettype(win) ~= ''
+	    or vim.wo[win].winbar ~= ''
+	    or vim.bo[buf].ft == 'help'
+	  then
+	    return false
+	  end
+
+	  local stat = vim.uv.fs_stat(vim.api.nvim_buf_get_name(buf))
+	  if stat and stat.size > 1024 * 1024 then
+	    return false
+	  end
+
+	  return vim.bo[buf].ft == 'markdown'
+	    or vim.bo[buf].ft == 'oil' -- enable in oil buffers
+	    or vim.bo[buf].ft == 'fugitive' -- enable in fugitive buffers
+	    or pcall(vim.treesitter.get_parser, buf)
+	    or not vim.tbl_isempty(vim.lsp.get_clients({
+	      bufnr = buf,
+	      method = 'textDocument/documentSymbol',
+	    }))
+	end,
+      },
+      sources = {
+	path = {
+	  relative_to = function(buf, win)
+	    -- Show full path in oil or fugitive buffers
+	    local bufname = vim.api.nvim_buf_get_name(buf)
+	    if
+	      vim.startswith(bufname, 'oil://')
+	      or vim.startswith(bufname, 'fugitive://')
+	    then
+	      local root = bufname:gsub('^%S+://', '', 1)
+	      while root and root ~= vim.fs.dirname(root) do
+		root = vim.fs.dirname(root)
+	      end
+	      return root
+	    end
+
+	    local ok, cwd = pcall(vim.fn.getcwd, win)
+	    return ok and cwd or vim.fn.getcwd()
+	  end,
+	},
+      },
+    })
+<
+
 ==============================================================================
 SIMILAR PROJECTS                                    *dropbar-similar-projects*