docs: document org_agenda_prefix_format

Author: swapnilsm

doc/orgmode.txt

@@ -845,6 +845,59 @@ Separator used to separate multiple agenda views generated by
 `@org.agenda.separator` hl group.
 
 
+org_agenda_prefix_format                    *orgmode-org_agenda_prefix_format*
+
+- Type: `{ agenda?: string, todo?: string, tags?: string, search?: string,
+    tags_todo?: string }`
+- Default:
+    >lua
+        {
+          agenda = '  %-12:c%?t% s',
+          todo = '  %-12:c',
+          tags = '  %-12:c',
+          tags_todo = '  %-12:c',
+          search = '  %-12:c',
+        }
+    <
+
+Format for the prefix of each line in the agenda view. The format string can
+contain placeholders that will be replaced with actual values. Format of the
+placeholder: `%[specifiers][variable]` or `%[specifiers](lua expression)`.
+
+**Specifiers:**
+
+- `-` - Left align the value (default is right align)
+- `[number]` - Set fixed width for the value
+- `?` - Optional placeholder. If the value is empty, the placeholder (and surrounding spaces) will be omitted.
+
+**Variables:**
+
+- `c` - Category of the headline
+- `:c` - Category of the headline followed by a colon
+- `s` - Planning info (Deadline, Scheduled, etc.)
+- `t` - Time range (e.g. 10:00-11:00)
+- `T` - Tags
+- `e` - Effort property
+- `l` - Headline level
+- `b` - Breadcrumbs (parent headline titles separated by `->`)
+
+**Lua expressions:** Anything inside `%()` will be evaluated as a Lua
+expression. The expression has access to following variables:
+
+- `headline` - |orgmode-orgheadline| object
+- `item` - |orgmode-orgagendaitem| object (only in `agenda` view)
+- `metadata` - Metadata table containing `category_length`
+
+Example:
+
+>lua
+    org_agenda_prefix_format = {
+      agenda = ' %-12:c %?t %s ',
+      todo = ' %-12:c %(headline:get_property("PRIORITY") or "C") '
+    }
+<
+
+
 org_agenda_remove_tags                        *orgmode-org_agenda_remove_tags*
 
 - Type: `boolean`

docs/configuration.org

@@ -788,6 +788,56 @@ Separator used to separate multiple agenda views generated by
 [[#org_agenda_custom_commands][org_agenda_custom_commands]].
 To change the highlight, override =@org.agenda.separator= hl group.
 
+*** org_agenda_prefix_format
+:PROPERTIES:
+:CUSTOM_ID: org_agenda_prefix_format
+:END:
+- Type: ={ agenda?: string, todo?: string, tags?: string, search?: string, tags_todo?: string }=
+- Default:
+  #+begin_src lua
+  {
+    agenda = '  %-12:c%?t% s',
+    todo = '  %-12:c',
+    tags = '  %-12:c',
+    tags_todo = '  %-12:c',
+    search = '  %-12:c',
+  }
+  #+end_src
+
+Format for the prefix of each line in the agenda view.
+The format string can contain placeholders that will be replaced with actual values.
+Format of the placeholder: =%[specifiers][variable]= or =%[specifiers](lua expression)=.
+
+*Specifiers:*
+- =-= - Left align the value (default is right align)
+- =[number]= - Set fixed width for the value
+- =?= - Optional placeholder. If the value is empty, the placeholder (and surrounding spaces) will be omitted.
+
+*Variables:*
+- =c= - Category of the headline
+- =:c= - Category of the headline followed by a colon
+- =s= - Planning info (Deadline, Scheduled, etc.)
+- =t= - Time range (e.g. 10:00-11:00)
+- =T= - Tags
+- =e= - Effort property
+- =l= - Headline level
+- =b= - Breadcrumbs (parent headline titles separated by =->=)
+
+*Lua expressions:*
+Anything inside =%()= will be evaluated as a Lua expression.
+The expression has access to following variables:
+- =headline= - [[#org-headline][OrgHeadline]] object
+- =item= - [[#org-agenda-item][OrgAgendaItem]] object (only in =agenda= view)
+- =metadata= - Metadata table containing =category_length=
+
+Example:
+#+begin_src lua
+org_agenda_prefix_format = {
+  agenda = ' %-12:c %?t %s ',
+  todo = ' %-12:c %(headline:get_property("PRIORITY") or "C") '
+}
+#+end_src
+
 *** org_agenda_remove_tags
 :PROPERTIES:
 :CUSTOM_ID: org_agenda_remove_tags

lua/orgmode/agenda/agenda_item.lua

@@ -189,7 +189,6 @@ function AgendaItem:_generate_marker()
   return ''
 end
 
-
 function AgendaItem:_generate_label()
   local include_time = self.time ~= ''
   if (self.headline_date:is_deadline() or self.headline_date:is_scheduled()) and not self.is_same_day then

lua/orgmode/agenda/init.lua

@@ -156,7 +156,8 @@ function Agenda:_build_custom_commands()
     opts_by_type[opts.type].category_filter = opts.org_agenda_category_filter_preset
     opts_by_type[opts.type].highlighter = self.highlighter
     opts_by_type[opts.type].remove_tags = utils.if_nil(opts.org_agenda_remove_tags, parent_opts.org_agenda_remove_tags)
-    opts_by_type[opts.type].org_agenda_prefix_format = utils.if_nil(opts.org_agenda_prefix_format, parent_opts.org_agenda_prefix_format)
+    opts_by_type[opts.type].org_agenda_prefix_format =
+      utils.if_nil(opts.org_agenda_prefix_format, parent_opts.org_agenda_prefix_format)
     opts_by_type[opts.type].id = id
 
     return opts_by_type[opts.type]

lua/orgmode/agenda/types/todo.lua

@@ -108,8 +108,14 @@ function OrgAgendaTodosType:_get_header()
 end
 
 ---@param bufnr? number
-function OrgAgendaTodosType:render(bufnr)
+---@param current_line? number
+function OrgAgendaTodosType:render(bufnr, current_line)
   self.bufnr = bufnr or 0
+  local was_line_in_view = true
+  if self.view then
+    was_line_in_view = self.view:is_in_range(current_line)
+  end
+
   local headlines, category_length = self:_get_headlines()
 
   local prefix_formats = self.org_agenda_prefix_format or config.org_agenda_prefix_format
@@ -141,9 +147,25 @@ function OrgAgendaTodosType:render(bufnr)
   end
 
   self.view = agendaView:render()
+  if was_line_in_view then
+    self:_jump_to_item(current_line)
+  end
   return self.view
 end
 
+---@private
+function OrgAgendaTodosType:_jump_to_item(line)
+  local agenda_line = self:get_line(line)
+  if not agenda_line or not agenda_line.headline then
+    return
+  end
+  for _, l in ipairs(self.view.lines) do
+    if l.headline and l.headline:id_get_or_create() == agenda_line.headline:id_get_or_create() then
+      return vim.fn.cursor({ l.line_nr, 0 })
+    end
+  end
+end
+
 ---@private
 ---@param headline OrgHeadline
 ---@param metadata table<string, any>

tests/plenary/agenda/formatter_spec.lua

@@ -18,7 +18,7 @@ describe('Agenda formatter', function()
     local headline = generate_headline(string.format('<%s>', today:to_string()))
     local agenda_item = AgendaItem:new(headline:get_all_dates()[1], headline, today)
     local metadata = { category_length = 10 }
-    
+
     local format = '%c'
     local result = Formatter.format(format, agenda_item, metadata)
     assert.are.same('agenda_test', result)
@@ -86,16 +86,16 @@ describe('Agenda formatter', function()
     local headline = generate_headline(string.format('<%s>', today:to_string()))
     local agenda_item = AgendaItem:new(headline:get_all_dates()[1], headline, today)
     local metadata = { category_length = 10 }
-    
+
     -- Define a global function for testing
     _G.test_prefix = function()
-      return "SHORT"
+      return 'SHORT'
     end
 
     local format = '%(test_prefix())'
     local result = Formatter.format(format, agenda_item, metadata)
     assert.are.same('SHORT', result)
-    
+
     -- Test with width and alignment
     format = '%10(test_prefix())'
     result = Formatter.format(format, agenda_item, metadata)