feat(capture): Support for "prepend" as field in capture templates

doc/orgmode.txt

@@ -982,6 +982,9 @@ Templates have the following fields:
     capture content will be added. If a function is provided, it will be called during
     refile with the destination file as its argument and must return the headline title as string. If no headline is specified,
     the content will be appended to the end of the file
+- `prepend` (`boolean`) - captured items are by default added as the last item at
+    the specfied target, setting this field places captured items as the first item
+    at the target
 - `datetree (boolean | { time_prompt?: boolean, reversed?: boolean, tree_type: 'day' | 'month' | 'week' | 'custom' })`
     Create a date tree <https://orgmode.org/manual/Template-elements.html#FOOT84> with current day in the target file and put the capture content there.
     - `true` - Create ascending datetree (newer dates go to end) with the current date

docs/configuration.org

@@ -923,6 +923,9 @@ Templates have the following fields:
   capture content will be added. If a function is provided, it will be called during
   refile with the destination file as its argument and must return the headline title as string. If no headline is specified,
   the content will be appended to the end of the file
+- =prepend= (=boolean=) --- captured items are by default added as the last item at
+    the specfied target, setting this field places captured items as the first item
+    at the target
 - =datetree (boolean | { time_prompt?: boolean, reversed?: boolean, tree_type: 'day' | 'month' | 'week' | 'custom' })=
   Create a [[https://orgmode.org/manual/Template-elements.html#FOOT84][date tree]] with current day in the target file and put the capture content there.
   - =true= - Create ascending datetree (newer dates go to end) with the current date

lua/orgmode/capture/init.lua

@@ -167,9 +167,16 @@ function Capture:_refile_from_capture_buffer(opts)
   local target_line = -1
   local destination_file = opts.destination_file
   local destination_headline = opts.destination_headline
+  local prepend = opts.template.prepend
 
   if destination_headline then
-    target_line = destination_headline:get_range().end_line
+    if prepend then
+      target_line = destination_headline:get_range().start_line
+    else
+      target_line = destination_headline:get_range().end_line
+    end
+  elseif prepend then
+    target_line = 0
   end
 
   if opts.template.datetree then

lua/orgmode/capture/template/init.lua

@@ -83,6 +83,7 @@ local expansions = {
 ---@field template? string|string[]
 ---@field target? string
 ---@field datetree? OrgCaptureTemplateDatetree
+---@field prepend? boolean
 ---@field headline? string|fun(OrgFile?):string
 ---@field regexp? string
 ---@field properties? OrgCaptureTemplateProperties
@@ -103,6 +104,7 @@ function Template:new(opts)
   vim.validate('target', opts.target, 'string', true)
   vim.validate('regexp', opts.regexp, 'string', true)
   vim.validate('headline', opts.headline, { 'string', 'function' }, true)
+  vim.validate('prepend', opts.prepend, 'boolean', true)
   vim.validate('properties', opts.properties, 'table', true)
   vim.validate('subtemplates', opts.subtemplates, 'table', true)
   vim.validate('datetree', opts.datetree, { 'boolean', 'table' }, true)
@@ -113,6 +115,7 @@ function Template:new(opts)
   this.template = opts.template or ''
   this.target = opts.target or ''
   this.headline = opts.headline
+  this.prepend = opts.prepend
   this.properties = TemplateProperties:new(opts.properties)
   this.datetree = opts.datetree
   this.regexp = opts.regexp

tests/plenary/capture/capture_spec.lua

@@ -296,6 +296,52 @@ describe('Capture', function()
       '',
     }, vim.api.nvim_buf_get_lines(0, 0, -1, false))
   end)
+  it('to beginning', function()
+    local destination_file = helpers.create_file({
+      '* foobar',
+      '        ',
+      '',
+      '\t\t\t\t',
+      '',
+    })
+
+    local capture_lines = { '** baz' }
+    local capture_file = helpers.create_file(capture_lines)
+
+    local template = Template:new({
+      prepend = true,
+      properties = {
+        empty_lines = {
+          before = 2,
+          after = 1,
+        },
+      },
+    })
+    local capture_window = CaptureWindow:new({ template = template })
+    assert(capture_file)
+    local item = capture_file:get_headlines()[1]
+
+    ---@diagnostic disable-next-line: invisible
+    org.capture:_refile_from_capture_buffer({
+      destination_file = destination_file,
+      source_file = capture_file,
+      source_headline = item,
+      template = template,
+      capture_window = capture_window,
+    })
+    vim.cmd('edit ' .. vim.fn.fnameescape(destination_file.filename))
+    assert.are.same({
+      '',
+      '',
+      '* baz',
+      '',
+      '* foobar',
+      '        ',
+      '',
+      '\t\t\t\t',
+      '',
+    }, vim.api.nvim_buf_get_lines(0, 0, -1, false))
+  end)
   it('to headline', function()
     local destination_file = helpers.create_file({
       '* foobar',