Feature: capture write position option to insert before line

[chhoumann]

Request

Add a capture write-position option to insert content before a matched line (sibling to "After line").

Why

This enables precise placement around headings or markers when the existing placement options are insufficient.

Notes

Current write-position options include top/bottom/after line and cursor-based options for the active file; there is no before-line option for target insertion.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• Add optional newline before Insert After operations #817
• Feature: cursor marker in QuickAdd templates and choice-type descriptions #1025

🔗 Related PRs

#986 - feat: Add write to top of file switch for capture to active file (#248) [merged]

👤 Suggested Assignees

• chhoumann

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Add a "Before line" capture write-position option that enables users to insert captured content before a matched line or heading, providing precise placement control as a complement to the existing "After line" option.

Observations

Codebase Summary

QuickAdd is an Obsidian plugin with a three-layer capture system architecture: type definitions (src/types/choices/), execution engines (src/engine/), and UI builders (src/gui/ChoiceBuilder/). The capture functionality includes a comprehensive insertAfter implementation with line matching, section boundary detection, and configuration options for handling edge cases. The system uses formatters to process content and perform actual file modifications, with capture actions determined by priority logic in captureAction.ts.

Assumptions

Assumption 1: Section boundary behavior for insertBefore

Options Considered:

• Mirror insertAfter exactly with an insertAtStart boolean flag and implement getStartOfSection() helper
• Implement only basic line-before insertion without section boundary support

Chosen Option: Mirror insertAfter exactly with an insertAtStart boolean flag and implement getStartOfSection() helper

Rationale: This provides feature parity, meets user expectations for consistent behavior between before/after options, and aligns with the existing pattern. The getStartOfSection() helper will complement getEndOfSection() by finding the line immediately after the matched heading (or the next heading if considering subsections).

Assumption 2: Action priority in getCaptureAction()

Options Considered:

• Give insertBefore higher priority than insertAfter (checked first)
• Give insertBefore equal priority to insertAfter with mutual exclusion validation
• Give insertBefore lower priority than insertAfter (insertAfter takes precedence)

Chosen Option: Give insertBefore equal priority to insertAfter with mutual exclusion validation

Rationale: This prevents configuration confusion and aligns with the existing mutual exclusion pattern between insertAfter and prepend. The UI builder will hide insertBefore fields when insertAfter is enabled and vice versa, ensuring only one line-matching option is active.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Type System and Configuration Layer

Establish the foundational types and constants for insertBefore, creating structural parity with insertAfter.

Task 1: Add insertBefore Type Definitions

Define the insertBefore configuration interface and implementation with complete feature parity to insertAfter.

• Add insertBefore property to ICaptureChoice interface in src/types/choices/ICaptureChoice.ts with structure: { enabled: boolean; before: string; insertAtStart: boolean; considerSubsections: boolean; createIfNotFound: boolean; createIfNotFoundLocation: string; }
• Implement default values in CaptureChoice class in src/types/choices/CaptureChoice.ts: insertAtStart: false, considerSubsections: false, createIfNotFoundLocation: "top", enabled: false
• Ensure the Load() method handles backward compatibility by defaulting missing insertBefore properties appropriately

Task 2: Extend CaptureAction Type

Add insertBefore as a recognized capture action type to enable routing through the action system.

• Add "insertBefore" to the CaptureAction union type in src/engine/captureAction.ts
• Update getCaptureAction() function to check for choice.insertBefore?.enabled with priority equal to insertAfter (both checked before prepend)
• Return "insertBefore" action when the insertBefore configuration is enabled

🤖 Prompt for AI agents

Phase 1: Establish type definitions and configuration for insertBefore feature
with full parity to insertAfter.

Add insertBefore property to ICaptureChoice interface with fields: enabled,
before, insertAtStart, considerSubsections, createIfNotFound,
createIfNotFoundLocation.

Implement default values in CaptureChoice class with insertAtStart: false,
considerSubsections: false, createIfNotFoundLocation: "top", enabled: false.

Ensure Load() method handles backward compatibility for missing insertBefore
properties.

Add "insertBefore" to CaptureAction union type.

Update getCaptureAction() to check choice.insertBefore?.enabled with equal
priority to insertAfter (both before prepend).

Return "insertBefore" action when insertBefore is enabled.

Phase 2: Core Insertion Logic

Implement the line matching algorithm, section boundary detection, and content insertion mechanics for insertBefore.

Task 1: Create Line Matching Function

Build the three-tier matching algorithm that finds target lines for insertBefore placement.

• Add findInsertBeforeIndex() method in src/formatters/captureChoiceFormatter.ts following the same three-tier pattern as findInsertAfterIndex(): exact match → prefix match → substring match
• Return the line index immediately before the matched line (matched index - 1, with 0 as minimum)
• Handle edge cases: empty files return -1, match on first line returns 0

Task 2: Implement Section Boundary Helper

Create section start detection to support the insertAtStart configuration option.

• Add getStartOfSection() helper function in src/formatters/helpers/getStartOfSection.ts to complement getEndOfSection()
• Implement logic that finds the line immediately after the matched heading (heading line + 1)
• When shouldConsiderSubsections is true, find the start after all nested subsections of prior heading; when false, place immediately after the target heading line
• Handle edge cases: first heading in file, headings at document start, consecutive headings with no content between

Task 3: Create insertBefore Handler

Build the orchestration logic that coordinates matching, section detection, and insertion for insertBefore actions.

• Add insertBeforeHandler() method in src/formatters/captureChoiceFormatter.ts mirroring the structure of insertAfterHandler()
• Format the target location string using formatLocationString() to resolve template tokens like {{title}} and {{linkcurrent}}
• Call findInsertBeforeIndex() to locate the target line
• When target not found and createIfNotFound is true, delegate to createInsertBeforeIfNotFound() helper (create this helper similar to the existing createInsertAfterIfNotFound())
• If insertAtStart is enabled, call getStartOfSection() to adjust insertion position to section start
• Perform insertion using insertTextBeforePositionInBody() (create this method to complement insertTextAfterPositionInBody())
• Return success with formatted heading name for status notice

Task 4: Add insertBefore Case to Engine Execution

Integrate insertBefore handling into the capture choice execution flow.

• Add case for "insertBefore" action in CaptureChoiceEngine.run() method in src/engine/CaptureChoiceEngine.ts
• Delegate to formatter.insertBeforeHandler() when insertBefore action is detected
• Use the same success notice pattern: Captured to ${fileName} before '${heading}'
• Reuse existing error handling for file operations and matching failures

🤖 Prompt for AI agents

Phase 2: Implement core line matching, section boundary detection, and insertion
mechanics for insertBefore.

Create findInsertBeforeIndex() in captureChoiceFormatter.ts using three-tier
matching (exact → prefix → substring). Return matched index - 1 (minimum 0).
Handle edge cases: empty files return -1, first line match returns 0.

Create getStartOfSection() helper in src/formatters/helpers/getStartOfSection.ts
to find line after matched heading. Support considerSubsections flag for nested
heading handling. Handle edge cases: first heading, document start, consecutive
headings.

Create insertBeforeHandler() in captureChoiceFormatter.ts mirroring
insertAfterHandler() structure. Format location string with
formatLocationString(), call findInsertBeforeIndex(), handle createIfNotFound
with createInsertBeforeIfNotFound() helper, adjust position with
getStartOfSection() when insertAtStart enabled, perform insertion with
insertTextBeforePositionInBody(), return success with heading name.

Add "insertBefore" case to CaptureChoiceEngine.run(). Delegate to
formatter.insertBeforeHandler(). Use success notice pattern: "Captured to
${fileName} before '${heading}'". Reuse existing error handling.

Phase 3: UI Configuration Layer

Expose insertBefore configuration options in the capture choice builder interface.

Task 1: Add Write Position Dropdown Option

Extend the write-position dropdown to include the "Before line..." option.

• Add dropdown.addOption("before", "Before line…"); to the addWritePositionSetting() method in src/gui/ChoiceBuilder/captureChoiceBuilder.ts
• Update the dropdown value detection logic (line ~325) to check this.choice.insertBefore?.enabled and set value to "before" when true
• Update the onChange handler to set this.choice.insertBefore.enabled = true when "before" is selected (and disable other mutually exclusive options)

Task 2: Create insertBefore Configuration Fields

Build the UI elements for configuring insertBefore-specific options when the "Before line..." option is selected.

• Create addInsertBeforeFields() method in captureChoiceBuilder.ts following the pattern of addInsertAfterFields() (lines 409-528)
• Add validated text input for the before target string with format syntax support and live preview using displayFormatter.format()
• Add toggle for "Insert at start of section" bound to this.choice.insertBefore.insertAtStart
• Add toggle for "Consider subsections" bound to this.choice.insertBefore.considerSubsections
• Add combined toggle and dropdown for "Create line if not found" with location options (top/bottom/cursor) bound to createIfNotFound and createIfNotFoundLocation

Task 3: Implement Mutual Exclusion Logic

Ensure insertBefore and insertAfter cannot both be enabled simultaneously.

• In the "before" option's onChange handler, disable insertAfter: this.choice.insertAfter.enabled = false
• In the "after" option's onChange handler, disable insertBefore: this.choice.insertBefore.enabled = false
• Update the field visibility logic to show insertBefore fields only when insertBefore is enabled and hide them when insertAfter or other exclusive options are active

🤖 Prompt for AI agents

Phase 3: Build UI configuration interface for insertBefore in the capture choice
builder.

Add "before" option to write-position dropdown in addWritePositionSetting().
Update dropdown value detection to check this.choice.insertBefore?.enabled and
set value to "before". In onChange handler, set this.choice.insertBefore.enabled
= true when "before" selected and disable mutually exclusive options.

Create addInsertBeforeFields() method following addInsertAfterFields() pattern.
Add validated text input for before target string with format syntax support and
live preview using displayFormatter.format(). Add toggle for "Insert at start of
section" bound to insertAtStart. Add toggle for "Consider subsections" bound to
considerSubsections. Add combined toggle and dropdown for "Create line if not
found" with location options bound to createIfNotFound and
createIfNotFoundLocation.

Implement mutual exclusion: in "before" onChange, set insertAfter.enabled =
false; in "after" onChange, set insertBefore.enabled = false. Update field
visibility to show insertBefore fields only when insertBefore is enabled.

Phase 4: Testing and Validation

Ensure insertBefore works correctly across all configuration scenarios and edge cases.

Task 1: Create Unit Tests for insertBefore Logic

Write comprehensive tests for the core insertion mechanics using the insertAfter test patterns as a reference.

• Create src/formatters/capture-insert-before-linkcurrent.test.ts test file mirroring the structure of capture-insert-after-linkcurrent.test.ts
• Test token resolution for {{linkcurrent}} and {{title}} in the before target string
• Test three-tier matching algorithm: exact match, prefix match, substring match scenarios
• Test insertAtStart functionality with section boundary detection
• Test considerSubsections flag behavior for nested heading structures
• Test createIfNotFound fallback with all location options (top/bottom/cursor)
• Test edge cases: empty files, first line matches, consecutive headings, files without target line

Task 2: Add Action Priority Tests

Validate that insertBefore is properly detected and prioritized in the action selection logic.

• Add test cases to src/engine/captureAction.test.ts for insertBefore action detection
• Test mutual exclusion: when both insertBefore and insertAfter are enabled, verify expected behavior (UI should prevent this, but test engine handling)
• Test priority order: insertBefore/insertAfter → prepend → default append
• Verify that enabling insertBefore returns "insertBefore" from getCaptureAction()

Task 3: Validate UI Configuration Flow

Test that the UI properly enables, disables, and saves insertBefore configuration.

• Manually verify dropdown shows "Before line..." option
• Verify selecting "Before line..." shows all insertBefore configuration fields
• Test that switching between "Before line..." and "After line..." properly clears/disables the opposite configuration
• Confirm all insertBefore settings persist correctly when saving and reopening the choice builder
• Validate input field validation and preview formatting for the before target string

🤖 Prompt for AI agents

Phase 4: Create comprehensive tests for insertBefore functionality across all
layers.

Create capture-insert-before-linkcurrent.test.ts mirroring
capture-insert-after-linkcurrent.test.ts structure. Test token resolution for
{{linkcurrent}} and {{title}}. Test three-tier matching (exact, prefix,
substring). Test insertAtStart with section boundary detection. Test
considerSubsections for nested headings. Test createIfNotFound with all location
options. Test edge cases: empty files, first line matches, consecutive headings,
missing target line.

Add insertBefore action detection tests to captureAction.test.ts. Test mutual
exclusion between insertBefore and insertAfter. Test priority order:
insertBefore/insertAfter → prepend → append. Verify getCaptureAction() returns
"insertBefore" when enabled.

Manually validate UI configuration flow: dropdown shows "Before line..." option,
selecting it shows all configuration fields, switching between before/after
clears opposite configuration, settings persist after save/reopen, input
validation and preview formatting work correctly.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Phase 1: Establish type definitions and configuration for insertBefore feature
with full parity to insertAfter.

Add insertBefore property to ICaptureChoice interface with fields: enabled,
before, insertAtStart, considerSubsections, createIfNotFound,
createIfNotFoundLocation.

Implement default values in CaptureChoice class with insertAtStart: false,
considerSubsections: false, createIfNotFoundLocation: "top", enabled: false.

Ensure Load() method handles backward compatibility for missing insertBefore
properties.

Add "insertBefore" to CaptureAction union type.

Update getCaptureAction() to check choice.insertBefore?.enabled with equal
priority to insertAfter (both before prepend).

Return "insertBefore" action when insertBefore is enabled.
===============================================================================

Task: 2

Phase 2: Implement core line matching, section boundary detection, and insertion
mechanics for insertBefore.

Create findInsertBeforeIndex() in captureChoiceFormatter.ts using three-tier
matching (exact → prefix → substring). Return matched index - 1 (minimum 0).
Handle edge cases: empty files return -1, first line match returns 0.

Create getStartOfSection() helper in src/formatters/helpers/getStartOfSection.ts
to find line after matched heading. Support considerSubsections flag for nested
heading handling. Handle edge cases: first heading, document start, consecutive
headings.

Create insertBeforeHandler() in captureChoiceFormatter.ts mirroring
insertAfterHandler() structure. Format location string with
formatLocationString(), call findInsertBeforeIndex(), handle createIfNotFound
with createInsertBeforeIfNotFound() helper, adjust position with
getStartOfSection() when insertAtStart enabled, perform insertion with
insertTextBeforePositionInBody(), return success with heading name.

Add "insertBefore" case to CaptureChoiceEngine.run(). Delegate to
formatter.insertBeforeHandler(). Use success notice pattern: "Captured to
${fileName} before '${heading}'". Reuse existing error handling.
===============================================================================

Task: 3

Phase 3: Build UI configuration interface for insertBefore in the capture choice
builder.

Add "before" option to write-position dropdown in addWritePositionSetting().
Update dropdown value detection to check this.choice.insertBefore?.enabled and
set value to "before". In onChange handler, set this.choice.insertBefore.enabled
= true when "before" selected and disable mutually exclusive options.

Create addInsertBeforeFields() method following addInsertAfterFields() pattern.
Add validated text input for before target string with format syntax support and
live preview using displayFormatter.format(). Add toggle for "Insert at start of
section" bound to insertAtStart. Add toggle for "Consider subsections" bound to
considerSubsections. Add combined toggle and dropdown for "Create line if not
found" with location options bound to createIfNotFound and
createIfNotFoundLocation.

Implement mutual exclusion: in "before" onChange, set insertAfter.enabled =
false; in "after" onChange, set insertBefore.enabled = false. Update field
visibility to show insertBefore fields only when insertBefore is enabled.
===============================================================================

Task: 4

Phase 4: Create comprehensive tests for insertBefore functionality across all
layers.

Create capture-insert-before-linkcurrent.test.ts mirroring
capture-insert-after-linkcurrent.test.ts structure. Test token resolution for
{{linkcurrent}} and {{title}}. Test three-tier matching (exact, prefix,
substring). Test insertAtStart with section boundary detection. Test
considerSubsections for nested headings. Test createIfNotFound with all location
options. Test edge cases: empty files, first line matches, consecutive headings,
missing target line.

Add insertBefore action detection tests to captureAction.test.ts. Test mutual
exclusion between insertBefore and insertAfter. Test priority order:
insertBefore/insertAfter → prepend → append. Verify getCaptureAction() returns
"insertBefore" when enabled.

Manually validate UI configuration flow: dropdown shows "Before line..." option,
selecting it shows all configuration fields, switching between before/after
clears opposite configuration, settings persist after save/reopen, input
validation and preview formatting work correctly.

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!