blob: ae7e8817f385041000ffa28a82f3f184d6fe209a (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
|
# Org Refile Design
## Context
The configuration already has the core minibuffer completion stack in place:
- `lisp/ss-ui.el` enables Vertico, Orderless, and Marginalia globally.
- `lisp/ss-org.el` owns base Org configuration.
- `lisp/ss-agenda.el` already discovers `org-agenda-files` from the journal and
PARA directories.
The missing piece is Org refile configuration. The requested behavior is to
refile Org entries to any heading in the current `org-agenda-files`, using a
single, path-oriented prompt that works well with the existing Vertico-based
completion UI.
## Options Considered
### 1. Recommended: configure built-in Org refile against `org-agenda-files`
- Use Org's standard `org-refile` command and target machinery.
- Refresh `org-agenda-files` before refile so the target set stays aligned with
the existing agenda discovery rules.
- Configure path-based completion so Vertico and Orderless present the target
list cleanly.
This keeps the workflow conventional, reuses existing repository structure, and
avoids maintaining a parallel refile implementation.
### 2. Add a custom wrapper command with richer target formatting
- Build a custom candidate list for headings across agenda files.
- Pass the chosen destination back into Org's refile internals.
This could show more custom metadata, but it duplicates behavior Org already
provides and increases maintenance cost for little practical gain.
### 3. Add more completion packages just for refile
- Introduce a Vertico extension or a separate package to alter refile prompts.
This adds package surface area without first exhausting the built-in Org and
completion capabilities already present in the config.
## Chosen Design
Use option 1.
- Configure `org-refile-targets` to use `org-agenda-files` with unrestricted
heading depth.
- Enable outline-path completion so identically named headings are
distinguishable by their parent path.
- Use the direct, path-based completion flow rather than an additional outline
navigation step.
- Refresh `org-agenda-files` before refile by reusing the existing agenda file
discovery helper instead of copying the directory rules.
- Keep the change inside the existing module boundaries: Org behavior in
`lisp/ss-org.el`, with a UI tweak in `lisp/ss-ui.el` only if the current
completion categories need one.
## Verification
- Add focused ERT coverage for the refile setup helper and variable values.
- Run `emacs --batch -Q --load ./init.el` from the repository root.
## Documentation Impact
`README.md` should be updated to describe that Org refile targets any heading in
`org-agenda-files` and uses the configured minibuffer completion stack for
path-based target selection.
|
