-
-
Notifications
You must be signed in to change notification settings - Fork 158
/
Copy pathorgmode.txt
3126 lines (2078 loc) · 100 KB
/
orgmode.txt
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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*orgmode.txt* Orgmode clone written in Lua for Neovim
==============================================================================
Table of Contents *orgmode-table-of-contents*
1. Configuration |orgmode-configuration|
- Global settings |orgmode-configuration-global-settings|
- Agenda settings |orgmode-configuration-agenda-settings|
- Calendar settings |orgmode-configuration-calendar-settings|
- Tags settings |orgmode-configuration-tags-settings|
- Mappings |orgmode-configuration-mappings|
- Features |orgmode-configuration-features|
- User interface |orgmode-configuration-user-interface|
2. Troubleshooting |orgmode-troubleshooting|
- Indentation is not working|orgmode-troubleshooting-indentation-is-not-working|
- I get treesitter/query.lua errors when opening agenda/capture prompt or org files|orgmode-troubleshooting-i-get-treesitter/query.lua-errors-when-opening-agenda/capture-prompt-or-org-files|
- I get .../orgmode/parser/org.so is not a valid Win32 application on Windows|orgmode-troubleshooting-i-get-.../orgmode/parser/org.so-is-not-a-valid-win32-application-on-windows|
- Dates are not in English|orgmode-troubleshooting-dates-are-not-in-english|
- Chinese characters are not displayed correctly in agenda|orgmode-troubleshooting-chinese-characters-are-not-displayed-correctly-in-agenda|
- Links are not concealed |orgmode-troubleshooting-links-are-not-concealed|
- Jumping to file path is not working for paths with forward slash|orgmode-troubleshooting-jumping-to-file-path-is-not-working-for-paths-with-forward-slash|
==============================================================================
1. Configuration *orgmode-configuration*
This page contains information about all configuration that can be provided to
the plugin.
- |orgmode-global-settings|
- |orgmode-agenda-settings|
- |orgmode-calendar-settings|
- |orgmode-tags-settings|
- |orgmode-mappings|
- |orgmode-features|
- |orgmode-user-interface|
GLOBAL SETTINGS *orgmode-configuration-global-settings*
org_agenda_files *orgmode-org_agenda_files*
- Type: `string | string[]`
- Default: `''`
Single or multiple paths from where the org files are being read.
Examples:
- `~/org/*`
- `{'~/Dropbox/org/**/*', '~/orgfiles/*'}`
org_default_notes_file *orgmode-org_default_notes_file*
- Type: `string`
- Default: `''`
Path to a file that will be used as a default target file when refiling.
Example: `~/orgfiles/refile.org`
org_todo_keywords *orgmode-org_todo_keywords*
- Type: `string[]`
- Default: `{'TODO', '|', 'DONE'}`
List of unfinished (_"TODO"_) and finished (_"DONE"_) keywords. `|` is used as
a separator between the two groups.
if `|` is omitted, only the last entry in array is considered a _"DONE"_ state.
To use Fast access to TODO States
<https://orgmode.org/manual/Fast-access-to-TODO-states.html#Fast-access-to-TODO-states>,
set a fast access key to at least one of the entries.
For entries where a fast access key is not set, the first character of the
keyword is used as the fast access key.
Examples (Without fast access):
- `{'TODO', 'NEXT', '|', 'DONE'}`
- `{'TODO', 'WAITING', '|', 'DONE', 'DELEGATED'}`
Examples (With fast access):
- `{'TODO(t)', 'NEXT(n)', '|', 'DONE(d)'}`
- `{'TODO(t)', 'NEXT', '|', 'DONE'}` - Same as above. Fast key is derived from first char.
NOTE: Make sure fast access keys do not overlap. If that happens, first entry
in list gets it.
org_todo_repeat_to_state *orgmode-org_todo_repeat_to_state*
- Type: `string | nil`
- Default: `nil`
Set an entry from |orgmode-org_todo_keywords| to use as the "starting" state
for repeatable todos.
If provided value does not exist in |orgmode-org_todo_keywords|, first entry
from that list is used.
win_split_mode *orgmode-win_split_mode*
- Type: `string | function | [string, number]`
- Default: `'horizontal'`
This option determines how to open agenda and capture window.
Available `string` values:
- `horizontal` - Always split horizontally
- `vertical` - Always split vertically
- `auto` - Determine between horizontal and vertical split depending on the current window size
- `float` - Open in float window that has width of 70% of the screen centered
- `{'float', 0.9}` - Open in float window and provide custom scale (in this case it's 90% of screen size), must be value between `0` and `1`
If none of the options above suit your needs, there are 2 other ways to
customize this:
1. Provide a custom command string (see `:help <mods>`). Few examples:
- Always open in tab: `tabnew`
- Always open vertically: `vsplit`
- Always open horizontally with specific height of 20 lines: `20split`
2. Custom function
>lua
win_split_mode = function(name)
-- Make sure it's not a scratch buffer by passing false as 2nd argument
local bufnr = vim.api.nvim_create_buf(false, false)
--- Setting buffer name is required
vim.api.nvim_buf_set_name(bufnr, name)
local fill = 0.8
local width = math.floor((vim.o.columns * fill))
local height = math.floor((vim.o.lines * fill))
local row = math.floor((((vim.o.lines - height) / 2) - 1))
local col = math.floor(((vim.o.columns - width) / 2))
vim.api.nvim_open_win(bufnr, true, {
relative = "editor",
width = width,
height = height,
row = row,
col = col,
style = "minimal",
border = "rounded"
})
end
<
win_border *orgmode-win_border*
- Type: `string | string[]`
- Default: `'single'`
Border style for floating windows. Available options:
- `none` - No border (default)
- `single` - A single line box
- `double` - A double line box
- `rounded` - Like "single", but with rounded corners ("╭" etc.)
- `solid` - Adds padding by a single whitespace cell
- `shadow` - A drop shadow effect by blending with the background
- `{'╔', '═' ,'╗', '║', '╝', '═', '╚', '║' }` - Specify border characters in a clock-wise fashion
- `{'/', '-', '\\', '|' }` - If less than eight chars the chars will start repeating
See `:help nvim_open_win()`
Applies to:
- always - calendar pop-up, help pop-up, notification pop-up
- `win_split_mode` is set to `float` - agenda window , capture window
org_startup_folded *orgmode-org_startup_folded*
- Type: `string`
- Default: `'overview'`
How many headings and other foldable items should be shown when an org file is
opened. Available options:
- `overview` - Only show top level elements (default)
- `content` - Only show the first two levels
- `showeverything` - Show all elements
- `inherit` - Use the fold level set in Neovim's global `foldlevel` option
org_todo_keyword_faces *orgmode-org_todo_keyword_faces*
- Type: `table<string, string>`
- Default: `{}`
Custom colors for todo keywords. Available options:
- foreground - `:foreground hex/colorname`. Examples: `:foreground #FF0000`, `:foreground blue`
- background - `:background hex/colorname`. Examples: `:background #FF0000`, `:background blue`
- weight - `:weight bold`
- underline - `:underline on`
- italic - `:slant italic`
Full configuration example with additional todo keywords and their colors:
>lua
require('orgmode').setup({
org_todo_keywords = {'TODO', 'WAITING', '|', 'DONE', 'DELEGATED'},
org_todo_keyword_faces = {
WAITING = ':foreground blue :weight bold',
DELEGATED = ':background #FFFFFF :slant italic :underline on',
TODO = ':background #000000 :foreground red', -- overrides builtin color for `TODO` keyword
}
})
<
org_archive_location *orgmode-org_archive_location*
- Type: `string`
- Default: `'%s_archive::'`
Destination file for archiving. `%s` indicates the current file. `::` is used
as a separator for archiving to headline which is currently not supported. This
means that if you do a refile from a file `~/my-orgs/todos.org`, your task will
be archived in `~/my-orgs/todos.org_archive`.
Example value: `'~/my-orgs/default-archive-file.org::'`
📝 NOTE: This value can be overridden per file basis with a org special
keyword `#+ARCHIVE`.
org_hide_leading_stars *orgmode-org_hide_leading_stars*
- Type: `boolean`
- Default: `false`
Hide leading stars for headings. Example:
Disabled (default):
>org
* TODO First item
** TODO Second Item
*** TODO Third item
<
Enabled:
>org
* TODO First item
* TODO Second Item
* TODO Third item
<
📝 NOTE: Stars are hidden by applying highlight group that masks them with
color that's same as background color. If this highlight group does not suit
you, you can apply different highlight group to it:
>lua
vim.cmd[[autocmd ColorScheme * hi link @org.leading.stars MyCustomHlGroup]]
<
To set specific characters instead of using asterisk, check org-bullets.nvim
<./plugins.org::#org-bulletsnvim> plugin plugin.
org_hide_emphasis_markers *orgmode-org_hide_emphasis_markers*
- Type: `boolean`
- Default: `false`
Conceal bold/italic/underline/code/verbatim markers.
Ensure your |conceallevel| is set properly in order for this to function.
org_ellipsis *orgmode-org_ellipsis*
- Type: `string`
- Default: `'...'`
Marker used to indicate a folded headline.
org_log_done *orgmode-org_log_done*
- Type: `string|false`
- Default: `time`
Possible values:
- `time` - adds `CLOSED` date when marking headline as done
- `note` - adds `CLOSED` date as above, and prompts for closing note via capture window.
Confirm note with `org_note_finalize` (Default `<C-c>`), or ignore providing note via `org_note_kill` (Default `<Leader>ok`)
- `false` - Disable any logging
org_log_repeat *orgmode-org_log_repeat*
- Type: `string|false`
- Default: `time`
Possible values:
- `time` - adds `LAST_REPEAT` date to properties when marking headline with a repeater date as done
- `note` - adds `LAST_REPEAT` date as above, and prompts for closing note via capture window.
Confirm note with `org_note_finalize` (Default `<C-c>`), or ignore providing note via `org_note_kill` (Default `<Leader>ok`)
- `false` - Disable logging the `LAST_REPEAT` date
org_log_into_drawer *orgmode-org_log_into_drawer*
- Type: `string|nil`
- Default: `nil`
Log TODO state changes into a drawer with the given name. The recommended value
is `LOGBOOK`. If `nil`, log into the section body.
org_highlight_latex_and_related *orgmode-org_highlight_latex_and_related*
- Type: `string|nil`
- Default: `nil`
📝 NOTE: This option is experimental
Possible values:
- `native` - Includes whole latex syntax file into the org syntax. It can potentially cause some highlighting issues and slowness.
- `entities` - Highlight latex only in these situations (see Orgmode latex fragments <https://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments>):
- between `\begin` and `\end` delimiters
- between `$` and `$` delimiters - example: `$a^2=b$`
- between `$$` and `$$` delimiters - example: `$$ a=+\sqrt{2} $$`
- between `\[` and `\]` delimiters - example: `\[ a=-\sqrt{2} \]`
- between `\(` and `\)` delimiters - example: `\( b=2 \)`
org_startup_indented *orgmode-org_startup_indented*
- Type: `boolean`
- Default: `false`
Possible values:
- `true` - Uses _Virtual_ indents to align content visually. The indents are only visual, they are not saved to the file.
- `false` - Do not add any _Virtual_ indentation.
You can toggle Virtual indents on the fly by executing command `:Org
indent_mode` when in a org buffer. This additionally sets the buffer variable
`vim.b.org_indent_mode` to `true` or `false`, depending on the current state.
Value of this buffer variable is then used to determine behavior of few options
below.
org_adapt_indentation *orgmode-org_adapt_indentation*
- Type: `boolean`
- Default: `true`
Possible values:
- `true` - Use _hard_ indents for content under headlines. Files will save with indents relative to headlines.
- `false` - Do not add any _hard_ indents. Files will save without indentation relative to headlines.
org_indent_mode_turns_off_org_adapt_indentation*orgmode-org_indent_mode_turns_off_org_adapt_indentation*
- Type: `boolean`
- Default: `true`
Possible values:
- `true` - Disable |orgmode-org_adapt_indentation| by default when |orgmode-org_startup_indented| is enabled.
- `false` - Do not disable |orgmode-org_adapt_indentation| by default when |orgmode-org_startup_indented| is enabled.
org_indent_mode_turns_on_hiding_stars*orgmode-org_indent_mode_turns_on_hiding_stars*
- Type: `boolean`
- Default: `true`
Possible values:
- `true` - Enable |orgmode-org_hide_leading_stars| by default when |orgmode-org_indent_mode| is enabled for buffer (`vim.b.org_indent_mode = true`).
- `false` - Do not modify the value in |orgmode-org_hide_leading_stars| by default when |orgmode-org_indent_mode| is enabled for buffer (`vim.b.org_indent_mode = true`).
org_src_window_setup *orgmode-org_src_window_setup*
- Type: `string | function`
- Default: `'top 16new'`
If the value is a string, it will be run directly as input to |vim.cmd|,
otherwise if the value is a function it will be called. Both values have the
responsibility of opening a buffer (within a window) to show the special edit
buffer. The content of the buffer will be set automatically, so this option
only needs to handle opening an empty buffer.
org_edit_src_content_indentation *orgmode-org_edit_src_content_indentation*
- Type: `number`
- Default: `0`
The indent value for content within `SRC` block types beyond the existing
indent of the block itself. Only applied when exiting from an
`org_edit_special` action on a `SRC` block.
org_custom_exports *orgmode-org_custom_exports*
- Type: `table`
- Default: `{}`
Add custom export options to the export prompt. Structure:
>example
[shortcut:string] = {
[label:string] = 'Label in export prompt',
[action:function] = function(exporter)
return exporter(command:table, target:string, on_success?:function, on_error?:function)
end
}
<
Breakdown:
- `shortcut` - single char that will be used to select the export. Make
sure it doesn't conflict with existing options
- `action` - function that provides `exporter` function for generating
the exports
- `exporter` - function that calls the command provided via `job`
- `command` - table (array like) that contains command how to generate
the export
- `target` - target file name that will be generated
- `on_success?` - function that is triggered when export succeeds
(command exit status is 0). Provides table parameter with command
output. Optional, defaults to prompt to open target file.
- `on_error?` - function that is triggered when export fails (command
exit status is not 0). Provides table parameter with command output.
Optional, defaults to printing output as error.
For example, lets add option to export to `rtf` format via `pandoc`:
>lua
require('orgmode').setup({
org_custom_exports = {
f = {
label = 'Export to RTF format',
action = function(exporter)
local current_file = vim.api.nvim_buf_get_name(0)
local target = vim.fn.fnamemodify(current_file, ':p:r')..'.rtf'
local command = {'pandoc', current_file, '-o', target}
local on_success = function(output)
print('Success!')
vim.api.nvim_echo({{ table.concat(output, '\n') }}, true, {})
end
local on_error = function(err)
print('Error!')
vim.api.nvim_echo({{ table.concat(err, '\n'), 'ErrorMsg' }}, true, {})
end
return exporter(command , target, on_success, on_error)
end
}
}
})
<
org_time_stamp_rounding_minutes *orgmode-org_time_stamp_rounding_minutes*
- Type: `number`
- Default: `5`
Number of minutes to increase/decrease when using
|orgmode-org_timestamp_up|/|orgmode-org_timestamp_down|
org_cycle_separator_lines *orgmode-org_cycle_separator_lines*
- Type `number`
- Default: `2`
Minimum number of empty lines needed at the end of the headline to show a
single empty line when headline is folded.
For example, given this structure:
>org
* One empty space headline
Content
* Two empty space headline
Content
* Three empty space headline
Content
* Last headline
Content
<
When folded, it will appear like this:
>org
* One empty space headline ...
* Two empty space headline ...
* Three empty space headline ...
* Last headline ...
<
When value is `0`, all empty lines are folded together with headline.
Cannot be negative.
org_blank_before_new_entry *orgmode-org_blank_before_new_entry*
- Type: `table<string, boolean>`
- Default: `{ heading = true, plain_list_item = false }`
Determine if blank line should be prepended when:
- Adding heading via `org_meta_return` and `org_insert_*` mappings
- Adding a list item via `org_meta_return`
org_id_uuid_program *orgmode-org_id_uuid_program*
- Type: `string`
- Default: `uuidgen`
External program used to generate uuid's for id module
org_id_ts_format *orgmode-org_id_ts_format*
- Type: `string`
- Default: `%Y%m%d%H%M%S`
Format of the id generated when |orgmode-org_id_method| is set to `ts`.
org_id_method *orgmode-org_id_method*
- Type: `'uuid' | 'ts' | 'org'`
- Default: `uuid`
What method to use to generate ids via org id module.
- `uuid` - Use |orgmode-org_id_uuid_program| to generate
the id
- `ts` - Generate id from current timestamp using format |orgmode-org_id_ts_format|
- `org` - Generate a random 12 digit number and prepend |orgmode-org_id_prefix|
org_id_prefix *orgmode-org_id_prefix*
- Type: `string | nil`
- Default: `nil`
Prefix added to the generated id when |orgmode-org_id_method| is set to `org`.
org_id_link_to_org_use_id *orgmode-org_id_link_to_org_use_id*
- Type: `boolean`
- Default: `false`
If `true`, generate ID with the Org ID module and append it to the headline as
property. More info on |orgmode-org_store_link|
org_use_property_inheritance *orgmode-org_use_property_inheritance*
- Type: `boolean | string | string[]`
- Default: `false`
Determine whether properties of one headline are inherited by sub-headlines.
- `false` - properties only pertain to the file or headline that defines them
- `true` - properties of a headlines also pertain to all its sub-headlines
- `string[]` - only the properties named in the given list are inherited
- `string` - only properties matching the given regex are inherited
Note that for a select few properties, the inheritance behavior is hard-coded
withing their special applications. See Property Inheritance
<https://orgmode.org/manual/Property-Inheritance.html> for details.
org_babel_default_header_args *orgmode-org_babel_default_header_args*
- Type: `table<string, string>`
- Default: `{ [':tangle'] = 'no', [':noweb'] = no }`
Default header args for extracting source code. See
|orgmode-extract-source-code-(tangle)| for more details.
calendar_week_start_day *orgmode-calendar_week_start_day*
- Type: `number`
- Default: `1`
Available options:
- `0` - start week on Sunday
- `1` - start week on Monday
Determine on which day the week will start in calendar modal
(ex:|orgmode-changing-the-date-under-cursor|)
emacs_config *orgmode-emacs_config*
- Type: `table`
- Default: `{ executable_path = 'emacs', config_path=nil }`
Set configuration for your emacs. This is useful for having the emacs export
properly pickup your emacs config and plugins. If `config_path` is not
provided, exporter tries to find a configuration file from these locations:
1. `~/.config/emacs/init.el`
2. `~/.emacs.d/init.el`
3. `~/.emacs.el`
If there is no configuration found, it will still process the export.
If it finds a configuration and export attempt fails because of the
configuration issue, there will be a prompt to attempt the same export without
the configuration file.
AGENDA SETTINGS *orgmode-configuration-agenda-settings*
org_deadline_warning_days *orgmode-org_deadline_warning_days*
- Type: `number`
- Default: `14`
Number of days during which deadline becomes visible in today's agenda.
Example: If Today is `2021-06-10`, and we have these tasks:
- `Task 1` has a deadline date `2021-06-15`
- `Task 2` has a deadline date `2021-06-30`
- `Task 1` is visible in today's agenda
- `Task 2` is not visible in today's agenda until `2021-06-16`
org_agenda_span *orgmode-org_agenda_span*
- Type: `string|number`
- Default: `'week'`
_possible string values_: `day`, `week`, `month`, `year` Default time span
shown when agenda is opened.
org_agenda_start_on_weekday *orgmode-org_agenda_start_on_weekday*
- Type: `number`
- Default: `1`
From which day in week (ISO weekday, 1 is Monday) to show the agenda. Applies
only to `week` and number span. If set to `false`, starts from today
org_agenda_start_day *orgmode-org_agenda_start_day*
- Type: `string`
- Default: `nil`
_example values_: `+2d`, `-1d` offset to apply to the agenda start date.
Example: If `org_agenda_start_on_weekday` is `false`, and
`org_agenda_start_day` is `-2d`, agenda will always show current week from
today - 2 days
org_agenda_custom_commands *orgmode-org_agenda_custom_commands*
- Type: `table<string, OrgAgendaCustomCommand>`
- Default: `{}`
Define custom agenda views that are available through the |orgmode-org_agenda|
mapping. It is possible to combine multiple agenda types into single view.
Available options for each agenda type are explained down below the example:
>lua
require('orgmode').setup({
org_agenda_files = {'~/org/**/*'},
org_agenda_custom_commands = {
-- "c" is the shortcut that will be used in the prompt
c = {
description = 'Combined view', -- Description shown in the prompt for the shortcut
types = {
{
type = 'tags_todo', -- Type can be agenda | tags | tags_todo
match = '+PRIORITY="A"', --Same as providing a "Match:" for tags view <leader>oa + m, See: https://orgmode.org/manual/Matching-tags-and-properties.html
org_agenda_overriding_header = 'High priority todos',
org_agenda_todo_ignore_deadlines = 'far', -- Ignore all deadlines that are too far in future (over org_deadline_warning_days). Possible values: all | near | far | past | future
},
{
type = 'agenda',
org_agenda_overriding_header = 'My daily agenda',
org_agenda_span = 'day' -- can be any value as org_agenda_span
},
{
type = 'tags',
match = 'WORK', --Same as providing a "Match:" for tags view <leader>oa + m, See: https://orgmode.org/manual/Matching-tags-and-properties.html
org_agenda_overriding_header = 'My work todos',
org_agenda_todo_ignore_scheduled = 'all', -- Ignore all headlines that are scheduled. Possible values: past | future | all
},
{
type = 'agenda',
org_agenda_overriding_header = 'Whole week overview',
org_agenda_span = 'week', -- 'week' is default, so it's not necessary here, just an example
org_agenda_start_on_weekday = 1 -- Start on Monday
org_agenda_remove_tags = true -- Do not show tags only for this view
},
}
},
p = {
description = 'Personal agenda',
types = {
{
type = 'tags_todo',
org_agenda_overriding_header = 'My personal todos',
org_agenda_category_filter_preset = 'todos', -- Show only headlines from `todos` category. Same value providad as when pressing `/` in the Agenda view
org_agenda_sorting_strategy = {'todo-state-up', 'priority-down'} -- See all options available on org_agenda_sorting_strategy
},
{
type = 'agenda',
org_agenda_overriding_header = 'Personal projects agenda',
org_agenda_files = {'~/my-projects/**/*'}, -- Can define files outside of the default org_agenda_files
},
{
type = 'tags',
org_agenda_overriding_header = 'Personal projects notes',
org_agenda_files = {'~/my-projects/**/*'},
org_agenda_tag_filter_preset = 'NOTES-REFACTOR' -- Show only headlines with NOTES tag that does not have a REFACTOR tag. Same value providad as when pressing `/` in the Agenda view
},
}
}
}
})
<
These arguments are shared between all of the agenda types:
- `org_agenda_overriding_header` `(string)` - Override the header of the agenda view
- `org_agenda_files` `(string | string[])` - Set custom files to be loaded into this view. In same format as |orgmode-org_agenda_files|
- `org_agenda_tag_filter_preset` `string` - Custom tags filter for the view. Same format as |orgmode-org_agenda_files|, but applies only for tags.
- `org_agenda_category_filter_preset` `string` - Custom category filter for the view. Same format as |orgmode-org_agenda_files|, but applies only for categories.
- `org_agenda_sorting_strategy` `string[]` - List of sorting functions. See |orgmode-org_agenda_sorting_strategy|
- `org_agenda_remove_tags` `boolean` - Remove tags from the view. Default: `false`
`agenda` type arguments:
- `org_agenda_span` `string|number` - Set custom span for the view. In same format as |orgmode-org_agenda_span|
- `org_agenda_start_on_weekday` `number` - Set custom start day for the view. In same format as |orgmode-org_agenda_start_on_weekday|
- `org_agenda_start_day` `string` - Set custom start day offset for the view. In same format as |orgmode-org_agenda_start_day|
`tags` and `tags_todo` type arguments:
- `org_agenda_todo_ignore_scheduled` `('past' | 'future' | 'all' | nil')` - Do not show headlines that have scheduled task according to the value. Default: `nil`
- `org_agenda_todo_ignore_deadlines` `('near' | 'far' | 'all' | 'past' | 'future' | nil')` - Do not show headlines that have deadline task according to the value. Default: `nil`
- `far` - Do not show deadlines that are too far in future (over |orgmode-org_deadline_warning_days|)
- `near` - Do not show deadlines that are too near in future (under |orgmode-org_deadline_warning_days|)
org_agenda_sorting_strategy *orgmode-org_agenda_sorting_strategy*
- Type:
`table<'agenda' | 'todo' | 'tags', OrgAgendaSortingStrategy[]><`
- Default:
`{ agenda = {'time-up', 'priority-down', 'category-keep'}, todo =
{'priority-down', 'category-keep'}, tags = {'priority-down', 'category-keep'}}`
List of sorting strategies to apply to a given view. Available strategies:
- `time-up` - Sort entries by time of day. Applicable only in `agenda`
view
- `time-down` - Opposite of `time-up`
- `priority-down` - Sort by priority, from highest to lowest
- `priority-up` - Sort by priority, from lowest to highest
- `tag-up` - Sort by sorted tags string, ascending
- `tag-down` - Sort by sorted tags string, descending
- `todo-state-up` - Sort by todo keyword by position (example: 'TODO,
PROGRESS, DONE' has a sort value of 1, 2 and 3), ascending
- `todo-state-down` - Sort by todo keyword, descending
- `clocked-up` - Show clocked in headlines first
- `clocked-down` - Show clocked in headlines last
- `category-up` - Sort by category name, ascending
- `category-down` - Sort by category name, descending
- `category-keep` - Keep default category sorting, as it appears in
org-agenda-files
org_agenda_block_separator *orgmode-org_agenda_block_separator*
- Type: `string`
- Default: `-`
Separator used to separate multiple agenda views generated by
|orgmode-org_agenda_custom_commands|. To change the highlight, override
`@org.agenda.separator` hl group.
org_agenda_remove_tags *orgmode-org_agenda_remove_tags*
- Type: `boolean`
- Default: `false`
Should tags be hidden from all agenda views.
org_capture_templates *orgmode-org_capture_templates*
- Type: `table<string, table>`
- Default:
`{ t = { description = 'Task', template = '* TODO %?\n %u' } }` Templates for
capture/refile prompt. Variables:
- `%f`: Prints the file of the buffer capture was called from
- `%F`: Like `%f` but inserts the full path
- `%n`: Inserts the current `$USER`
- `%t`: Prints current date (Example: `<2021-06-10 Thu>`)
- `%^t`: Prompt for current date (Example: `<2021-06-10 Thu>`)
- `%^{Name}t`: Prompt for current date for given `Name` (visible in
calendar title) (Example: `<2021-06-10 Thu>`)
- `%T`: Prints current date and time (Example: `<2021-06-10 Thu 12:30>`)
- `%^T`: Prompt for current date and time (Example:
`<2021-06-10 Thu 12:30>`)
- `%^{Name}T`: Prompt for current date and time for given `Name`
(visible in calendar title) (Example: `<2021-06-10 Thu 12:30>`)
- `%u`: Prints current date in inactive format (Example:
`[2021-06-10 Thu]`)
- `%^u`: Prompt for current date in inactive format (Example:
`[2021-06-10 Thu]`)
- `%^{Name}u`: Prompt for current date in inactive format for given
`Name` (visible in calendar title) (Example: `[2021-06-10 Thu]`)
- `%U`: Prints current date and time in inactive format (Example:
`[2021-06-10 Thu 12:30]`)
- `%^U`: Prompt for current date and time in inactive format (Example:
`[2021-06-10 Thu 12:30]`)
- `%^{Name}U`: Prompt for current date and time in inactive format for
given `Name` (visible in calendar title) (Example:
`[2021-06-10 Thu 12:30]`)
- `%a`: File and line number from where capture was initiated (Example:
`[[file:/home/user/projects/myfile.txt +2]]`)
- `%<FORMAT>`: Insert current date/time formatted according to
lua date <https://www.lua.org/pil/22.1.html> format (Example:
`%<%Y-%m-%d %A>` produces '2021-07-02 Friday')
- `%x`: Insert content of the clipboard via the "+" register (see :help
clipboard)
- `%?`: Default cursor position when template is opened
- `%^{PROMPT|DEFAULT|COMPLETION...}`: Prompt for input, if completion is
provided an :h inputlist will be used
- `%(EXP)`: Runs the given lua code and inserts the result. NOTE: this
will internally pass the content to the lua `load()` function. So the
body inside `%()` should be the body of a function that returns a
string.
Templates have the following fields:
- `description` (`string`) — description of the template that is
displayed in the template selection menu
- `template` (`string|string[]`) — body of the template that will be
used when creating capture
- `target` (`string?`) — name of the file to which the capture content
will be added. If the target is not specified, the content will be
added to the |orgmode-org_default_notes_file| file
- `headline` (`string?`) — title of the headline after which the
capture content will be added. If no headline is specified, the
content will be appended to the end of the file
- `datetree (boolean | { time_prompt?: boolean, reversed?: boolean, tree_type: 'day' | 'month' | 'week' | 'custom' })`
Create a date tree <https://orgmode.org/manual/Template-elements.hml#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
- `{ time_prompt = true, reversed?: boolean }` open up a date picker to select a date before opening up a capture buffer
- `{ reversed: true }` add entries in reversed order (newer dates comes first)
- `{ tree_type: 'day' | 'month' | 'week' | 'custom' }` Which date tree type to use:
- `day` Create year -> month -> day structure, and refile headlines in the day
headline
- `month` Create year -> month structure, and refile headlines in the month
headline
- `week` Create year -> week number structure, and refile headlines in the week
number headline
- `custom` (**Advanced**) - Create custom datetree with own date formats. This
requires adding `tree` property in the `datetree` opts. Example with year and
month tree:
>lua
datetree = {
tree_type = 'custom',
tree = {
{
format = '%Y',
pattern = '^(%d%d%d%d)$',
order = { 1 }
},
{
format = '%Y-%m',
pattern = '^(%d%d%d%d)%-(%d%d)$',
order = { 1, 2 }
}
}
}
<
Check this line in source
<https://github.com/nvim-orgmode/orgmode/blob/master/lua/orgmode/capture/template/datetree.lua#L144>
for builtin tree types and detailed explanation how to add own tree.
- `regexp (string)` Search for specific line in the target file via regex (same as searching through file from command),
and append the content after that line. For example, if you have line `appendhere` in target file,
put this option to `^appendhere$` to add headlines after that line
- `properties` (`table?`):
- `empty_lines` (`table|number?`) if the value is a number, then empty lines are added before and after the content.
If the value is a table, then the following fields are expected:
- `before` (`integer?`) add empty lines to the beginning of the content
- `after` (`integer?`) add empty lines to the end of the content
Example:
>lua
{ T = {
description = 'Todo',
template = '* TODO %?\n %u',
target = '~/org/todo.org'
} }
<
Journal example:
>lua
{
j = {
description = 'Journal',
template = '\n*** %<%Y-%m-%d> %<%A>\n**** %U\n\n%?',
target = '~/sync/org/journal.org'
},
}
<
Journal example with dynamic target, i.e. a separate file per month:
>lua
{
J = {
description = 'Journal',
template = '\n*** %<%Y-%m-%d> %<%A>\n**** %U\n\n%?',
target = '~/sync/org/journal/%<%Y-%m>.org'
},
}
<
Nested key example:
>lua
{
e = 'Event',
er = {
description = 'recurring',
template = '** %?\n %T',
target = '~/org/calendar.org',
headline = 'recurring'
},
eo = {
description = 'one-time',
template = '** %?\n %T',
target = '~/org/calendar.org',
headline = 'one-time'
}
}
-- or
{
e = {
description = 'Event',
subtemplates = {
r = {
description = 'recurring',
template = '** %?\n %T',
target = '~/org/calendar.org',