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