From 7b16324c5ac7d94b31e005c5bf9741b137087103 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com>
Date: Mon, 16 Mar 2026 15:21:40 -0400
Subject: [PATCH] docs: add highlight-opened-file recipe (#450) (#145)

Problem: users wanted a visual indicator on the originating file when
opening a directory listing from a file buffer.

Solution: add `oil-recipe-highlight-opened-file` recipe that uses
`OilReadPost` to flash an extmark highlight on the cursor entry for
1.5 seconds after render.
---
 doc/oil.txt     | 38 ++++++++++++++++++++++++++++++++++++++
 doc/upstream.md |  2 +-
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/doc/oil.txt b/doc/oil.txt
index 74a92ba..fce558a 100644
--- a/doc/oil.txt
+++ b/doc/oil.txt
@@ -1232,6 +1232,44 @@ for compatibility with FreeDesktop-compliant trash programs like gtrash:
     package.loaded["oil.adapters.trash.mac"] = require("oil.adapters.trash.freedesktop")
 <
 
+Flash highlight on opened file ~
+                                              *oil-recipe-highlight-opened-file*
+
+When opening a directory from a file buffer, briefly highlight the originating
+file's name in the listing. Uses |OilReadPost| to apply a timed extmark after
+the buffer renders.
+>lua
+    local ns = vim.api.nvim_create_namespace("oil_highlight_entry")
+    vim.api.nvim_create_autocmd("User", {
+      pattern = "OilReadPost",
+      callback = function(args)
+        vim.defer_fn(function()
+          local bufnr = args.data.buf
+          if not vim.api.nvim_buf_is_valid(bufnr) then
+            return
+          end
+          vim.api.nvim_buf_clear_namespace(bufnr, ns, 0, -1)
+          local entry = require("oil").get_cursor_entry()
+          if not entry then
+            return
+          end
+          local lnum = vim.api.nvim_win_get_cursor(0)[1] - 1
+          local line = vim.api.nvim_buf_get_lines(bufnr, lnum, lnum + 1, true)[1]
+          local col = line:find(entry.name, 1, true)
+          if col then
+            vim.api.nvim_buf_set_extmark(bufnr, ns, lnum, col - 1, {
+              end_col = col - 1 + #entry.name,
+              hl_group = "Visual",
+            })
+            vim.defer_fn(function()
+              pcall(vim.api.nvim_buf_clear_namespace, bufnr, ns, 0, -1)
+            end, 1500)
+          end
+        end, 50)
+      end,
+    })
+<
+
 --------------------------------------------------------------------------------
 EVENTS                                                                *oil-events*
 
diff --git a/doc/upstream.md b/doc/upstream.md
index b032e28..537c07b 100644
--- a/doc/upstream.md
+++ b/doc/upstream.md
@@ -81,7 +81,7 @@ issues against this fork.
 | [#444](https://github.com/stevearc/oil.nvim/issues/444) | Opening behaviour customization                            | open                                                                                                                                                                                      |
 | [#446](https://github.com/stevearc/oil.nvim/issues/446) | Executable highlighting                                    | cherry-picked ([#698](https://github.com/stevearc/oil.nvim/pull/698))                                                                                                                     |
 | [#449](https://github.com/stevearc/oil.nvim/issues/449) | Renaming TypeScript files stopped working                  | not actionable — config issue, increase `lsp_file_methods.timeout_ms`                                                                                                                     |
-| [#450](https://github.com/stevearc/oil.nvim/issues/450) | Highlight opened file in directory listing                 | open                                                                                                                                                                                      |
+| [#450](https://github.com/stevearc/oil.nvim/issues/450) | Highlight opened file in directory listing                 | fixed — added `oil-recipe-highlight-opened-file`                                                                                                                                          |
 | [#457](https://github.com/stevearc/oil.nvim/issues/457) | Custom column API                                          | open                                                                                                                                                                                      |
 | [#466](https://github.com/stevearc/oil.nvim/issues/466) | Select into window on right                                | not actionable — user-land concern, custom action trivially solves this                                                                                                                   |
 | [#473](https://github.com/stevearc/oil.nvim/issues/473) | Show hidden when dir is all-hidden                         | fixed ([#85](https://github.com/barrettruth/canola.nvim/pull/85))                                                                                                                         |