From adfce49601ba27ff953f9c6354665fbc12a3b256 Mon Sep 17 00:00:00 2001 From: github-actions Date: Sun, 19 Jan 2025 23:13:19 +0000 Subject: [PATCH] [docgen] Update docs --- doc/orgmode.txt | 4051 ++++++++++++++++++++++++++++------------------- 1 file changed, 2409 insertions(+), 1642 deletions(-) diff --git a/doc/orgmode.txt b/doc/orgmode.txt index 12b9ced42..76bfe4e89 100644 --- a/doc/orgmode.txt +++ b/doc/orgmode.txt @@ -1,206 +1,144 @@ -orgmode.txt *orgmode* *orgmode.nvim* - -* NOTE: This file is autogenerated from DOCS.md file - -================================================================================ -CONTENTS *orgmode-contents* - -1. Table of content.....................................|orgmode-table_of_content| - 1.1. Getting started with Orgmode.......|orgmode-getting_started_with_orgmode| - 1.2. Settings...............................................|orgmode-settings| - 1.2.1. Global settings...........................|orgmode-global_settings| - 1.2.1.1. org_agenda_files...................|orgmode-org_agenda_files| - 1.2.1.2. org_default_notes_file.......|orgmode-org_default_notes_file| - 1.2.1.3. org_todo_keywords.................|orgmode-org_todo_keywords| - 1.2.1.4. org_todo_repeat_to_state...|orgmode-org_todo_repeat_to_state| - 1.2.1.5. win_split_mode.......................|orgmode-win_split_mode| - 1.2.1.6. win_border...............................|orgmode-win_border| - 1.2.1.7. org_startup_folded...............|orgmode-org_startup_folded| - 1.2.1.8. org_todo_keyword_faces.......|orgmode-org_todo_keyword_faces| - 1.2.1.9. org_archive_location...........|orgmode-org_archive_location| - 1.2.1.10. org_hide_leading_stars......|orgmode-org_hide_leading_stars| - 1.2.1.11. org_hide_emphasis_markers.|orgmode-org_hide_emphasis_markers| - 1.2.1.12. org_ellipsis..........................|orgmode-org_ellipsis| - 1.2.1.13. org_log_done..........................|orgmode-org_log_done| - 1.2.1.14. org_log_repeat......................|orgmode-org_log_repeat| - 1.2.1.15. org_log_into_drawer............|orgmode-org_log_into_drawer| - 1.2.1.16. org_highlight_latex_and_related.|orgmode-org_highlight_latex_and_related| - 1.2.1.17. org_startup_indented..........|orgmode-org_startup_indented| - 1.2.1.18. org_adapt_indentation........|orgmode-org_adapt_indentation| - 1.2.1.19. org_indent_mode_turns_off_org_adapt_indentation.|orgmode-org_indent_mode_turns_off_org_adapt_indentation| - 1.2.1.20. org_indent_mode_turns_on_hiding_stars.|orgmode-org_indent_mode_turns_on_hiding_stars| - 1.2.1.21. org_src_window_setup..........|orgmode-org_src_window_setup| - 1.2.1.22. org_edit_src_content_indentation.|orgmode-org_edit_src_content_indentation| - 1.2.1.23. org_custom_exports..............|orgmode-org_custom_exports| - 1.2.1.24. org_time_stamp_rounding_minutes.|orgmode-org_time_stamp_rounding_minutes| - 1.2.1.25. org_blank_before_new_entry.|orgmode-org_blank_before_new_entry| - 1.2.1.26. org_id_uuid_program............|orgmode-org_id_uuid_program| - 1.2.1.27. org_id_ts_format..................|orgmode-org_id_ts_format| - 1.2.1.28. org_id_method........................|orgmode-org_id_method| - 1.2.1.29. org_id_prefix........................|orgmode-org_id_prefix| - 1.2.1.30. org_id_link_to_org_use_id.|orgmode-org_id_link_to_org_use_id| - 1.2.1.31. org_babel_default_header_args.|orgmode-org_babel_default_header_args| - 1.2.1.32. calendar_week_start_day....|orgmode-calendar_week_start_day| - 1.2.1.33. emacs_config..........................|orgmode-emacs_config| - 1.2.2. Agenda settings...........................|orgmode-agenda_settings| - 1.2.2.1. org_deadline_warning_days.|orgmode-org_deadline_warning_days| - 1.2.2.2. org_agenda_span.....................|orgmode-org_agenda_span| - 1.2.2.3. org_agenda_start_on_weekday.|orgmode-org_agenda_start_on_weekday| - 1.2.2.4. org_agenda_start_day...........|orgmode-org_agenda_start_day| - 1.2.2.5. org_agenda_custom_commands.|orgmode-org_agenda_custom_commands| - 1.2.2.6. org_agenda_sorting_strategy.|orgmode-org_agenda_sorting_strategy| - 1.2.2.7. org_agenda_block_separator.|orgmode-org_agenda_block_separator| - 1.2.2.8. org_agenda_remove_tags.......|orgmode-org_agenda_remove_tags| - 1.2.2.9. org_capture_templates.........|orgmode-org_capture_templates| - 1.2.2.10. org_agenda_min_height........|orgmode-org_agenda_min_height| - 1.2.2.11. org_priority_highest..........|orgmode-org_priority_highest| - 1.2.2.12. org_priority_default..........|orgmode-org_priority_default| - 1.2.2.13. org_priority_lowest............|orgmode-org_priority_lowest| - 1.2.2.14. org_agenda_skip_scheduled_if_done.|orgmode-org_agenda_skip_scheduled_if_done| - 1.2.2.15. org_agenda_skip_deadline_if_done.|orgmode-org_agenda_skip_deadline_if_done| - 1.2.2.16. org_agenda_text_search_extra_files.|orgmode-org_agenda_text_search_extra_files| - 1.2.3. Calendar settings.......................|orgmode-calendar_settings| - 1.2.3.1. calendar.round_min_with_hours.|orgmode-calendar.round_min_with_hours| - 1.2.3.2. calendar.min_big_step.........|orgmode-calendar.min_big_step| - 1.2.3.3. calendar.min_small_step.....|orgmode-calendar.min_small_step| - 1.2.4. Tags settings...............................|orgmode-tags_settings| - 1.2.4.1. org_tags_column.....................|orgmode-org_tags_column| - 1.2.4.2. org_use_tag_inheritance.....|orgmode-org_use_tag_inheritance| - 1.2.4.3. org_tags_exclude_from_inheritance.|orgmode-org_tags_exclude_from_inheritance| - 1.3. Mappings...............................................|orgmode-mappings| - 1.4. Press key for an agenda command.|orgmode-press_key_for_an_agenda_command| - 1.5. Changelog.............................................|orgmode-changelog| - 1.5.1. 25 February 2024.....................|orgmode-25_february_2024| - 1.5.2. 21 January 2024.......................|orgmode-21_january_2024| - 1.5.3. 24 October 2021.......................|orgmode-24_october_2021| - 1.5.4. 10 October 2021.......................|orgmode-10_october_2021| - -================================================================================ -TABLE OF CONTENT *orgmode-table_of_content* - -1. Getting started with Orgmode (#getting-started-with-orgmode) -2. Settings (#settings) - 1. Global settings (#global-settings) - 2. Agenda settings (#agenda-settings) - 3. Calendar settings (#calendar-settings) - 4. Tags settings (#tags-settings) -3. Mappings (#mappings) - 1. Global mappings (#global-mappings) - 2. Agenda mappings (#agenda-mappings) - 3. Capture mappings (#capture-mappings) - 4. Note mappings (#note-mappings) - 5. Org mappings (#org-mappings) - 6. Edit Src mappings (#edit-src) - 7. Text objects (#text-objects) - 8. Dot repeat (#dot-repeat) -4. Tables (#tables) -5. Hyperlinks (#hyperlinks) -6. Autocompletion (#autocompletion) -7. Abbreviations (#abbreviations) -8. Formatting (#formatting) -9. User interface (#user-interface) - 1. Colors (#colors) - 2. Menu (#menu) - 3. Folds (#folds) -10. Advanced search (#advanced-search) -11. Notifications (experimental) (#notifications-experimental) -12. Clocking (#clocking) -13. Extract source code (tangle) (#extract-source-code-tangle) -14. Changelog (#changelog) - --------------------------------------------------------------------------------- -GETTING STARTED WITH ORGMODE *orgmode-getting_started_with_orgmode* - -To get a basic idea how Orgmode works, look at this screencast from @dhruvasagar (https://github.com/dhruvasagar) -that demonstrates how the similar Orgmode clone vim-dotoo (https://github.com/dhruvasagar/vim-dotoo) works. - -https://www.youtube.com/watch?v=nsv33iOnH34 (https://www.youtube.com/watch?v=nsv33iOnH34) - --------------------------------------------------------------------------------- -SETTINGS *orgmode-settings* - -Variable names mostly follow the same naming as Orgmode mappings. -Biggest difference is that underscores are being used instead of hyphens. - -Link to all settings file (lua/orgmode/config/defaults.lua) - -GLOBAL SETTINGS *orgmode-global_settings* - -ORG_AGENDA_FILES *orgmode-org_agenda_files* - -type: `string|string[]` -default value: `''` -Glob path where agenda files are read from. Can provide multiple paths via array. +*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| + - Troubleshooting |orgmode-configuration-troubleshooting| + +============================================================================== +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: -* `'~/Dropbox/org/*'`, -* `{'~/Dropbox/org/*', '~/my-orgs/**/*'}` +- `~/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. -ORG_DEFAULT_NOTES_FILE *orgmode-org_default_notes_file* +Example: `~/orgfiles/refile.org` -type: `string` -default value: `''` -Path to a file that will be used as a default target file when refiling -Example: `~/Dropbox/org/notes.org` -ORG_TODO_KEYWORDS *orgmode-org_todo_keywords* +org_todo_keywords *orgmode-org_todo_keywords* -type: `string[]` -default value: `{'TODO', '|', 'DONE'}` -List of "unfinished" and "finished" states. -`|` is used as a separator between "unfinished" and "finished". -If `|` is omitted, only last entry in array is considered a "finished" state. -To use Fast access to TODO States (https://orgmode.org/manual/Fast-access-to-TODO-states.html#Fast-access-to-TODO-states) +- 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 +, set a fast access key to at least one of the entries. -Examples (without the fast access): +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'}` +- `{'TODO', 'NEXT', '|', 'DONE'}` +- `{'TODO', 'WAITING', '|', 'DONE', 'DELEGATED'}` Examples (With fast access): -* `{'TODO(t)', 'NEXT(n)', '|', 'DONE(d)'}` -* `{'TODO(t)', 'NEXT', '|', 'DONE'}` - will work same as above. Only one todo keyword needs to have fast access key, others will be parsed from first char. +- `{'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. +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 value: `nil` -Set a org_todo_keyword (#org-todo-keywords) to use as the "starting" state for repeatable todos. +org_todo_repeat_to_state *orgmode-org_todo_repeat_to_state* -The keyword set here must exist in the org_todo_keywords (#org-todo-keywords) list, otherwise the first one defined will be used. +- Type: `string | nil` +- Default: `nil` -WIN_SPLIT_MODE *orgmode-win_split_mode* +Path to a file that will be used as a default target file when refiling. -type: `string|function|table` -default value: `horizontal` -Available options: +Set an entry from |orgmode-org_todokeywords| to use as the "starting" state for +repeatable todos. + +If provided value does not exist in |orgmode-org_todokeywords|, first entry +from that list is used. + + +win_split_mode *orgmode-win_split_mode* -* `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` +- Type: `string | function | [string, number]` +- Default: `'horizontal'` This option determines how to open agenda and capture window. -If none of the options above suit your needs, you can provide custom command string (see `:help `) or custom function: -Here are few examples: -Open in float 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 `). 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, @@ -213,71 +151,63 @@ Open in float window: end < -Always open in tab: -> - win_split_mode = 'tabnew' -< -Always open vertically: -> - win_split_mode = 'vsplit' -< -Always open horizontally with specific height of 20 lines: -> - win_split_mode = '20split' -< -WIN_BORDER *orgmode-win_border* +win_border *orgmode-win_border* -type: `string|string[]` -default value: `single` -Border style of floating windows. -Available options: +- 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 +- `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* +- always - calendar pop-up, help pop-up, notification pop-up +- `win_split_mode` is set to `float` - agenda window , capture window -type: `string` -default value: `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_startup_folded *orgmode-org_startup_folded* -ORG_TODO_KEYWORD_FACES *orgmode-org_todo_keyword_faces* +- 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 -type: `table` -default value: `{}` -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` +org_todo_keyword_faces *orgmode-org_todo_keyword_faces* + +- Type: `table` +- 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 = { @@ -288,198 +218,238 @@ Full configuration example with additional todo keywords and their colors: }) < -ORG_ARCHIVE_LOCATION *orgmode-org_archive_location* +***** -type: `string` -default value: `'%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 values: -* `'~/my-orgs/default-archive-file.org::'` - This value can be overridden per file basis with a org special keyword `#+ARCHIVE`. - Example: `#+ARCHIVE: ~/path/to/archive_file.org` +org_archive_location *orgmode-org_archive_location* -ORG_HIDE_LEADING_STARS *orgmode-org_hide_leading_stars* +- 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`. -type: `boolean` -default value: `false` -Hide leading stars for headings. -Example: + +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: -> +📝 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]] < -ORG_HIDE_EMPHASIS_MARKERS *orgmode-org_hide_emphasis_markers* +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` -type: `boolean` -default value: `false` Conceal bold/italic/underline/code/verbatim markers. -Ensure your `:h conceallevel` is set properly in order for this to function. -ORG_ELLIPSIS *orgmode-org_ellipsis* +Ensure your |conceallevel| is set properly in order for this to function. + + +org_ellipsis *orgmode-org_ellipsis* + +- Type: `string` +- Default: `'...'` -type: `string` -default value: `...` Marker used to indicate a folded headline. -Not applicable with new empty `foldtext` options in Neovim -ORG_LOG_DONE *orgmode-org_log_done* -type: `string|false` -default value: `time` +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 ``), or ignore providing note via `org_note_kill` (Default `ok`) -* `false` - Disable any logging +- `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 ``), or ignore providing note via `org_note_kill` (Default `ok`) +- `false` - Disable any logging + + +org_log_repeat *orgmode-org_log_repeat* -ORG_LOG_REPEAT *orgmode-org_log_repeat* +- Type: `string|false` +- Default: `time` -type: `string|false` -default value: `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 ``), or ignore providing note via `org_note_kill` (Default `ok`) -* `false` - Disable logging the `LAST_REPEAT` date +- `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 ``), or ignore providing note via `org_note_kill` (Default `ok`) +- `false` - Disable logging the `LAST_REPEAT` date -ORG_LOG_INTO_DRAWER *orgmode-org_log_into_drawer* -type: `string|nil` -default value: `nil` -Possible values: -Log TODO state changes into a drawer with the given name. The recommended value is `LOGBOOK`. -If `nil`, log into the section body. +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* +org_highlight_latex_and_related *orgmode-org_highlight_latex_and_related* + +- Type: `string|nil` +- Default: `nil` + +📝 NOTE: This option is experimental -type: `string|nil` -default value: `nil` 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 \)` - -This option requires setting `additional_vim_regex_highlighting = {'org'}` in tree-sitter configuration since its old Vim syntax: -> - require('nvim-treesitter.configs').setup { - highlight = { - enable = true, - additional_vim_regex_highlighting = {'org'}, -- This line is needed - }, - ensure_installed = {'org'}, - } -< +- `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 ): + - 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* +org_startup_indented *orgmode-org_startup_indented* + +- Type: `boolean` +- Default: `false` -type: `boolean` -default value: `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. +- `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 setting `vim.b.org_indent_mode` to either `true` or `false` when in a org -buffer. For example, if virtual indents were enabled in the current buffer then you could disable them immediately by +You can toggle Virtual indents on the fly by setting `vim.b.org_indent_mode` to +either `true` or `false` when in a org buffer. For example, if virtual indents +were enabled in the current buffer then you could disable them immediately by setting `vim.b.org_indent_mode = false`. -This feature has no effect when enabled on Neovim versions < 0.10.0 -ORG_ADAPT_INDENTATION *orgmode-org_adapt_indentation* +org_adapt_indentation *orgmode-org_adapt_indentation* + +- Type: `boolean` +- Default: `true` -type: `boolean` -default value: `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. +- `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 value: `true` +org_indent_mode_turns_off_org_adapt_indentation*orgmode-org_indent_mode_turns_off_org_adapt_indentation* + +- Type: `boolean` +- Defaul: `true` + Possible values: -* `true` - Disable `org_adapt_indentation` (#org_adapt_indentation) by default when `org_startup_indented` (#org_startup_indented) is enabled. -* `false` - Do not disable `org_adapt_indentation` (#org_adapt_indentation) by default when `org_startup_indented` (#org_startup_indented) is enabled. +- `true` - Disable |orgmode-org_adaptindentation| by default when |orgmode-org_startupindented| is enabled. +- `false` - Do not disable |orgmode-org_adaptindentation| by default when |orgmode-org_startupindented| is enabled. + + +org_indent_mode_turns_on_hiding_stars*orgmode-org_indent_mode_turns_on_hiding_stars* -ORG_INDENT_MODE_TURNS_ON_HIDING_STARS *orgmode-org_indent_mode_turns_on_hiding_stars* +- Type: `boolean` +- Defaul: `true` -type: `boolean` -default value: `true` Possible values: -* `true` - Enable `org_hide_leading_stars` (#org_hide_leading_stars) by default when `org_indent_mode` (#org_startup_indented) is enabled for buffer (`vim.b.org_indent_mode = true`). -* `false` - Do not modify the value in `org_hide_leading_stars` (#org_hide_leading_stars) by default when `.org_indent_mode` (#org_startup_indented) is enabled for buffer (`vim.b.org_indent_mode = true`). +- `true` - Enable |orgmode-org_hideleadingstars| by default when |orgmode-org_indentmode| is enabled for buffer (`vim.b.org_indent_mode = true`). +- `false` - Do not modify the value in |orgmode-org_hideleadingstars| by default when |orgmode-org_indentmode| is enabled for buffer (`vim.b.org_indent_mode = true`). -ORG_SRC_WINDOW_SETUP *orgmode-org_src_window_setup* -type: `string|function` -default value: "top 16new" -If the value is a string, it will be run directly as input to `:h 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_src_window_setup *orgmode-org_src_window_setup* -ORG_EDIT_SRC_CONTENT_INDENTATION *orgmode-org_edit_src_content_indentation* +- Type: `string | function` +- Default: `'top 16new'` -type: `number` -default value: 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. +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_CUSTOM_EXPORTS *orgmode-org_custom_exports* -type: `table` -default value: `{}` -Add custom export options to the export prompt. -Structure: -> - [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 - } +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. +- `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 = { @@ -503,136 +473,172 @@ For example, lets add option to export to `rtf` format via `pandoc`: }) < -ORG_TIME_STAMP_ROUNDING_MINUTES *orgmode-org_time_stamp_rounding_minutes* -type: `number` -default value: `5` -Number of minutes to increase/decrease when using org_timestamp_up (#org_timestamp_up)/org_timestamp_down (#org_timestamp_down) +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_timestampup|/|orgmode-org_timestampdown| + + +org_blank_before_new_entry *orgmode-org_blank_before_new_entry* -ORG_BLANK_BEFORE_NEW_ENTRY *orgmode-org_blank_before_new_entry* +- Type: `table` +- Default: `{ heading = true, plain_list_item = false }` -type: `table` -default value: `{ 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` +- 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 value: `uuidgen` +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 value: `%Y%m%d%H%M%S` -Format of the id generated when org_id_method (#org_id_method) is set to `ts`. +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_idmethod| is set to `ts`. -ORG_ID_METHOD *orgmode-org_id_method* -type: `'uuid' | 'ts' | 'org'` -default value: `uuid` +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 org_id_uuid_program (#org_id_uuid_program) to generate the id -* `ts` - Generate id from current timestamp using format org_id_ts_format (#org_id_ts_format) -* `org` - Generate a random 12 digit number and prepend org_id_prefix (#org_id_prefix) +- `uuid` - Use |orgmode-org_iduuidprogram| to generate + the id +- `ts` - Generate id from current timestamp using format |orgmode-org_idtsformat| +- `org` - Generate a random 12 digit number and prepend |orgmode-org_idprefix| + + +org_id_prefix *orgmode-org_id_prefix* -ORG_ID_PREFIX *orgmode-org_id_prefix* +- Type: `string | nil` +- Default: `nil` -type: `string | nil` -default value: `nil` -Prefix added to the generated id when org_id_method (#org_id_method) is set to `org`. +Prefix added to the generated id when |orgmode-org_idmethod| is set to `org`. -ORG_ID_LINK_TO_ORG_USE_ID *orgmode-org_id_link_to_org_use_id* -type: `boolean` -default value: `false` -If `true`, generate ID with the Org ID module and append it to the headline as property. More info on org_store_link (#org_store_link) +org_id_link_to_org_use_id *orgmode-org_id_link_to_org_use_id* -ORG_BABEL_DEFAULT_HEADER_ARGS *orgmode-org_babel_default_header_args* +- Type: `boolean` +- Default: `false` -type: `table` -default value: `{ [':tangle'] = 'no', [':noweb'] = no }` -Default header args for extracting source code. See Extract source code (tangle) (#extract-source-code-tangle) for more details. +If `true`, generate ID with the Org ID module and append it to the headline as +property. More info on |orgmode-org_storelink| -CALENDAR_WEEK_START_DAY *orgmode-calendar_week_start_day* -type: `number` -default value: `1` +org_babel_default_header_args *orgmode-org_babel_default_header_args* + +- Type: `table` +- 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 +- `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|) + -Determine on which day the week will start in calendar modal (ex: changing the date under cursor (#org_change_date)) +emacs_config *orgmode-emacs_config* -EMACS_CONFIG *orgmode-emacs_config* +- Type: `table` +- Default: `{ executable_path = 'emacs', config_path=nil }` -type: `table` -default value: `{ 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: +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` +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. +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-agenda_settings* -ORG_DEADLINE_WARNING_DAYS *orgmode-org_deadline_warning_days* +AGENDA SETTINGS *orgmode-configuration-agenda-settings* + + +org_deadline_warning_days *orgmode-org_deadline_warning_days* + +- Type: `number` +- Default: `14` -type: `number`, -default value: `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` +Example: If Today is `2021-06-10`, and we have these tasks: -`Task 1` is visible in today's agenda -`Task 2` is not visible in today's agenda until `2021-06-16` +- `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 value: 'week' -possible string values: `day`, `week`, `month`, `year` -Default time span shown when agenda is opened. +org_agenda_span *orgmode-org_agenda_span* -ORG_AGENDA_START_ON_WEEKDAY *orgmode-org_agenda_start_on_weekday* +- Type: `string|number` +- Default: `'week'` -type: `number` -default value: `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 +_possible string values_: `day`, `week`, `month`, `year` Default time span +shown when agenda is opened. -ORG_AGENDA_START_DAY *orgmode-org_agenda_start_day* -type: `string` -default value: `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_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_CUSTOM_COMMANDS *orgmode-org_agenda_custom_commands* +org_agenda_start_day *orgmode-org_agenda_start_day* -type: `table` -default value: `{}` +- Type: `string` +- Default: `nil` -Define custom agenda views that are available through the (org_agenda)[#org_agenda] mapping. -It is possible to combine multiple agenda types into single view. -An example: -> +_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` +- Default: `{}` + +Define custom agenda views that are available through the +(org_agenda)[#org_agenda] mapping. It is possible to combine multiple agenda +types into single view. An example: + +>lua require('orgmode').setup({ org_agenda_files = {'~/org/**/*'}, org_agenda_custom_commands = { @@ -692,112 +698,162 @@ An example: }) < -ORG_AGENDA_SORTING_STRATEGY *orgmode-org_agenda_sorting_strategy* - -type: `table<'agenda' | 'todo' | 'tags', OrgAgendaSortingStrategy[]><` -default value: `{ 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 headines 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 value: `-` -Separator used to separate multiple agenda views generated by 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 value: `false` + +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 headines 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 +org_agendacustomcommands. 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` -default value: `{ 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]]`) -* `%`: 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. + +org_capture_templates *orgmode-org_capture_templates* + +- Type: `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]]`) +- `%`: Insert current date/time formatted according to + lua date 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 `org_default_notes_file` (#orgdefaultnotesfile) 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.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 - * `{ 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: -> - 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 +- `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_defaultnotesfile| 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 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 + + 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', @@ -806,7 +862,8 @@ Example: < Journal example: -> + +>lua { j = { description = 'Journal', @@ -817,7 +874,8 @@ Journal example: < Journal example with dynamic target, i.e. a separate file per month: -> + +>lua { J = { description = 'Journal', @@ -828,7 +886,8 @@ Journal example with dynamic target, i.e. a separate file per month: < Nested key example: -> + +>lua { e = 'Event', er = { @@ -867,7 +926,8 @@ Nested key example: < Lua expression example: -> + +>lua { j = { description = 'Journal', @@ -878,127 +938,168 @@ Lua expression example: } < -ORG_AGENDA_MIN_HEIGHT *orgmode-org_agenda_min_height* -type: `number` -default value: `16` +org_agenda_min_height *orgmode-org_agenda_min_height* + +- Type: `number` +- Default: `16` + Indicates the minimum height that the agenda window will occupy. -ORG_PRIORITY_HIGHEST *orgmode-org_priority_highest* -type: `string|number` -default value: `A` -Indicates highest priority for a task in the agenda view. -Example: -`* TODO [#A] This task has the highest priority` +org_priority_highest *orgmode-org_priority_highest* -ORG_PRIORITY_DEFAULT *orgmode-org_priority_default* +- Type: `string|number` +- Default: `A` -type: `string|number` -default value: `B` -Indicates normal priority for a task in the agenda view. -This is the default priority for all tasks if other priority is not applied -Example: -`* TODO [#B] This task has the normal priority` -`* TODO And this one has the same priority` +Indicates highest priority for a task in the agenda view. Example: -ORG_PRIORITY_LOWEST *orgmode-org_priority_lowest* +>org + * TODO [#A] This task has the highest priority +< -type: `string|number` -default value: `C` -Indicates lowest priority for a task in the agenda view. -Example: -`* TODO [#B] This task has the normal priority` -`* TODO And this one has the same priority` -`* TODO [#C] I'm lowest in priority` -ORG_AGENDA_SKIP_SCHEDULED_IF_DONE *orgmode-org_agenda_skip_scheduled_if_done* +org_priority_default *orgmode-org_priority_default* + +- Type: `string|number` +- Default: `B` + +Indicates normal priority for a task in the agenda view. This is the default +priority for all tasks if other priority is not applied Example: + +>org + * TODO [#B] This task has the normal priority + * TODO And this one has the same priority +< + + +org_priority_lowest *orgmode-org_priority_lowest* + +- Type: `string|number` +- Default: `C` + +Indicates lowest priority for a task in the agenda view. Example: -type: `boolean` -default value: `false` +>org + * TODO [#B] This task has the normal priority + * TODO And this one has the same priority as above one + * TODO [#C] I'm lowest in priority +< + + +org_agenda_skip_scheduled_if_done *orgmode-org_agenda_skip_scheduled_if_done* + +- Type: `boolean` +- Default: `false` Hide scheduled entries from agenda if they are in a "DONE" state. -ORG_AGENDA_SKIP_DEADLINE_IF_DONE *orgmode-org_agenda_skip_deadline_if_done* -type: `boolean` -default value: `false` +org_agenda_skip_deadline_if_done *orgmode-org_agenda_skip_deadline_if_done* + +- Type: `boolean` +- Default: `false` Hide deadline entries from agenda if they are in a "DONE" state. -ORG_AGENDA_TEXT_SEARCH_EXTRA_FILES *orgmode-org_agenda_text_search_extra_files* -type: `string[]` -default value: `{}` -Additional files to search from agenda search prompt. -Currently it accepts only a single value: `agenda-archives`. -Example value: `{'agenda-archives'}` +org_agenda_text_search_extra_files*orgmode-org_agenda_text_search_extra_files* + +- Type: `('agenda-archives')[]` +- Default: `{}` + +Additional files to search from agenda search prompt. Currently it accepts only +a single value: `agenda-archives`. Example value: `{'agenda-archives'}` + -CALENDAR SETTINGS *orgmode-calendar_settings* +CALENDAR SETTINGS *orgmode-configuration-calendar-settings* -Adjust behavior of the calendar modal (ex: changing the date under cursor (#org_change_date)). +Adjust behavior of the calendar modal (ex: +|orgmode-changing-the-date-under-cursor|). -CALENDAR.ROUND_MIN_WITH_HOURS *orgmode-calendar.round_min_with_hours* -type: `boolean` -default: `true` -Should minutes be rounded, when the hour is changed. It behaves more fluently when changing the hours, especially when scheduling from the current time (which can be something odd). If set to false, the minutes are unchanged while changing the hours. +calendar.round_min_with_hours *orgmode-calendar.round_min_with_hours* -CALENDAR.MIN_BIG_STEP *orgmode-calendar.min_big_step* +- Type: `boolean` +- Default: `true` + +Should minutes be rounded, when the hour is changed. It behaves more fluently +when changing the hours, especially when scheduling from the current time +(which can be something odd). If set to false, the minutes are unchanged while +changing the hours. + + +calendar.min_big_step *orgmode-calendar.min_big_step* + +- Type: `number` +- Default: `15` -type: `number` -default: `15` The step size for changing the minutes while the cursor is on the first digit. -CALENDAR.MIN_SMALL_STEP *orgmode-calendar.min_small_step* -type: `number` -default: same as [](#org_time_stamp_rounding_minutes) +calendar.min_small_step *orgmode-calendar.min_small_step* + +- Type: `number` +- Default: same as |orgmode-org_timestamproundingminutes| + The step size for changing the minutes while the cursor is on the second digit. -TAGS SETTINGS *orgmode-tags_settings* -ORG_TAGS_COLUMN *orgmode-org_tags_column* +TAGS SETTINGS *orgmode-configuration-tags-settings* + + +org_tags_column *orgmode-org_tags_column* -type: `number` -default value: `80` -The column to which tags should be indented in a headline. -If this number is positive, it specifies the column. -If it is negative, it means that the tags should be flushright to that column. -For example, -80 works well for a normal 80 character screen. -When 0, place tags directly after headline text, with only one space in between. +- Type: `number` +- Default: `80` -ORG_USE_TAG_INHERITANCE *orgmode-org_use_tag_inheritance* +The column to which tags should be indented in a headline. If this number is +positive, it specifies the column. If it is negative, it means that the tags +should be flushright to that column. For example, -80 works well for a normal +80 character screen. When 0, place tags directly after headline text, with only +one space in between. -type: `boolean` -default value: `true` -When set to `true`, tags are inherited from parents for purposes of searching. Which means that if you have this structure: -> + +org_use_tag_inheritance *orgmode-org_use_tag_inheritance* + +- Type: `boolean` +- Default: `true` + When set to `true`, tags are + +inherited from parents for purposes of searching. Which means that if you have +this structure: + +>org * TODO My top task :MYTAG: ** TODO MY child task :CHILDTAG: *** TODO Nested task < -First headline has tag `MYTAG` -Second headline has tags `MYTAG` and `CHILDTAG` -Third headline has tags `MYTAG` and `CHILDTAG` -When disabled, headlines have only tags that are directly applied to them. +First headline has tag `MYTAG` Second headline has tags `MYTAG` and `CHILDTAG` +Third headline has tags `MYTAG` and `CHILDTAG`. When disabled, headlines have +only tags that are directly applied to them. -ORG_TAGS_EXCLUDE_FROM_INHERITANCE *orgmode-org_tags_exclude_from_inheritance* -type: `string[]` -default value: `{}` -List of tags that are excluded from inheritance. -Using the example above, setting this variable to `{'MYTAG'}`, second and third headline would have only `CHILDTAG`, where `MYTAG` would not be inherited. +org_tags_exclude_from_inheritance *orgmode-org_tags_exclude_from_inheritance* --------------------------------------------------------------------------------- -MAPPINGS *orgmode-mappings* +- Type: `string[]` +- Default: `{}` -Mappings try to mimic some of the Orgmode mappings, but since Orgmode uses `CTRL + c` as a modifier most of the time, we have to take a different route. -When possible, instead of `CTRL + C`, prefix `o` is used. This is customizable via the `mappings.prefix` setting. +List of tags that are excluded from inheritance. Using the example above, +setting this variable to `{'MYTAG'}`, second and third headline would have only +`CHILDTAG`, where `MYTAG` would not be inherited. + + +MAPPINGS *orgmode-configuration-mappings* + +Mappings try to mimic some of the Orgmode mappings, but since Orgmode uses +`CTRL + c` as a modifier most of the time, we have to take a different route. +When possible, instead of `CTRL + C`, prefix `o` is used. This is +customizable via the `mappings.prefix` setting. To disable all mappings, just pass `disable_all = true` to mappings settings: -> + +>lua require('orgmode').setup({ org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, org_default_notes_file = '~/Dropbox/org/refile.org', @@ -1009,7 +1110,8 @@ To disable all mappings, just pass `disable_all = true` to mappings settings: < To disable a specific mapping, set it's value to `false`: -> + +>lua require('orgmode').setup({ org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, org_default_notes_file = '~/Dropbox/org/refile.org', @@ -1022,8 +1124,10 @@ To disable a specific mapping, set it's value to `false`: }) < -To change a key mapping's `lhs` but not its `desc`, provide a string or a table: -> +To change a key mapping's `lhs` but not its `desc`, provide a string or a +table: + +>lua require('orgmode').setup({ org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, org_default_notes_file = '~/Dropbox/org/refile.org', @@ -1036,1099 +1140,1762 @@ To change a key mapping's `lhs` but not its `desc`, provide a string or a table: }, } }) - To change a key mapping's `lhs` and its `desc`, provide a table: < -lua -require('orgmode').setup({ - org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/*/'}, - org_default_notes_file = '~/Dropbox/org/refile.org', - mappings = { - global = { - org_capture = { '', desc = 'Open Capture Prompt' } - } - } -}) -> - (The `desc` value is displayed in tools like WhichKey.) - You can find the configuration file that holds all default mappings [here](./lua/orgmode/config/mappings/init.lua) - **NOTE**: All mappings are normal mode mappings (`nnoremap`) with exception of `org_return` - ### Use Enter in insert mode to add list items/checkboxes/todos - By default, adding list items/checkboxes/todos is done with [org_meta_return](#org_meta_return) which is a normal mode mapping. - If you want to have an insert mode mapping there are two options: - 1. If your terminal supports it, map a key like `Shift + Enter` to the meta return mapping (Recommended): -< +To change a key mapping's `lhs` and its `desc`, provide a table: -lua -vim.api.nvim_create_autocmd('FileType', { - pattern = 'org', - callback = function() - vim.keymap.set('i', '', 'lua require("orgmode").action("org_mappings.meta_return")', { - silent = true, - buffer = true, +>lua + require('orgmode').setup({ + org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, + org_default_notes_file = '~/Dropbox/org/refile.org', + mappings = { + global = { + org_capture = { '', desc = 'Open Capture Prompt' } + } + } }) - end, -}) -> - 2. If you want to use only enter, enable `org_return_uses_meta_return` option: < -lua -require('orgmode').setup({ - org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/*/'}, - org_default_notes_file = '~/Dropbox/org/refile.org', - mappings = { - org_return_uses_meta_return = true - } -}) -> - This will trigger `org_meta_return` if there is no content after the cursor position (either at the end of line or has just trailing spaces). - Just note that this option always tries to use `meta_return`, which also adds new headlines - automatically if you are on the headline line, which can give undesired results. - ### Global mappings - There are only 2 global mappings that are accessible from everywhere. - #### **org_agenda** - _mapped to_: `oa`
- Opens up agenda prompt. - #### **org_capture** - _mapped to_: `oc`
- Opens up capture prompt. - These live under `mappings.global` and can be overridden like this: -< +(The `desc` value is displayed in tools like WhichKey.) -lua -require('orgmode').setup({ - org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/*/'}, - org_default_notes_file = '~/Dropbox/org/refile.org', - mappings = { - global = { - org_agenda = 'gA', - org_capture = 'gC' - } - } -}) -> - If you want to use multiple mappings for same thing, pass array of mappings: -< +You can find the configuration file that holds all default mappings here +<../lua/orgmode/config/mappings/init.lua> -lua -require('orgmode').setup({ - org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/*/'}, - org_default_notes_file = '~/Dropbox/org/refile.org', - mappings = { - global = { - org_agenda = {'gA', 'oa'}, - org_capture = {'gC', 'oc'} - } - } -}) -> - ### Agenda mappings - Mappings used in agenda view window. - #### **org_agenda_later** - _mapped to_: `f`
- Go to next agenda span - #### **org_agenda_earlier** - _mapped to_: `b`
- Go to previous agenda span - #### **org_agenda_goto_today** - _mapped to_: `.`
- Go to span with for today - #### **org_agenda_day_view** - _mapped to_: `vd`
- Show agenda day view - #### **org_agenda_week_view** - _mapped to_: `vw`
- Show agenda week view - #### **org_agenda_month_view** - _mapped to_: `vm`
- Show agenda month view - #### **org_agenda_year_view** - _mapped to_: `vy`
- Show agenda year view - #### **org_agenda_quit** - _mapped to_: `q`
- Close agenda - #### **org_agenda_switch_to** - _mapped to_: ``
- Open selected agenda item in the same buffer - #### **org_agenda_goto** - _mapped to_: `{''}`
- Open selected agenda item in split window - #### **org_agenda_goto_date** - _mapped to_: `J`
- Open calendar that allows selecting date to jump to - #### **org_agenda_redo** - _mapped to_: `r`
- Reload all org files and refresh current agenda view - #### **org_agenda_todo** - _mapped to_: `t`
- Change `TODO` state of an item in both agenda and original Org file - #### **org_agenda_clock_in** - _mapped to_: `I`
- Clock in item under cursor.
- See [Clocking](#clocking) for more details. - #### **org_agenda_clock_out** - _mapped to_: `O`
- Clock out currently active clock item.
- See [Clocking](#clocking) for more details. - #### **org_agenda_clock_cancel** - _mapped to_: `X`
- Cancel clock on currently active clock item.
- See [Clocking](#clocking) for more details. - #### **org_agenda_clock_goto** - _mapped to_: `oxj`
- Jump to currently clocked in headline.
- See [Clocking](#clocking) for more details. - #### **org_agenda_clockreport_mode** - _mapped to_: `R`
- Show clock report at the end of the agenda for current agenda time range
- See [Clocking](#clocking) for more details. - #### **org_agenda_priority** - _mapped to_: `o,`
- Choose the priority of a headline item. - #### **org_agenda_priority_up** - _mapped to_: `+`
- Increase the priority of a headline item. - #### **org_agenda_priority_down** - _mapped to_: `-`
- Decrease the priority of a headline item. - #### **org_agenda_archive** - mapped to: `o$`
- Archive headline item to archive location. - #### **org_agenda_toggle_archive_tag** - _mapped to_: `oA`
- Toggle "ARCHIVE" tag of a headline item. - #### **org_agenda_set_tags** - _mapped to_: `ot`
- Set tags on current headline item. - #### **org_agenda_deadline** - _mapped to_: `oid`
- Insert/Update deadline date on current headline item.
- #### **org_agenda_schedule** - _mapped to_: `ois`
- Insert/Update scheduled date on current headline item.
- #### **org_agenda_refile** - _mapped to_: `or`
- Refile current headline to a destination org-file. - Same as [org_refile](#org_refile) but from agenda view. - #### **org_agenda_add_note** - _mapped to_: `ona`
- Add note to the current headline - #### **org_agenda_filter** - _mapped to_: `/`
- Open prompt that allows filtering current agenda view by category, tags and title (vim regex, see `:help vim.regex()`)
- Example:
- Having `todos.org` file with headlines that have tags `mytag` or `myothertag`, and some of them have `check` in content, this search:
- `todos+mytag/check/`
- Returns all headlines that are in `todos.org` file, that have `mytag` tag, and have `check` in headline title. Note that regex is case sensitive by default.
- Use vim regex flag `\c` to make it case insensitive. See `:help vim.regex()` and `:help /magic`.
- Pressing `` in filter prompt autocompletes categories and tags. - #### **org_agenda_show_help** - _mapped to_: `g?`
- Show help popup with mappings - These mappings live under `mappings.agenda`, and can be changed like this: -< +**NOTE**: All mappings are normal mode mappings (`nnoremap`) with exception of +`org_return` -lua -require('orgmode').setup({ - org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/*/'}, - org_default_notes_file = '~/Dropbox/org/refile.org', - mappings = { - agenda = { - org_agenda_later = '>', - org_agenda_earlier = '<', - org_agenda_goto_today = {'.', 'T'} - } - } -}) -> - ### Capture mappings - Mappings used in capture window. - #### **org_capture_finalize** - _mapped to_: ``
- Save current capture content to `org_default_notes_file` and close capture window - #### **org_capture_refile** - _mapped to_: `or`
- Refile capture content to specific destination - #### **org_capture_kill** - _mapped to_: `ok`
- Close capture window without saving anything - #### **org_capture_show_help** - _mapped to_: `g?`
- Show help popup with mappings - These mappings live under `mappings.capture`, and can be changed like this: -< -lua -require('orgmode').setup({ - org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/*/'}, - org_default_notes_file = '~/Dropbox/org/refile.org', - mappings = { - capture = { - org_capture_finalize = 'w', - org_capture_refile = 'R', - org_capture_kill = 'Q' - } - } -}) -> - ### Note mappings - Mappings used in closing note window. - #### **org_note_finalize** - _mapped to_: ``
- Save note window content as closing note for a headline. Ignores first comment (if exists) - #### **org_note_kill** - _mapped to_: `ok`
- Close note window without saving anything -< +Use Enter in insert mode to add list items/checkboxes/todos*orgmode-Use-Enter-in-insert-mode-to-add-list-items/checkboxes/todos* -lua -require('orgmode').setup({ - org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/*/'}, - org_default_notes_file = '~/Dropbox/org/refile.org', - mappings = { - note = { - org_note_finalize = 'w', - org_note_kill = 'Q' - } - } -}) -> - ### Org mappings - Mappings for `org` files. - #### **org_refile** - _mapped to_: `or`
- Refile current headline, including its subtree, to a destination org-file. This file must be one of the files specified for the `org_agenda_files` setting. A target headline in the destination file can be specified with `destination.org/`. If there are multiple headlines with the same name in the destination file, the first occurence will be used. - #### **org_timestamp_up** - _mapped to_: ``
- Increase date part under under cursor. Accepts count: (Example: `5`)
- `|` in examples references cursor position.
- - Year - Example date: `<202|1-10-01 Fri 10:30>` becomes `<202|2-10-01 Sat 10:30>` - - Month - Example date: `<2021-1|0-01 Fri 10:30>` becomes `<2022-1|1-01 Mon 10:30>` - - Day - Example date: `<2021-10-0|1 Fri 10:30>` becomes `<2022-10-0|2 Sat 10:30>`. Same thing happens when cursor is on day name. - - Hour - Example date: `<2021-10-01 Fri 1|0:30>` becomes `<2022-10-02 Sat 1|1:30>`. - - Minute - Example date: `<2021-10-01 Fri 10:3|0>` becomes `<2022-10-02 Sat 11:3|5>`. See [org_time_stamp_rounding_minutes](#org_time_stamp_rounding_minutes) for steps configuration. - - Repeater/Delay range (`h->d->w->m->y`) - Example date: `<2021-10-01 Fri 10:30 +1|w>` becomes `<2021-10-01 Fri 10:30 +1|m>` - - Active/Inactive state - (`<` to `[` and vice versa) - Example date: `|<2021-10-01 Fri 10:30>` becomes `|[2021-10-01 Fri 10:30]` - #### **org_timestamp_down** - _mapped to_: ``
- Decrease date part under under cursor.
- Same as [org_timestamp_up](#org_timestamp_up), just opposite direction. - #### **org_timestamp_up_day** - _mapped to_: ``
- Increase date under cursor by 1 or "count" day(s) (Example count: `5`). - #### **org_timestamp_down_day** - _mapped to_: ``
- Decrease date under cursor by 1 or "count" day(s) (Example count: `5`). - #### **org_change_date** - _mapped to_: `cid`
- Change date under cursor. Opens calendar to select new date - #### **org_toggle_timestamp_type** - _mapped to_: `od!`
- Switches the timestamp under the cursor between inactive and active. - #### **org_priority** - _mapped to_: `o,`
- Choose the priority of a headline item. - #### **org_priority_up** - _mapped to_: `ciR`
- Increase the priority of a headline item. - #### **org_priority_down** - _mapped to_: `cir`
- Decrease the priority of a headline item. - #### **org_todo** - _mapped to_: `cit`
- Cycle todo keyword forward on current headline or open fast access to TODO states prompt (see [org_todo_keywords](#org_todo_keywords)) if it's enabled. - #### **org_todo_prev** - _mapped to_: `ciT`
- Cycle todo keyword backward on current headline. - #### **org_toggle_checkbox** - _mapped to_: ``
- Toggle current line checkbox state - #### **org_toggle_heading** - _mapped to_: `o*`
- Toggle current line to headline and vice versa. Checkboxes will turn into TODO headlines. - #### **org_insert_link** - _mapped to_: `oli`
- Insert a hyperlink at cursor position. When the cursor is on a hyperlink, edit that hyperlink.
- If there are any links stored with [org_store_link](#org_store_link), pressing `` to autocomplete the input - will show list of all stored links to select. Links generated with ID are properly expanded to valid links after selection. - #### **org_store_link** - _mapped to_: `ols`
- Generate a link to the closest headline. If [org_id_link_to_org_use_id](#org_id_link_to_org_use_id) is `true`, - it appends the `ID` property to the headline, and generates link with that id to be inserted via [org_insert_link](#org_insert_link). - When [org_id_link_to_org_use_id](#org_id_link_to_org_use_id) is `false`, it generates the standard file::*headline link (example: `file:/path/to/my/todos.org::*My headline`) - #### **org_open_at_point** - _mapped to_: `oo`
- Open hyperlink or date under cursor. When date is under the cursor, open the agenda for that day.
- #### **org_edit_special** - _mapped to_: `o'`
- Open a source block for editing in a temporary buffer of the associated `filetype`.
- This is useful for editing text with language servers attached, etc. When the buffer is closed, the text of the underlying source block in the original Org file is updated. - _Note that if the Org file that the source block comes from is edited before the special edit buffer is closed, the edits will not be applied. The special edit buffer contents can be recovered from :messages output_ - #### **org_add_note** - _mapped to_: `ona`
- Add note to the current headline - #### **org_cycle** - _mapped to_: ``
- Cycle folding for current headline - #### **org_global_cycle** - _mapped to_: ``
- Cycle global folding - #### **org_archive_subtree** - _mapped to_: `o$`
- Archive current headline to archive location - #### **org_set_tags_command** - _mapped to_: `ot`
- Set tags on current headline - #### **org_toggle_archive_tag** - _mapped to_: `oA`
- Toggle "ARCHIVE" tag on current headline - #### **org_do_promote** - _mapped to_: `<<`
- Promote headline - #### **org_do_demote** - _mapped to_: `>>`
- Demote headline - #### **org_promote_subtree** - _mapped to_: ` - Promote subtree - #### **org_demote_subtree** - _mapped to_: `>s`
- Demote subtree - #### **org_meta_return** - _mapped to_: ``
- Add headline, list item or checkbox below, depending on current line - #### **org_insert_heading_respect_content** - _mapped to_: `oih`
- Add headline after current headline + it's content with same level - #### **org_insert_todo_heading** - _mapped to_: `oiT`
- Add TODO headline right after the current headline - #### **org_insert_todo_heading_respect_content** - _mapped to_: `oit`
- Add TODO headliner after current headline + it's content - #### **org_move_subtree_up** - _mapped to_: `oK`
- Move current headline + it's content up by one headline - #### **org_move_subtree_down** - _mapped to_: `oJ`
- Move current headline + it's content down by one headline - #### **org_export** - _mapped to_: `oe`
- Open export options.
- **NOTE**: Exports are handled via `emacs` and `pandoc`. This means that `emacs` and/or `pandoc` must be in `$PATH`.
- see [org_custom_exports](#org_custom_exports) if you want to add your own export options. - #### **org_next_visible_heading** - _mapped to_: `}`
- Go to next heading (any level).
- #### **org_previous_visible_heading** - _mapped to_: `{`
- Go to previous heading (any level).
- #### **org_forward_heading_same_level** - _mapped to_: `]]`
- Go to next heading on same level. Doesn't go outside of parent.
- #### **org_backward_heading_same_level** - _mapped to_: `[[`
- Go to previous heading on same level. Doesn't go outside of parent.
- #### **outline_up_heading** - _mapped to_: `g{`
- Go to parent heading.
- #### **org_deadline** - _mapped to_: `oid`
- Insert/Update deadline date.
- #### **org_schedule** - _mapped to_: `ois`
- Insert/Update scheduled date.
- #### **org_time_stamp** - _mapped to_: `oi.`
- Insert/Update date under cursor.
- #### **org_time_stamp_inactive** - _mapped to_: `oi!`
- Insert/Update inactive date under cursor.
- #### **org_clock_in** - _mapped to_: `oxi`
- Clock in headline under cursor.
- See [Clocking](#clocking) for more details. - #### **org_clock_out** - _mapped to_: `oxo`
- Clock out headline under cursor.
- See [Clocking](#clocking) for more details. - #### **org_clock_cancel** - _mapped to_: `oxq`
- Cancel currently active clock on current headline.
- See [Clocking](#clocking) for more details. - #### **org_clock_goto** - _mapped to_: `oxj`
- Jump to currently clocked in headline.
- See [Clocking](#clocking) for more details. - #### **org_set_effort** - _mapped to_: `oxe`
- Set effort estimate property on for current headline.
- See [Clocking](#clocking) for more details. - #### **org_babel_tangle** - _mapped to_: `obt`
- Tangle current file. See [Extract source code (tangle)](#extract-source-code-tangle) for more details. - #### **org_show_help** - _mapped to_: `g?`
- Show help popup with mappings - These mappings live under `mappings.org`, and can be changed like this: -< +By default, adding list items/checkboxes/todos is done with +|orgmode-org_metareturn| which is a normal mode mapping. If you want to have an +insert mode mapping there are two options: -lua -require('orgmode').setup({ - org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/*/'}, - org_default_notes_file = '~/Dropbox/org/refile.org', - mappings = { - org = { - org_timestamp_up = '+', - org_timestamp_down = '-' - } - } -}) -> - ### Edit Src - Mappings applied when editing a `SRC` block content via `org_edit_special`. - #### **org_edit_src_abort** - _mapped to_: `ok`
- Abort changes made to temporary buffer created from the content of a `SRC` block, see above.
- #### **org_edit_src_save** - _mapped to_: `ow`
- Apply changes from the special buffer to the source Org buffer
- #### **org_edit_src_save_exit** - _mapped to_: `'`
- Apply changes from the special buffer to the source Org buffer and close the edit special window
- #### **org_edit_src_show_help** - _mapped to_: `g?`
- Show help within the temporary buffer used to edit the content of a `SRC` block.
- ### Text objects - Operator mappings for `org` files.
- Example: Pressing `vir` select everything from current heading and all child.
- `inner` means that it doesn't select the stars, where `around` selects `inner` + `stars`.
- See [this issue comment](https://github.com/nvim-orgmode/orgmode/issues/48#issuecomment-884528170) for visual preview.
- Note: Some mappings can clash with other plugin mappings, like [gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim) which also has `ih` operator mapping. - #### **inner_heading** - _mapped to_: `ih`
- Select inner heading with content. - #### **around_heading** - _mapped to_: `ah`
- Select around heading with content. - #### **inner_subtree** - _mapped to_: `ir`
- Select whole inner subtree. - #### **around_subtree** - _mapped to_: `ar`
- Select around whole subtree. - #### **inner_heading_from_root** - _mapped to_: `Oh` (big letter `o`)
- select everything from first level heading to the current heading. - #### **around_heading_from_root** - _mapped to_: `OH` (big letter `o`)
- select around everything from first level heading to the current heading. - #### **inner_subtree_from_root** - _mapped to_: `Or` (big letter `o`)
- select everything from first level subtree to the current subtree. - #### **around_subtree_from_root** - _mapped to_: `OR` (big letter `o`)
- select around everything from first level subtree to the current subtree.
- These mappings live under `mappings.text_objects`, and can be changed like this: -< +1. If your terminal supports it, map a key like `Shift + Enter` to the +meta return mapping (Recommended): -lua -require('orgmode').setup({ - org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/*/'}, - org_default_notes_file = '~/Dropbox/org/refile.org', - mappings = { - text_objects = { - inner_heading = 'ic', - } - } -}) -> - #### **markup text objects** - Mappings to select inner/outer markup entries. For example, having `This is *bold*`, and if cursor is in middle of `*bold*`, doing `ci*` changes only inner text, - and doing `ca*` changes outer text. - These are supported: `*`, `_`, `/`, `+`, `~`, `=` - These cannot be changed. - ### Dot repeat - To make all mappings dot repeatable, install [vim-repeat](https://github.com/tpope/vim-repeat) plugin. - ## Tables - Tables can be formatted via built in `formatexpr` (see `:help gq`) - For example, having this content: +>lua + vim.api.nvim_create_autocmd('FileType', { + pattern = 'org', + callback = function() + vim.keymap.set('i', '', 'lua require("orgmode").action("org_mappings.meta_return")', { + silent = true, + buffer = true, + }) + end, + }) < -* TODO My headline - DEADLINE: +1. If you want to use only enter, enable `org_return_uses_meta_return` option: -|Header 1|Header 2 - |- - | col 1| col 2| -> - And going to line `4` and pressing `gqgq`, it will format it to this: +>lua + require('orgmode').setup({ + org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, + org_default_notes_file = '~/Dropbox/org/refile.org', + mappings = { + org_return_uses_meta_return = true + } + }) < -* TODO My headline - DEADLINE: - -| Header 1 | Header 2 | - |----------+----------| - | col 1 | col 2 | -> - ## Hyperlinks - The format for links is either `[[LINK]]` or `[[LINK][DESCRIPTION]]`. If a description is provided, the actual link is concealed in favor of the description. - Hyperlink types supported: - - URL (http://, https://) - - File (starts with `file:`. Example: `file:/home/user/.config/nvim/init.lua`) Optionally, target can be specified: - - Headline - It needs to start with `*` (Example: `file:/home/user/org/file.org::*Specific Headline`) - - Custom id - It needs to start with `#` (Example: `file:/home/user/org/file.org::#my-custom-id`) - - Line number - It needs to be a number (Example: `file:/home/user/org/file.org::235`) - - Headline title target within the same file (starts with `*`) (Example: `*Specific headline`) - - Headline with `CUSTOM_ID` property within the same file (starts with `#`) (Example: `#my-custom-id`) - - Fallback: If file path, opens the file, otherwise, tries to find the headline title in the current file. - ## Autocompletion - By default, `omnifunc` is provided in `org` files that autocompletes these types: - - Tags - - Todo keywords - - Common drawer properties and values (`:PROPERTIES:`, `:CATEGORY:`, `:END:`, etc.) - - Planning keywords (`DEADLINE`, `SCHEDULED`, `CLOSED`) - - Orgfile special keywords (`#+TITLE`, `#+BEGIN_SRC`, `#+ARCHIVE`, etc.) - - Hyperlinks (`* - headlines`, `# - headlines with CUSTOM_ID property`, `headlines matching title`) - For [nvim-cmp](https://github.com/hrsh7th/nvim-cmp), add `orgmode` to list of sources: -< +This will trigger `org_meta_return` if there is no content after the cursor +position (either at the end of line or has just trailing spaces). Just note +that this option always tries to use `meta_return`, which also adds new +headlines automatically if you are on the headline line, which can give +undesired results. -lua -require'cmp'.setup({ - sources = { - { name = 'orgmode' } - } -}) -> - For [completion.nvim](https://github.com/nvim-lua/completion-nvim), just add `omni` mode to chain complete list and add additional keyword chars: -< -lua -vim.g.completion_chain_complete_list = { - org = { - { mode = 'omni'}, - }, -} -vim.cmd[[autocmd FileType org setlocal iskeyword+=:,#,+]] -> - Note that autocompletion is context aware, which means that - for example tags autocompletion will kick in only when cursor is at the end of headline. - Example (`|` marks the cursor): -< +Global mappings *orgmode-Global-mappings* -org -* TODO Some task :| -> - Or todo keywords only at the beginning of the headline: -< +There are only 2 global mappings that are accessible from everywhere. -org -** | -> - Or hyperlinks after double square bracket: -< -org -Some content [[| -> - ## Abbreviations - `org` buffers have access to two abbreviations: - - `:today:` - expands to today's date (example: `<2021-06-29 Tue>`) - - `:itoday:` - expands to an inactive version of today's date (example: `[2021-06-29 Tue]`) - - `:now:` - expands to today's date and current time (example: `<2021-06-29 Tue 15:32>`) - - `:inow:` - expands to inactive version of today's date and current time (example: `[2021-06-29 Tue 15:32]`) - ## Formatting - Formatting is done via `gq` mapping, which uses `formatexpr` under the hood (see `:help formatexpr` for more info). - For example, to re-format whole document, you can do `gggqG`. `gg` goes to first line in current file, `gq` starts the format motion, - and `G` goes to last line in file to make it format the whole thing. To format a single line, do `gqgq`, or to format selection, - select the lines you want to format and just do `gq`. - Currently, these things are formatted: - - Tags are aligned according to the `org_tags_column` setting - - Tables are formatted (see [Tables](#Tables) for more info) - - Clock entries total time is recalculated (see [Recalculating totals](#recalculating-totals) in [Clocking](#Clocking) section) - ## User interface - ### Colors - Most of the highlight groups are linked to treesitter highlights where applicable (see `:h treesitter-highlight`). - The following highlight groups are used: - - `@org.headline.level1`: Headline at level 1 - linked to `Title` - - `@org.headline.level2`: Headline at level 2 - linked to `Constant` - - `@org.headline.level3`: Headline at level 3 - linked to `Identifier` - - `@org.headline.level4`: Headline at level 4 - linked to `Statement` - - `@org.headline.level5`: Headline at level 5 - linked to `PreProc` - - `@org.headline.level6`: Headline at level 6 - linked to `Type` - - `@org.headline.level7`: Headline at level 7 - linked to `Special` - - `@org.headline.level8`: Headline at level 8 - linked to `String` - - `@org.priority.highest`: Highest priority marker - linked to `@comment.error` - - `@org.priority.high`: High priority marker - Not linked to anything, defaults to normal text - - `@org.priority.default`: Default priority marker - Not linked to anything, defaults to normal text - - `@org.priority.low`: Lowest priority marker - Not linked to anything, defaults to normal text - - `@org.priority.lowest`: Lowest priority marker - Not linked to anything, defaults to normal text - - `@org.timestamp.active`: An active timestamp - linked to `@keyword` - - `@org.timestamp.inactive`: An inactive timestamp - linked to `@comment` - - `@org.keyword.todo`: TODO keywords color - Parsed from `Error` (see note below) - - `@org.keyword.done`: DONE keywords color - Parsed from `DiffAdd` (see note below) - - `@org.bullet`: A normal bullet under a header item - linked to `@markup.list` - - `@org.properties`: Property drawer start/end delimiters - linked to `@property` - - `@org.drawer`: Drawer start/end delimiters - linked to `@property` - - `@org.tag`: A tag for a headline item, shown on the righthand side like `:foo:` - linked to `@tag.attribute` - - `@org.plan`: `SCHEDULED`, `DEADLINE`, `CLOSED`, etc. keywords - linked to `Constant` - - `@org.comment`: A comment block - linked to `@comment` - - `@org.latex_env`: LaTeX block - linked to `@markup.environment` - - `@org.directive`: Blocks starting with `#+` - linked to `@comment` - - `@org.checkbox`: The default checkbox highlight, including square brackets - linked to `@markup.list.unchecked` - - `@org.checkbox.halfchecked`: A checkbox status (marker between `[]`) checked with `[-]` - linked to `@markup.list.unchecked` - - `@org.checkbox.checked`: A checkbox status (marker between `[]`) checked with either `[x]` or `[X]` - linked to `@markup.list.checked` - - `@org.bold`: **bold** text - linked to `@markup.strong`, - - `@org.bold.delimiter`: bold text delimiter `*` - linked to `@markup.strong`, - - `@org.italic`: _italic_ text - linked to `@markup.italic`, - - `@org.italic.delimiter`: italic text delimiter `/` - linked to `@markup.italic`, - - `@org.strikethrough`: ~strikethrough~ text - linked to `@markup.strikethrough`, - - `@org.strikethrough.delimiter`: strikethrough text delimiter `+` - linked to `@markup.strikethrough`, - - `@org.underline`: underline text - linked to `@markup.underline`, - - `@org.underline.delimiter`: underline text delimiter `_` - linked to `@markup.underline`, - - `@org.code`: `code` text - linked to `@markup.raw`, - - `@org.code.delimiter`: code text delimiter `~` - linked to `@markup.raw`, - - `@org.verbatim`: `verbatim` text - linked to `@markup.raw`, - - `@org.verbatim.delimiter`: verbatim text delimiter `=` - linked to `@markup.raw`, - - `@org.hyperlink`: [link](link) text - linked to `@markup.link.url`, - - `@org.latex`: Inline latex - linked to `@markup.math`, - - `@org.table.delimiter` - `|` and `-` delimiters in tables - linked to `@punctuation.special`, - - `@org.table.heading` - Table headings - linked to `@markup.heading`, - - `@org.edit_src` - The highlight for the source content in an _Org_ buffer while it is being edited in an edit special buffer - linked to `Visual`, - - `@org.agenda.deadline`: A item deadline in the agenda view - Parsed from `Error` (see note below) - - `@org.agenda.scheduled`: A scheduled item in the agenda view - Parsed from `DiffAdd` (see note dbelow) - - `@org.agenda.scheduled_past`: A item past its scheduled date in the agenda view - Parsed from `WarningMsg` (see note below) - - `@org.agenda.day`: Highlight for all days in Agenda view - linked to `Statement` - - `@org.agenda.today`: Highlight for today in Agenda view - linked to `@org.bold` - - `@org.agenda.weekend`: Highlight for weekend days in Agenda view - linked to `@org.bold` - Note: - Colors used for todo keywords and agenda states (deadline, schedule ok, schedule warning) - are parsed from the current colorscheme from several highlight groups (Error, WarningMsg, DiffAdd, etc.). - #### Overriding colors - All colors can be overridden by either setting new values or linking to another highlight group: -< +org_agenda *orgmode-org_agenda* -lua -vim.api.nvim_create_autocmd('ColorScheme', { - pattern = '*', - callback = function() - -- Define own colors - vim.api.nvim_set_hl(0, '@org.agenda.deadline', { fg = '#FFAAAA' }) - vim.api.nvim_set_hl(0, '@org.agenda.scheduled', { fg = '#AAFFAA' }) - -- Link to another highlight group - vim.api.nvim_set_hl(0, '@org.agenda.scheduled_past', { link = 'Statement' }) - end -}) -> - Or in Vimscript: -< +- Mapped to: `oa` -vim -autocmd ColorScheme * call s:setup_org_colors() - -function! s:setup_org_colors() abort - " Define own colors - hi @org.agenda.deadline guifg=#FFAAAA - hi @org.agenda.scheduled guifg=#AAFFAA - " Link to another highlight group - hi link @org.agenda.scheduled_past Statement -endfunction -> - For adding/changing TODO keyword colors see [org-todo-keyword-faces](#org_todo_keyword_faces) - ### Menu - The menu is used when selecting further actions in `agenda`, `capture` and `export`. Here is an example of the menu you see when opening `agenda`: -< +Opens up agenda prompt. --------------------------------------------------------------------------------- -PRESS KEY FOR AN AGENDA COMMAND *orgmode-press_key_for_an_agenda_command* - -a Agenda for current week or day -t List of all TODO entries -m Match a TAGS/PROP/TODO query -M Like m, but only for TODO entries -s Search for keywords -q Quit -> - Users have the option to change the appearance of this menu. To do this, you need to add a handler in the UI configuration section: -< -lua -require("orgmode").setup({ - ui = { - menu = { - handler = function(data) - -- your handler here, for example: - local options = {} - local options_by_label = {} -> - for _, item in ipairs(data.items) do - -- Only MenuOption has `key` - -- Also we don't need `Quit` option because we can close the menu with ESC - if item.key and item.label:lower() ~= "quit" then - table.insert(options, item.label) - options_by_label[item.label] = item - end - end - local handler = function(choice) - if not choice then - return - end - local option = options_by_label[choice] - if option.action then - option.action() - end - end - vim.ui.select(options, { - propmt = data.propmt, - }, handler) - end, - }, -< +org_capture *orgmode-org_capture* -}, -}) -> - When the menu is called, the handler receives a table `data` with the following fields as input: - - `title` (`string`) — menu title - - `items` (`table`) — array containing `MenuItem` (see below) - - `prompt` (`string`) — prompt text used to prompt a keystroke - Each menu item `MenuItem` is one of two types: `MenuOption` and `MenuSeparator`. - `MenuOption` is a table containing the following fields: - - `label` (`string`) — description of the action - - `key` (`string`) — key that will be processed when the keys are pressed in the menu - - `action` (`function` _optional_) — handler that will be called when the `key` is pressed in the menu. - `MenuSeparator` is a table containing the following fields: - - `icon` (`string` _optional_) — character used as separator. The default character is `-` - - `length` (`number` _optional_) — number of repetitions of the separator character. The default length is 80 - In order for the menu to work as expected, the handler must call `action` from `MenuItem`. - ### Folds - In Neovim 0.10+, folds are colored with the same highlight as when they are expanded. - This is enabled by default to be in line with how Emacs work. - To use the old way of highlighting folds with `Folded` highlight group, add this to config: -< +- Mapped to: `oc` -lua -require('orgmode').setup({ - ui = { - folds = { - colored = false - } - } -}) -> - ## Advanced search - Part of [Advanced search](https://orgmode.org/worg/org-tutorials/advanced-searching.html) functionality - is implemented. - To leverage advanced search, open up agenda prompt (default `oa`), and select `m` or `M`(todos only) option. - What is supported: - - Operators: `|`, `&`, `+` and `-` (examples: `COMPUTER+URGENT`, `COMPUTER|URGENT`, `+COMPUTER-URGENT`, `COMPUTER|WORK+EMAIL`) - - Search by property with basic arithmetic operators (`<`, `<=`, `=`, `>`, `>=`, `<>`) (examples: `CATEGORY="mycategory"`, `CUSTOM_ID=my_custom_id`, `AGE<10`, `ITEMS>=5`) - - Search by todo keyword (example: `COMPUTER+URGENT/TODO|NEXT`) - Few examples: - - Search all with tag `COMPUTER` **or** `WORK` and `EMAIL`: `COMPUTER|WORK+EMAIL`. `And` always have precedence over `or`. - Workaround to use first `or` is to write it like this: `COMPUTER+EMAIL|WORK+EMAIL` - - Search all with keyword `TODO`, tag `URGENT` and property `AGE` bigger than 10: `URGENT+AGE>10/TODO` - - Search all with keyword `DONE` or `DELEGATED`, tag `COMPUTER` and property `AGE` not equal to 10: `COMPUTER+AGE<>10/DONE|DELEGATED` - - Search all without keyword `DONE`, tag `URGENT` but without tag `COMPUTER` and property `CATEGORY` equal to `mywork`: `URGENT-COMPUTER+CATEGORY=mywork/-DONE` - ## Notifications (experimental) - There is an experimental support for agenda tasks notifications. Related [issue #49](https://github.com/nvim-orgmode/orgmode/issues/49). - Linux/MacOS has support for notifications via: - - System notification app (notify-send/terminal-notifier) (See below for setup) - - As part of Neovim running instance in floating window - Windows support only notifications in running Neovim instance. Any help on this topic is appreciated. - Default configuration (detailed description below): -< +Opens up capture prompt. -lua -require('orgmode').setup({ - notifications = { - enabled = false, - cron_enabled = true, - repeater_reminder_time = false, - deadline_warning_reminder_time = false, - reminder_time = 10, - deadline_reminder = true, - scheduled_reminder = true, - notifier = function(tasks) - local result = {} - for _, task in ipairs(tasks) do - require('orgmode.utils').concat(result, { - string.format('# %s (%s)', task.category, task.humanized_duration), - string.format('%s %s %s', string.rep('*', task.level), task.todo, task.title), - string.format('%s: <%s>', task.type, task.time:to_string()) - }) - end -> - if not vim.tbl_isempty(result) then - require('orgmode.notifications.notification_popup'):new({ content = result }) - end - end, - cron_notifier = function(tasks) - for _, task in ipairs(tasks) do - local title = string.format('%s (%s)', task.category, task.humanized_duration) - local subtitle = string.format('%s %s %s', string.rep('*', task.level), task.todo, task.title) - local date = string.format('%s: %s', task.type, task.time:to_string()) - -- Linux - if vim.fn.executable('notify-send') == 1 then - vim.loop.spawn('notify-send', { args = { string.format('%s\n%s\n%s', title, subtitle, date) }}) - end - -- MacOS - if vim.fn.executable('terminal-notifier') == 1 then - vim.loop.spawn('terminal-notifier', { args = { '-title', title, '-subtitle', subtitle, '-message', date }}) - end - end - end -< +These live under `mappings.global` and can be overridden like this: -}, -}) -> - Options description: - - `enabled` (boolean) - Enable notifications inside Neovim. Not needed for cron notifications. Default: `false` - - `cron_enabled` (boolean) - Enable notifications via cron. Requires additional setup, see [Cron](#cron) section. Default: `true` - - `repeater_reminder_time` (boolean|number|number[]) - Number of minutes before the repeater time to send notifications.
- For example, if now is `2021-07-15 15:30`, and there's a todo item with date `<2021-07-01 15:30 +1w>`, notification will be sent if value of this setting is `0`.
- If this configuration has a value of `{1, 5, 10}`, this means that notification will be sent on `2021-07-15 15:20`, `2021-07-15 15:25` and `2021-07-15 15:29`.
- Default value: `false`, which is disabled. - - `deadline_warning_reminder_time` (boolean|number|number[]) - Number of minutes before the warning time to send notifications.
- For example, if now is `2021-07-15 12:30`, and there's a todo item with date `<2021-07-15 18:30 -6h>`, notification will be sent.
- If this configuration has a value of `{1, 5, 10}`, this means that notification will be sent on `2021-07-15 12:20`, `2021-07-15 12:25` and `2021-07-15 12:29`.
- Default value: `0`, which means that it will send notification only on exact warning time - - `reminder_time` (boolean|number|number[]) - Number of minutes before the time to send notifications.
- For example, if now is `2021-07-15 12:30`, and there's a todo item with date `<2021-07-15 12:40>`, notification will be sent.
- If this configuration has a value of `{1, 5, 10}`, this means that notification will be sent on `2021-07-15 12:20`, `2021-07-15 12:25` and `2021-07-15 12:29`.
- This reminder also applies to both repeater and warning time if the time is matching. So with the example above, both `2021-07-15 12:20 +1w` and `2021-07-15 12:20 -3h` will trigger notification.
will trigger notification.
- Default value: `10`, which means that it will send notification 10 minutes before the time. - - `deadline_reminder` (boolean) - Should notifications be sent for DEADLINE dates. Default: `true` - - `scheduled_reminder` (boolean) - Should notifications be sent for SCHEDULED dates. Default: `true` - - `notifier` (function) - function for sending notification inside Neovim. Accepts array of tasks (see below) and shows floating window with notifications. - - `cron_notifier` (function) - function for sending notification via cron. Accepts array of tasks (see below) and triggers external program to send notifications. - **Tasks**
- Notifier functions accepts `tasks` parameter which is an array of this type: +>lua + require('orgmode').setup({ + org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, + org_default_notes_file = '~/Dropbox/org/refile.org', + mappings = { + global = { + org_agenda = 'gA', + org_capture = 'gC' + } + } + }) < -lua -{ - file = string, -- (Path to org file containing this task. Example: /home/myhome/orgfiles/todos.org) - todo = string, -- (Todo keyword on the task. Example value: TODO) - title = string, -- (Content of the headline without the todo keyword and tag. Example: Submit papers) - level = number, -- (Headline level (number of asterisks). Example: 1) - category = string, -- (file name where this task lives. With example file above, this would be: todos), - priority = string, -- (priority on the task. Example: A) - tags = string[], -- (array of tags applied to the headline. Example: {'WORK', 'OFFICE'}) - original_time = Date, -- (Date object (see Date object (lua/orgmode/objects/date.lua) for details) containing original time of the task (with adjustments and everything)) - time = Date, -- (Date object (see Date object (lua/orgmode/objects/date.lua) for details) time that matched the reminder configuration (with applied adjustments)) - reminder_type = string, -- (Type of the date that matched reminder settings. Can be one of these: repeater, warning or time), - minutes = number, -- (Number of minutes before the task) - humanized_duration = string, -- (Humanized duration until the task. Examples: in 10 min., in 5 hr, in 3 hr and 10 min.) - type = string, -- (Date type. Can be one of these: DEADLINE or SCHEDULED), - range = table -- (Start and end line of the headline subtree. Example: { start_line = 2, end_line = 5 }) -} -> - ### Cron - In order to trigger notifications via cron, job needs to be added to the crontab.
- This is currently possible only on Linux and MacOS, since I don't know how would this be done on Windows. Any help on this topic is appreciated.
- This works by starting the headless Neovim instance, running one off function inside orgmode, and quitting the Neovim. - First try to see if you can run this command: -< +If you want to use multiple mappings for same thing, pass array of mappings: -nvim --headless -c 'lua require("orgmode").cron()' -> - If it exits without errors, you are ready! - Here's maximum simplified **Linux** example (Tested on Manjaro/Arch/Ubuntu), but least optimized: - Run this to open crontab: -< +>lua + require('orgmode').setup({ + org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, + org_default_notes_file = '~/Dropbox/org/refile.org', + mappings = { + global = { + org_agenda = {'gA', 'oa'}, + org_capture = {'gC', 'oc'} + } + } + }) +< + + +Agenda mappings *orgmode-Agenda-mappings* + +Mappings used in agenda view window. + + +org_agenda_later *orgmode-org_agenda_later* + +- Mapped to: `f` + +Go to next agenda span. + + +org_agenda_earlier *orgmode-org_agenda_earlier* + +- Mapped to: `b` + +Go to previous agenda span. + + +org_agenda_goto_today *orgmode-org_agenda_goto_today* + +- Mapped to: `.` + +Go to span with for today. + + +org_agenda_day_view *orgmode-org_agenda_day_view* + +- Mapped to: `vd` + +Show agenda day view. + + +org_agenda_week_view *orgmode-org_agenda_week_view* + +- Mapped to: `vw` + +Show agenda week view. + + +org_agenda_month_view *orgmode-org_agenda_month_view* + +- Mapped to: `vm` + +Show agenda month view. + + +org_agenda_year_view *orgmode-org_agenda_year_view* + +- Mapped to: `vy` + +Show agenda year view. + + +org_agenda_quit *orgmode-org_agenda_quit* + +- Mapped to: `q` + +Close agenda. + + +org_agenda_switch_to *orgmode-org_agenda_switch_to* + +- Mapped to: `` + +Open selected agenda item in the same buffer. + + +org_agenda_goto *orgmode-org_agenda_goto* + +- Mapped to: `{''}` + +Open selected agenda item in split window. + + +org_agenda_goto_date *orgmode-org_agenda_goto_date* + +- Mapped to: `J` + +Open calendar that allows selecting date to jump to. + + +org_agenda_redo *orgmode-org_agenda_redo* + +- Mapped to: `r` + +Reload all org files and refresh current agenda view. + + +org_agenda_todo *orgmode-org_agenda_todo* + +- Mapped to: `t` + +Change `TODO` state of an item in both agenda and original Org file. + + +org_agenda_clock_in *orgmode-org_agenda_clock_in* + +- Mapped to: `I` + +Clock in item under cursor. See |orgmode-clocking| for more details. + + +org_agenda_clock_out *orgmode-org_agenda_clock_out* + +- Mapped to: `O` + +Clock out currently active clock item. See |orgmode-clocking| for more details. + + +org_agenda_clock_cancel *orgmode-org_agenda_clock_cancel* + +- Mapped to: `X` + +Cancel clock on currently active clock item. See |orgmode-clocking| for more +details. + + +org_agenda_clock_goto *orgmode-org_agenda_clock_goto* + +- Mapped to: `oxj` + +Jump to currently clocked in headline. See |orgmode-clocking| for more details. + + +org_agenda_clockreport_mode *orgmode-org_agenda_clockreport_mode* + +- Mapped to: `R` + +Show clock report at the end of the agenda for current agenda time range See +|orgmode-clocking| for more details. + + +org_agenda_priority *orgmode-org_agenda_priority* + +- Mapped to: `o,` + +Choose the priority of a headline item. + + +org_agenda_priority_up *orgmode-org_agenda_priority_up* + +- Mapped to: `+` + +Increase the priority of a headline item. + + +org_agenda_priority_down *orgmode-org_agenda_priority_down* + +- Mapped to: `-` + +Decrease the priority of a headline item. + + +org_agenda_archive *orgmode-org_agenda_archive* + +- Mapped to: `o$` + +Archive headline item to archive location. + + +org_agenda_toggle_archive_tag *orgmode-org_agenda_toggle_archive_tag* + +- Mapped to: `oA` + +Toggle "ARCHIVE" tag of a headline item. + + +org_agenda_set_tags *orgmode-org_agenda_set_tags* + +- Mapped to: `ot` + +Set tags on current headline item. + + +org_agenda_deadline *orgmode-org_agenda_deadline* + +- Mapped to: `oid` + +Insert/Update deadline date on current headline item. + + +org_agenda_schedule *orgmode-org_agenda_schedule* + +- Mapped to: `ois` + +Insert/Update scheduled date on current headline item. + + +org_agenda_refile *orgmode-org_agenda_refile* + +- Mapped to: `or` + +Refile current headline to a destination org-file. Same as |orgmode-org_refile| +but from agenda view. + + +org_agenda_add_note *orgmode-org_agenda_add_note* + +- Mapped to: `ona` + +Add note to the current headline + + +org_agenda_filter *orgmode-org_agenda_filter* + +- Mapped to: `/` + +Open prompt that allows filtering current agenda view by category, tags and +title (vim regex, see `:help vim.regex()`) Example: + +Having `todos.org` file with headlines that have tags `mytag` or `myothertag`, +and some of them have `check` in content, this search: `todos+mytag/check/` +Returns all headlines that are in `todos.org` file, that have `mytag` tag, and +have `check` in headline title. Note that regex is case sensitive by default. +Use vim regex flag `\c` to make it case insensitive. See `:help vim.regex()` +and `:help /magic`. Pressing `` in filter prompt autocompletes categories +and tags. + + +org_agenda_show_help *orgmode-org_agenda_show_help* + +- Mapped to: `g?` + +Show help popup with mappings + +These mappings live under `mappings.agenda`, and can be changed like this: + +>lua + require('orgmode').setup({ + org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, + org_default_notes_file = '~/Dropbox/org/refile.org', + mappings = { + agenda = { + org_agenda_later = '>', + org_agenda_earlier = '<', + org_agenda_goto_today = {'.', 'T'} + } + } + }) +< + + +Capture mappings *orgmode-Capture-mappings* + +Mappings used in capture window. + + +org_capture_finalize *orgmode-org_capture_finalize* + +- Mapped to: `` + +Save current capture content to `org_default_notes_file` and close capture +window. + + +org_capture_refile *orgmode-org_capture_refile* + +- Mapped to: `or` + +Refile capture content to specific destination. + + +org_capture_kill *orgmode-org_capture_kill* + +- Mapped to: `ok` + +Close capture window without saving anything. + + +org_capture_show_help *orgmode-org_capture_show_help* + +- Mapped to: `g?` + +Show help popup with mappings. + +These mappings live under `mappings.capture`, and can be changed like this: + +>lua + require('orgmode').setup({ + org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, + org_default_notes_file = '~/Dropbox/org/refile.org', + mappings = { + capture = { + org_capture_finalize = 'w', + org_capture_refile = 'R', + org_capture_kill = 'Q' + } + } + }) +< + + +Note mappings *orgmode-Note-mappings* + +Mappings used in closing note window. + + +org_note_finalize *orgmode-org_note_finalize* + +- Mapped to: `` + +Save note window content as closing note for a headline. Ignores first comment +(if exists). + + +org_note_kill *orgmode-org_note_kill* + +- Mapped to: `ok` + +Close note window without saving anything. + +>lua + require('orgmode').setup({ + org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, + org_default_notes_file = '~/Dropbox/org/refile.org', + mappings = { + note = { + org_note_finalize = 'w', + org_note_kill = 'Q' + } + } + }) +< + + +Org mappings *orgmode-Org-mappings* + +Mappings for `org` files. + + +org_refile *orgmode-org_refile* + +- Mapped to: `or` + +Refile current headline, including its subtree, to a destination org-file. This +file must be one of the files specified for the `org_agenda_files` setting. A +target headline in the destination file can be specified with +`destination.org/`. If there are multiple headlines with the same +name in the destination file, the first occurence will be used. + + +org_timestamp_up *orgmode-org_timestamp_up* + +- Mapped to: `` + +Increase date part under under cursor. Accepts count: (Example: `5`) `|` +in examples references cursor position. + +- Year - Example date: `<202|1-10-01 Fri 10:30>` becomes + `<202|2-10-01 Sat 10:30>` +- Month - Example date: `<2021-1|0-01 Fri 10:30>` becomes + `<2022-1|1-01 Mon 10:30>` +- Day - Example date: `<2021-10-0|1 Fri 10:30>` becomes + `<2022-10-0|2 Sat 10:30>`. Same thing happens when cursor is on day + name. +- Hour - Example date: `<2021-10-01 Fri 1|0:30>` becomes + `<2022-10-02 Sat 1|1:30>`. +- Minute - Example date: `<2021-10-01 Fri 10:3|0>` becomes + `<2022-10-02 Sat 11:3|5>`. See |orgmode-org_timestamproundingminutes| for steps configuration. +- Repeater/Delay range (`h->d->w->m->y`) - Example date: + `<2021-10-01 Fri 10:30 +1|w>` becomes `<2021-10-01 Fri 10:30 +1|m>` +- Active/Inactive state - (`<` to `[` and vice versa) - Example date: + `|<2021-10-01 Fri 10:30>` becomes `|[2021-10-01 Fri 10:30]` + + +org_timestamp_down *orgmode-org_timestamp_down* + +- Mapped to: `` + +Decrease date part under under cursor. Same as |orgmode-org_timestampup|, just +opposite direction. + + +org_timestamp_up_day *orgmode-org_timestamp_up_day* + +- Mapped to: `` + +Increase date under cursor by 1 or "count" day(s) (Example count: `5`). + + +org_timestamp_down_day *orgmode-org_timestamp_down_day* + +- Mapped to: `` + +Decrease date under cursor by 1 or "count" day(s) (Example count: `5`). + + +org_change_date *orgmode-org_change_date* + +- Mapped to: `cid` + +Change date under cursor. Opens calendar to select new date. + + +org_toggle_timestamp_type *orgmode-org_toggle_timestamp_type* + +- Mapped to: `od!` + +Switches the timestamp under the cursor between inactive and active. + + +org_priority *orgmode-org_priority* + +- Mapped to: `o,` + +Choose the priority of a headline item. + + +org_priority_up *orgmode-org_priority_up* + +- Mapped to: `ciR` + +Increase the priority of a headline item. + + +org_priority_down *orgmode-org_priority_down* + +- Mapped to: `cir` + +Decrease the priority of a headline item. + + +org_todo *orgmode-org_todo* + +- Mapped to: `cit` + +Cycle todo keyword forward on current headline or open fast access to TODO +states prompt (see |orgmode-org_todokeywords|) if it's enabled. + + +org_todo_prev *orgmode-org_todo_prev* + +- Mapped to: `ciT` + +Cycle todo keyword backward on current headline. + + +org_toggle_checkbox *orgmode-org_toggle_checkbox* + +- Mapped to: `` + +Toggle current line checkbox state. + + +org_toggle_heading *orgmode-org_toggle_heading* + +- Mapped to: `o*` + +Toggle current line to headline and vice versa. Checkboxes will turn into TODO +headlines. + + +org_insert_link *orgmode-org_insert_link* + +- Mapped to: `oli` + +Insert a hyperlink at cursor position. When the cursor is on a hyperlink, edit +that hyperlink. If there are any links stored with |orgmode-org_storelink|, +pressing `` to autocomplete the input will show list of all stored links +to select. Links generated with ID are properly expanded to valid links after +selection. + + +org_store_link *orgmode-org_store_link* + +- Mapped to: `ols` + +Generate a link to the closest headline. If |orgmode-org_idlinktoorguseid| is +`true`, it appends the `ID` property to the headline, and generates link with +that id to be inserted via |orgmode-org_insertlink|. When +|orgmode-org_idlinktoorguseid| is `false`, it generates the standard +file::*headline link (example: `file:/path/to/my/todos.org::*My headline`) + + +org_open_at_point *orgmode-org_open_at_point* + +- Mapped to: `oo` + +Open hyperlink or date under cursor. When date is under the cursor, open the +agenda for that day. + + +org_edit_special *orgmode-org_edit_special* + +- Mapped to: `o'` + +Open a source block for editing in a temporary buffer of the associated +`filetype`. This is useful for editing text with language servers attached, +etc. When the buffer is closed, the text of the underlying source block in the +original Org file is updated. 📝 NOTE: if the Org file that the source block +comes from is edited before the special edit buffer is closed, the edits will +not be applied. The special edit buffer contents can be recovered from +:messages output + + +org_add_note *orgmode-org_add_note* + +- Mapped to: `ona` + +Add note to the current headline. + + +org_cycle *orgmode-org_cycle* + +- Mapped to: `` + +Cycle folding for current headline. + + +org_global_cycle *orgmode-org_global_cycle* + +- Mapped to: `` + +Cycle global folding. + + +org_archive_subtree *orgmode-org_archive_subtree* + +- Mapped to: `o$` + +Archive current headline to archive location. + + +org_set_tags_command *orgmode-org_set_tags_command* + +- Mapped to: `ot` + +Set tags on current headline. + + +org_toggle_archive_tag *orgmode-org_toggle_archive_tag* + +- Mapped to: `oA` + +Toggle "ARCHIVE" tag on current headline. + + +org_do_promote *orgmode-org_do_promote* + +- Mapped to: `<<` + +Promote headline. + + +org_do_demote *orgmode-org_do_demote* + +- Mapped to: `>>` + +Demote headline. + + +org_promote_subtree *orgmode-org_promote_subtree* + +- Mapped to: `s` + +Demote subtree. + + +org_meta_return *orgmode-org_meta_return* + +- Mapped to: `` + +Add headline, list item or checkbox below, depending on current line. + + +org_insert_heading_respect_content*orgmode-org_insert_heading_respect_content* + +- Mapped to: `oih` + +Add headline after current headline + it's content with same level. + + +org_insert_todo_heading *orgmode-org_insert_todo_heading* + +- Mapped to: `oiT` + +Add TODO headline right after the current headline. + + +org_insert_todo_heading_respect_content*orgmode-org_insert_todo_heading_respect_content* + +- Mapped to: `oit` + +Add TODO headliner after current headline + it's content. + + +org_move_subtree_up *orgmode-org_move_subtree_up* + +- Mapped to: `oK` + +Move current headline + it's content up by one headline. + + +org_move_subtree_down *orgmode-org_move_subtree_down* + +- Mapped to: `oJ` + +Move current headline + it's content down by one headline. + + +org_export *orgmode-org_export* + +- Mapped to: `oe` + +Open export options. **NOTE**: Exports are handled via `emacs` and `pandoc`. +This means that `emacs` and/or `pandoc` must be in `$PATH`. see +|orgmode-org_customexports| if you want to add your own export options. + + +org_next_visible_heading *orgmode-org_next_visible_heading* + +- Mapped to: `}` + +Go to next heading (any level). + + +org_previous_visible_heading *orgmode-org_previous_visible_heading* + +- Mapped to: `{` + +Go to previous heading (any level). + + +org_forward_heading_same_level *orgmode-org_forward_heading_same_level* + +- Mapped to: `]]` + +Go to next heading on same level. Doesn't go outside of parent. + + +org_backward_heading_same_level *orgmode-org_backward_heading_same_level* + +- Mapped to: `[[` + +Go to previous heading on same level. Doesn't go outside of parent. + + +outline_up_heading *orgmode-outline_up_heading* + +- Mapped to: `g{` + +Go to parent heading. + + +org_deadline *orgmode-org_deadline* + +- Mapped to: `oid` + +Insert/Update deadline date. + + +org_schedule *orgmode-org_schedule* + +- Mapped to: `ois` + +Insert/Update scheduled date. + + +org_time_stamp *orgmode-org_time_stamp* + +- Mapped to: `oi.` + +Insert/Update date under cursor. + + +org_time_stamp_inactive *orgmode-org_time_stamp_inactive* + +- Mapped to: `oi!` + +Insert/Update inactive date under cursor. + + +org_clock_in *orgmode-org_clock_in* + +- Mapped to: `oxi` + +Clock in headline under cursor. See |orgmode-clocking| for more details. + + +org_clock_out *orgmode-org_clock_out* + +- Mapped to: `oxo` + +Clock out headline under cursor. See |orgmode-clocking| for more details. + + +org_clock_cancel *orgmode-org_clock_cancel* + +- Mapped to: `oxq` + +Cancel currently active clock on current headline. See |orgmode-clocking| for +more details. + + +org_clock_goto *orgmode-org_clock_goto* + +- Mapped to: `oxj` + +Jump to currently clocked in headline. See |orgmode-clocking| for more details. + + +org_set_effort *orgmode-org_set_effort* + +- Mapped to: `oxe` + +Set effort estimate property on for current headline. See |orgmode-clocking| +for more details. + + +org_babel_tangle *orgmode-org_babel_tangle* + +- Mapped to: `obt` + +Tangle current file. See |orgmode-extract-source-code-(tangle)| for more +details. + + +org_show_help *orgmode-org_show_help* + +- Mapped to: `g?` + +Show help popup with mappings + +These mappings live under `mappings.org`, and can be changed like this: + +>lua + require('orgmode').setup({ + org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, + org_default_notes_file = '~/Dropbox/org/refile.org', + mappings = { + org = { + org_timestamp_up = '+', + org_timestamp_down = '-' + } + } + }) +< + + +Edit Src *orgmode-Edit-Src* + +Mappings applied when editing a `SRC` block content via `org_edit_special`. + + +org_edit_src_abort *orgmode-org_edit_src_abort* + +- Mapped to: `ok` + +Abort changes made to temporary buffer created from the content of a `SRC` +block, see above. + + +org_edit_src_save *orgmode-org_edit_src_save* + +- Mapped to: `ow` + +Apply changes from the special buffer to the source Org buffer. + + +org_edit_src_save_exit *orgmode-org_edit_src_save_exit* + +- Mapped to: `'` + +Apply changes from the special buffer to the source Org buffer and close the +edit special window. -crontab -e -> - Then add this (Ensure path to `nvim` is correct): + +org_edit_src_show_help *orgmode-org_edit_src_show_help* + +- Mapped to: `g?` + +Show help within the temporary buffer used to edit the content of a `SRC` +block. + + +Text objects *orgmode-Text-objects* + +Operator mappings for `org` files. Example: Pressing `vir` select everything +from current heading and all child. `inner` means that it doesn't select the +stars, where `around` selects `inner` + `stars`. See this issue comment + for +visual preview. + +📝 NOTE: Some mappings can clash with other plugin mappings, like +gitsigns.nvim which also has `ih` +operator mapping. + + +inner_heading *orgmode-inner_heading* + +- Mapped to: `ih` + +Select inner heading with content. + + +around_heading *orgmode-around_heading* + +- Mapped to: `ah` + +Select around heading with content. + + +inner_subtree *orgmode-inner_subtree* + +- Mapped to: `ir` + +Select whole inner subtree. + + +around_subtree *orgmode-around_subtree* + +- Mapped to: `ar` + +Select around whole subtree. + + +inner_heading_from_root *orgmode-inner_heading_from_root* + +- Mapped to: `Oh` (big letter `o`) + +select everything from first level heading to the current heading. + + +around_heading_from_root *orgmode-around_heading_from_root* + +- Mapped to: `OH` (big letter `o`) + +select around everything from first level heading to the current heading. + + +inner_subtree_from_root *orgmode-inner_subtree_from_root* + +- Mapped to: `Or` (big letter `o`) + +select everything from first level subtree to the current subtree. + + +around_subtree_from_root *orgmode-around_subtree_from_root* + +- Mapped to: `OR` (big letter `o`) + +select around everything from first level subtree to the current subtree. + +These mappings live under `mappings.text_objects`, and can be changed like +this: + +>lua + require('orgmode').setup({ + org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'}, + org_default_notes_file = '~/Dropbox/org/refile.org', + mappings = { + text_objects = { + inner_heading = 'ic', + } + } + }) +< + + +markup text objects* *orgmode-markup-text-objects** + +Mappings to select inner/outer markup entries. For example, having `This is +*bold*`, and if cursor is in middle of `*bold*`, doing `ci*` changes only inner +text, and doing `ca*` changes outer text. These are supported: `*`, `_`, `/`, +`+`, `~`, `=` These cannot be changed. + + +Dot repeat *orgmode-Dot-repeat* + +To make all mappings dot repeatable, install vim-repeat + plugin. + + +FEATURES *orgmode-configuration-features* + + +Autocompletion *orgmode-Autocompletion* + +By default, `omnifunc` is provided in `org` files that autocompletes these +types: + +- Tags +- Todo keywords +- Common drawer properties and values (`:PROPERTIES:`, `:CATEGORY:`, `:END:`, etc.) +- Planning keywords (`DEADLINE`, `SCHEDULED`, `CLOSED`) +- Orgfile special keywords (`#+TITLE`, `#+BEGIN_SRC`, `#+ARCHIVE`, etc.) +- Hyperlinks (`* - headlines`, `# - headlines with CUSTOM_ID property`, `headlines matching title`) + +Autocompletion is context aware, which means that for example tags +autocompletion will kick in only when cursor is at the end of headline. Example +(`|` marks the cursor): + +>org + ** TODO Some task :| +< + +Or todo keywords only at the beginning of the headline: + +>org + *** | +< + +Or hyperlinks after double square bracket: + +>org + Some content [[| +< + +To use an autocompletion plugin, check Completion plugins +<./plugins.org::#completion-plugins> + + +Clocking *orgmode-Clocking* + +There is partial support for Clocking work time +. + +Supported actions: + + +Clock in *orgmode-Clock-in* + +Org file mapping: =oxi= Agenda view mapping: `I=\\ Start the clock by +adding or updating the =:LOGBOOK:` drawer. Note that this clocks out any +currently active clock. Also, agenda/todo/search view highlights item that is +clocked in. + + +CLOCK OUT + +Org file mapping: =oxo= Agenda view mapping: `O=\\ Clock out the entry +and update the =:LOGBOOK:` drawer, and also add a total tracked time. Note that +in agenda view pressing `O` anywhere clocks the currently active entry, while +in org file cursor must be in the headline subtree. + + +CLOCK CANCEL + +Org file mapping: =oxq= Agenda view mapping: =X= Cancel the currently +active clock. This just removes the entry added by clock in from `:LOGBOOK:` +drawer. Note that in agenda view pressing `X` anywhere cancels clock on the +currently active entry, while in org file cursor must be in the headline +subtree. + + +CLOCK GOTO + +Org file mapping: `oxj` Agenda view mapping: `oxj` Jump to +currently clocked in headline in the current window. + + +SET EFFORT + +- Org file mapping: `oxe` +- Agenda view mapping: `oxe` + +Add/Update an Effort estimate property for the current headline. + + +CLOCK REPORT TABLE + +Agenda view mapping: `R` + +Show the clocking report for the current agenda time range. Headlines from +table can be jumped to via `/` (underlined). Note that this is visible +only in Agenda view, since it's the only view that have a time range. +Todo/Search views are not supported. + + +AUTOMATIC UPDATES OF TOTALS + +When updating closed logbook dates that have a total at the right (`example: +==> 1:05`), updating any of the dates via +|orgmode-org_timestampup|/|orgmode-org_timestampdown| automatically +recalculates this value. + + +RECALCULATING TOTALS + +Org file mapping: `gq` (Note: This is Vim's built in mapping that calls +`formatexpr`, see `:help gq`) + +If you changed any of the dates in closed logbook entry, and want to +recalculate the total, select the line and press `gq`, or if you want to do it +in normal mode, just do `gqgq`. + + +STATUSLINE FUNCTION + +Function: `v:lua.orgmode.statusline()` + +Show the currently clocked in headline (if any), with total clocked time / +effort estimate (if set). + +>vim + set statusline=%{v:lua.orgmode.statusline()} +< + + +Formatting *orgmode-Formatting* + +Formatting is done via `gq` mapping, which uses `formatexpr` under the hood +(see `:help formatexpr` for more info). For example, to re-format whole +document, you can do `gggqG`. `gg` goes to first line in current file, `gq` +starts the format motion, and `G` goes to last line in file to make it format +the whole thing. To format a single line, do `gqgq`, or to format selection, +select the lines you want to format and just do `gq`. + +Currently, these things are formatted: + +- Tags are aligned according to the `org_tags_column` setting +- Tables are formatted (see |orgmode-tables| for more info) +- Clock entries total time is recalculated (see + |orgmode-recalculating-totals| in + |orgmode-clocking| section) + + +Hyperlinks *orgmode-Hyperlinks* + +The format for links is either `[[LINK]]` or `[[LINK][DESCRIPTION]]`. If a +description is provided, the actual link is concealed in favor of the +description. + +Hyperlink types supported: + +- URL (`http://`, `https://`) +- File (starts with `file:`. Example: `file:/home/user/.config/nvim/init.lua`) Optionally, target can be specified: + - Headline - It needs to start with `*` (Example: `file:/home/user/org/file.org::*Specific Headline`) + - Custom id - It needs to start with `#` (Example: `file:/home/user/org/file.org::#my-custom-id`) + - Line number - It needs to be a number (Example: `file:/home/user/org/file.org::235`) +- Headline title target within the same file (starts with `*`) (Example: `*Specific headline`) +- Headline with `CUSTOM_ID` property within the same file (starts with `#`) (Example: `#my-custom-id`) +- Fallback: If file path, opens the file, otherwise, tries to find the headline title in the current file. + + +Notifications *orgmode-Notifications* + +There is an experimental support for agenda tasks notifications. Related issue +#49 . + +Linux/MacOS has support for notifications via: + +- System notification app (notify-send/terminal-notifier) (See below for setup) +- As part of Neovim running instance in floating window + +Windows support only notifications in running Neovim instance. Any help on this +topic is appreciated. + +Default configuration (detailed description below): + +>lua + require('orgmode').setup({ + notifications = { + enabled = false, + cron_enabled = true, + repeater_reminder_time = false, + deadline_warning_reminder_time = false, + reminder_time = 10, + deadline_reminder = true, + scheduled_reminder = true, + notifier = function(tasks) + local result = {} + for _, task in ipairs(tasks) do + require('orgmode.utils').concat(result, { + string.format('# %s (%s)', task.category, task.humanized_duration), + string.format('%s %s %s', string.rep('*', task.level), task.todo, task.title), + string.format('%s: <%s>', task.type, task.time:to_string()) + }) + end + + if not vim.tbl_isempty(result) then + require('orgmode.notifications.notification_popup'):new({ content = result }) + end + end, + cron_notifier = function(tasks) + for _, task in ipairs(tasks) do + local title = string.format('%s (%s)', task.category, task.humanized_duration) + local subtitle = string.format('%s %s %s', string.rep('*', task.level), task.todo, task.title) + local date = string.format('%s: %s', task.type, task.time:to_string()) + + -- Linux + if vim.fn.executable('notify-send') == 1 then + vim.loop.spawn('notify-send', { args = { string.format('%s\n%s\n%s', title, subtitle, date) }}) + end + + -- MacOS + if vim.fn.executable('terminal-notifier') == 1 then + vim.loop.spawn('terminal-notifier', { args = { '-title', title, '-subtitle', subtitle, '-message', date }}) + end + end + end + }, + }) +< + +Options description: + +- `enabled` + - Type: `boolean` + - Default: `false` + Enable notifications inside Neovim. Not needed for cron notifications. +- `cron_enabled` + - Type: `boolean` + - Default: `true` + Enable notifications via cron. Requires additional setup, see |orgmode-cron| section. +- `repeater_reminder_time` (boolean|number|number[]) - + - Type: `boolean|number|number[]` + - Default: `false` + Number of minutes before the repeater time to send notifications. + For example, if now is `2021-07-15 15:30`, and there's a todo item + with date `<2021-07-01 15:30 +1w>`, notification will be sent if value + of this setting is `0`. + If this configuration has a value of `{1, 5, 10}`, this means that + notification will be sent on `2021-07-15 15:20`, `2021-07-15 15:25` + and `2021-07-15 15:29`. + `false` means disabled (default). +- `deadline_warning_reminder_time` + - Type: `boolean|number|number[]` + - Default: `0` + Number of minutes before the warning time to send notifications. + For example, if now is `2021-07-15 12:30`, and there's a todo item + with date `<2021-07-15 18:30 -6h>`, notification will be sent. + If this configuration has a value of `{1, 5, 10}`, this means that + notification will be sent on `2021-07-15 12:20`, `2021-07-15 12:25` + and `2021-07-15 12:29`. + `0` (Default) means that it will send notification only on exact warning time +- `reminder_time` + - Type: `boolean|number|number[]` + - Default: `10` + Number of minutes before the time to send notifications. + For example, if now is `2021-07-15 12:30`, and there's a todo item + with date `<2021-07-15 12:40>`, notification will be sent. + If this configuration has a value of `{1, 5, 10}`, this means that + notification will be sent on `2021-07-15 12:20`, `2021-07-15 12:25` + and `2021-07-15 12:29`. + This reminder also applies to both repeater and warning time if the + time is matching. So with the example above, both + `2021-07-15 12:20 +1w` and `2021-07-15 12:20 -3h` will trigger + notification. will trigger notification. + `10` (default) means that it will send notification 10 minutes before the time. +- `deadline_reminder` + - Type: `boolean` + - Default: `true` + Should notifications be sent for DEADLINE dates. +- `scheduled_reminder` + - Type: `boolean` + - Default: `true` + Should notifications be sent for SCHEDULED dates. +- `notifier` + - Type: `fun(tasks: table[])` + - Default: `nil` + Function for sending notification inside Neovim. Accepts array of tasks (see below) and shows floating window with notifications. +- `cron_notifier` + - Type: `fun(tasks: table[])` + - Default: `nil` + Function for sending notification via cron. Accepts array of tasks (see below) and triggers external program to send notifications. + +***Tasks** + +Notifier functions accepts `tasks` parameter which is an array of this type: + +>lua + { + file = string, -- (Path to org file containing this task. Example: /home/myhome/orgfiles/todos.org) + todo = string, -- (Todo keyword on the task. Example value: TODO) + title = string, -- (Content of the headline without the todo keyword and tag. Example: Submit papers) + level = number, -- (Headline level (number of asterisks). Example: 1) + category = string, -- (file name where this task lives. With example file above, this would be: todos), + priority = string, -- (priority on the task. Example: A) + tags = string[], -- (array of tags applied to the headline. Example: {'WORK', 'OFFICE'}) + original_time = Date, -- (Date object (see [Date object](lua/orgmode/objects/date.lua) for details) containing original time of the task (with adjustments and everything)) + time = Date, -- (Date object (see [Date object](lua/orgmode/objects/date.lua) for details) time that matched the reminder configuration (with applied adjustments)) + reminder_type = string, -- (Type of the date that matched reminder settings. Can be one of these: repeater, warning or time), + minutes = number, -- (Number of minutes before the task) + humanized_duration = string, -- (Humanized duration until the task. Examples: in 10 min., in 5 hr, in 3 hr and 10 min.) + type = string, -- (Date type. Can be one of these: DEADLINE or SCHEDULED), + range = table -- (Start and end line of the headline subtree. Example: { start_line = 2, end_line = 5 }) + } +< + + +Cron *orgmode-Cron* + +In order to trigger notifications via cron, job needs to be added to the +crontab. This is currently possible only on Linux and MacOS, since I don't know +how would this be done on Windows. Any help on this topic is appreciated. This +works by starting the headless Neovim instance, running one off function inside +orgmode, and quitting the Neovim. + +First try to see if you can run this command: + +>example + nvim --headless -c 'lua require("orgmode").cron()' +< + +If it exits without errors, you are ready! + +Here's maximum simplified **Linux** example (Tested on Manjaro/Arch/Ubuntu), +but least optimized: + +Run this to open crontab: + +>example + crontab -e +< + +Then add this (Ensure path to `nvim` is correct): + +>crontab + ** * * * * DISPLAY=:0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus /usr/local/bin/nvim --headless -c 'lua require("orgmode").cron()' +< + +More optimized version would be to create a lua file that has only necessary +plugins loaded: + +>lua + -- ~/.config/nvim/lua/partials/org_cron.lua + + -- If you are using lazy.vim do this: + local orgmode = vim.fn.stdpath('data') .. '/lazy/orgmode' + vim.opt.runtimepath:append(orgmode) + -- If you are using Packer or any other package manager that uses built-in package manager, do this: + vim.cmd('packadd orgmode') + + -- Run the orgmode cron + require('orgmode').cron({ + org_agenda_files = '~/orgmode/*', + org_default_notes_file = '~/orgmode/notes.org', + notifications = { + reminder_time = {0, 5, 10}, + }, + }) +< + +And update cron job to this: + +>crontab + ** * * * * DISPLAY=:0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus /usr/local/bin/nvim -u NONE --noplugin --headless -c 'lua require("partials.org_cron")' < -crontab -* * * * * DISPLAY=:0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus /usr/local/bin/nvim --headless -c 'lua require("orgmode").cron()' -> - More optimized version would be to create a lua file that has only necessary plugins loaded: +This option is most optimized because it doesn't load plugins and your init.vim +For **MacOS**, things should be very similar, but I wasn't able to test it. Any +help on this is appreciated. + + +Tables *orgmode-Tables* + +Tables can be formatted via built in `formatexpr` (see `:help gq`) + +For example, having this content: + +>org + * TODO My headline + DEADLINE: <2022-05-22 Sun> + + |Header 1|Header 2 + |- + | col 1| col 2| +< + +And going to line `4` and pressing `gqgq`, it will format it to this: + +>org + * TODO My headline + DEADLINE: <2022-05-22 Sun> + + | Header 1 | Header 2 | + |----------+----------| + | col 1 | col 2 | < -lua --- ~/.config/nvim/lua/partials/org_cron.lua - --- If you are using lazy.vim do this: -local orgmode = vim.fn.stdpath('data') .. '/lazy/orgmode' -vim.opt.runtimepath:append(orgmode) --- If you are using Packer or any other package manager that uses built-in package manager, do this: -vim.cmd('packadd orgmode') - --- Run the orgmode cron -require('orgmode').cron({ - org_agenda_files = '~/orgmode/*', - org_default_notes_file = '~/orgmode/notes.org', - notifications = { - reminder_time = {0, 5, 10}, - }, -}) -> - And update cron job to this: + +Advanced search *orgmode-Advanced-search* + +Part of Advanced search + functionality +is implemented. + +To leverage advanced search, open up agenda prompt (default `oa`), and +select `m` or =M=(todos only) option. + +What is supported: + +- Operators: `|`, `&`, `+` and `-` (examples: `COMPUTER+URGENT`, + `COMPUTER|URGENT`, `+COMPUTER-URGENT`, `COMPUTER|WORK+EMAIL`) +- Search by property with basic arithmetic operators (`<`, `<=`, `=`, `>=`, `>=`, `<>`) (examples: `CATEGORY="mycategory"`, `CUSTOM_ID=my_custom_id`, `AGE<10`, `ITEMS>=5`) +- Search by todo keyword (example: `COMPUTER+URGENT/TODO|NEXT`) + +Few examples: + +- Search all with tag `COMPUTER` **or** `WORK` and `EMAIL`: + `COMPUTER|WORK+EMAIL`. `And` always have precedence over `or`. + Workaround to use first `or` is to write it like this: + `COMPUTER+EMAIL|WORK+EMAIL` +- Search all with keyword `TODO`, tag `URGENT` and property `AGE` bigger + than 10: `URGENT+AGE>10/TODO` +- Search all with keyword `DONE` or `DELEGATED`, tag `COMPUTER` and + property `AGE` not equal to 10: `COMPUTER+AGE<>10/DONE|DELEGATED` +- Search all without keyword `DONE`, tag `URGENT` but without tag + `COMPUTER` and property `CATEGORY` equal to `mywork`: + `URGENT-COMPUTER+CATEGORY=mywork/-DONE` + + +Tangle *orgmode-Tangle* + +Extract source code (tangle) + +There is basic support for extracting source code with `tangle` and `noweb`. +(Orgmode link: Extracting source code +) These options are +supported: + +1. Setting `header-args` on multiple levels: + +1. Configuration (|orgmode-org_babeldefaultheaderargs|) + + +2. File level property (`#+property: header-args :tangle yes`) + + +3. Headline level property + +>org + * Headline + :PROPERTIES: + :header-args: :tangle yes + :END: < -crontab -* * * * * DISPLAY=:0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus /usr/local/bin/nvim -u NONE --noplugin --headless -c 'lua require("partials.org_cron")' -> - This option is most optimized because it doesn't load plugins and your init.vim - For **MacOS**, things should be very similar, but I wasn't able to test it. Any help on this is appreciated. - ## Clocking - There is partial support for [Clocking work time](https://orgmode.org/manual/Clocking-Work-Time.html).
- Supported actions: - ##### Clock in - Org file mapping: `oxi`
- Agenda view mapping: `I`
- Start the clock by adding or updating the `:LOGBOOK:` drawer. Note that this clocks out any currently active clock.
- Also, agenda/todo/search view highlights item that is clocked in. - ##### Clock out - Org file mapping: `oxo`
- Agenda view mapping: `O`
- Clock out the entry and update the `:LOGBOOK:` drawer, and also add a total tracked time.
- Note that in agenda view pressing `O` anywhere clocks the currently active entry, while in org file cursor must be in the headline subtree. - ##### Clock cancel - Org file mapping: `oxq`
- Agenda view mapping: `X`
- Cancel the currently active clock. This just removes the entry added by clock in from `:LOGBOOK:` drawer.
- Note that in agenda view pressing `X` anywhere cancels clock on the currently active entry, while in org file cursor must be in the headline subtree. - ##### Clock goto - Org file mapping: `oxj`
- Agenda view mapping: `oxj`
- Jump to currently clocked in headline in the current window - ##### Set effort - Org file mapping: `oxe`
- Agenda view mapping: `oxe`
- Add/Update an Effort estimate property for the current headline - ##### Clock report table - Agenda view mapping: `R`
- Show the clocking report for the current agenda time range. Headlines from table can be jumped to via `/` (underlined)
- Note that this is visible only in Agenda view, since it's the only view that have a time range. Todo/Search views are not supported. - ##### Automatic updates of totals - When updating closed logbook dates that have a total at the right (example: `=> 1:05`), updating any of the dates via - [org_timestamp_up](#org_timestamp_up)/[org_timestamp_down](#org_timestamp_down) automatically recalculates this value. - ##### Recalculating totals - Org file mapping: `gq` (Note: This is Vim's built in mapping that calls `formatexpr`, see `:help gq`)
- If you changed any of the dates in closed logbook entry, and want to recalculate the total, select the line and press `gq`, or - if you want to do it in normal mode, just do `gqgq`. - ##### Statusline function - Function: `v:lua.orgmode.statusline()`
- Show the currently clocked in headline (if any), with total clocked time / effort estimate (if set). + +4. Block level argument `#+begin_src lua :tangle yes` + + + + +2. Tangling all blocks with these options: + +1. `:tangle no` - Do not tangle +2. `:tangle yes` - Tangle to same filename as current org file, with +different extension (If org file is `~/org/todo.org` and block is `#+block_src lua`, tangles to `/org/todo.lua`) +3. `:tangle path` - Tangle to given filename. It can be absolute (`:tangle /path/to/file.ext`) or relative to current file (either `:tangle ./file.ext` or `:tangle file.ext`) + + +3. Basic `:noweb` syntax (See Noweb Reference Syntax +): + +1. `:noweb no` - Do not expand any references +2. `:noweb yes` - Expand references via `#+name` directive on block. +See example below. +3. `:noweb tangle` - Same as `:noweb yes` + + + +Example: Having this file in `~/org/todos.org` + +Block below will pick up reference from the 2nd block name + +`#+begin_src lua :tangle yes :noweb yes` `<>` `print('Headline +1')` `#+end_src` + +`#+name: headline2block` `#+begin_src lua :tangle yes` `print('Headline 2')` +`#+end_src` `#+end_src` + +Running |orgmode-org_babeltangle| will create file `~/org/todos.lua` with this +content: + +`#+begin_src lua` `print('Headline 2')` `print('Headline 1')` == +`print('Headline 2')` `#+end_src` + +To extract blocks to specific file, you can set file level property with +default path, and maybe exclude 2nd block to not be repeated: + +`#+property: header-args :tangle ./my_tangled_file.lua` + +`#+begin_src lua :noweb yes` `<>` `print('Headline 1')` +`#+end_src` + +Here we disable tangling, so only first block will give results with the noweb +`#+name: headline2block` `#+begin_src lua :tangle no` `print('Headline 2')` +`#+end_src` + +Running |orgmode-org_babeltangle| will create file `~/org/my_tangled_file.lua` +with this content: + +`#+begin_src lua` `print('Headline 2')` `print('Headline 1')` `#+end_src` + + +USER INTERFACE *orgmode-configuration-user-interface* + + +Colors *orgmode-Colors* + +Most of the highlight groups are linked to treesitter highlights where +applicable (see |treesitter-highlight|). + +The following highlight groups are used: + +- `@org.headline.level1`: Headline at level 1 - linked to `Title` +- `@org.headline.level2`: Headline at level 2 - linked to `Constant` +- `@org.headline.level3`: Headline at level 3 - linked to `Identifier` +- `@org.headline.level4`: Headline at level 4 - linked to `Statement` +- `@org.headline.level5`: Headline at level 5 - linked to `PreProc` +- `@org.headline.level6`: Headline at level 6 - linked to `Type` +- `@org.headline.level7`: Headline at level 7 - linked to `Special` +- `@org.headline.level8`: Headline at level 8 - linked to `String` +- `@org.priority.highest`: Highest priority marker - linked to `@comment.error` +- `@org.priority.high`: High priority marker - Not linked to anything, defaults to normal text +- `@org.priority.default`: Default priority marker - Not linked to anything, defaults to normal text +- `@org.priority.low`: Lowest priority marker - Not linked to anything, defaults to normal text +- `@org.priority.lowest`: Lowest priority marker - Not linked to anything, defaults to normal text +- `@org.timestamp.active`: An active timestamp - linked to `@keyword` +- `@org.timestamp.inactive`: An inactive timestamp - linked to `@comment` +- `@org.keyword.todo`: TODO keywords color - Parsed from `Error` (see note below) +- `@org.keyword.done`: DONE keywords color - Parsed from `DiffAdd` (see note below) +- `@org.bullet`: A normal bullet under a header item - linked to `@markup.list` +- `@org.properties`: Property drawer start/end delimiters - linked to `@property` +- `@org.drawer`: Drawer start/end delimiters - linked to `@property` +- `@org.tag`: A tag for a headline item, shown on the righthand side like `:foo:` - linked to `@tag.attribute` +- `@org.plan`: `SCHEDULED`, `DEADLINE`, `CLOSED`, etc. keywords - linked to `Constant` +- `@org.comment`: A comment block - linked to `@comment` +- `@org.latex_env`: LaTeX block - linked to `@markup.environment` +- `@org.directive`: Blocks starting with `#+` - linked to `@comment` +- `@org.checkbox`: The default checkbox highlight, including square brackets - linked to `@markup.list.unchecked` +- `@org.checkbox.halfchecked`: A checkbox status (marker between `[]`) checked with `[-]` - linked to `@markup.list.unchecked` +- `@org.checkbox.checked`: A checkbox status (marker between `[]`) checked with either `[x]` or `[X]` - linked to `@markup.list.checked` +- `@org.bold`: **bold** text - linked to `@markup.strong`, +- `@org.bold.delimiter`: bold text delimiter `*` - linked to `@markup.strong`, +- `@org.italic`: _italic_ text - linked to `@markup.italic`, +- `@org.italic.delimiter`: italic text delimiter `/` - linked to `@markup.italic`, +- `@org.strikethrough`: `strikethrough` text - linked to `@markup.strikethrough`, +- `@org.strikethrough.delimiter`: strikethrough text delimiter `+` - linked to `@markup.strikethrough`, +- `@org.underline`: underline text - linked to `@markup.underline`, +- `@org.underline.delimiter`: underline text delimiter `_` - linked to `@markup.underline`, +- `@org.code`: `code` text - linked to `@markup.raw`, +- `@org.code.delimiter`: code text delimiter `~` - linked to `@markup.raw`, +- `@org.verbatim`: `verbatim` text - linked to `@markup.raw`, +- `@org.verbatim.delimiter`: verbatim text delimiter `=` - linked to `@markup.raw`, +- `@org.hyperlink`: `[[file:link]]` text - linked to `@markup.link.url`, +- `@org.latex`: Inline latex - linked to `@markup.math`, +- `@org.table.delimiter` - `|` and `-` delimiters in tables - linked to `@punctuation.special`, +- `@org.table.heading` - Table headings - linked to `@markup.heading`, +- `@org.edit_src` - The highlight for the source content in an _Org_ buffer while it is being edited in an edit special buffer - linked to `Visual`, +- `@org.agenda.deadline`: A item deadline in the agenda view - Parsed from `Error` (see note below) +- `@org.agenda.scheduled`: A scheduled item in the agenda view - Parsed from `DiffAdd` (see note below) +- `@org.agenda.scheduled_past`: A item past its scheduled date in the agenda view - Parsed from `WarningMsg` (see note below) +- `@org.agenda.day`: Highlight for all days in Agenda view - linked to `Statement` +- `@org.agenda.today`: Highlight for today in Agenda view - linked to `@org.bold` +- `@org.agenda.weekend`: Highlight for weekend days in Agenda view - linked to `@org.bold` + +📝 NOTE: Colors used for todo keywords and agenda states (deadline, schedule +ok, schedule warning) are parsed from the current colorscheme from several +highlight groups (Error, WarningMsg, DiffAdd, etc.). + + +Overriding colors *orgmode-Overriding-colors* + +All colors can be overridden by either setting new values or linking to another +highlight group: + +>lua + vim.api.nvim_create_autocmd('ColorScheme', { + pattern = '*', + callback = function() + -- Define own colors + vim.api.nvim_set_hl(0, '@org.agenda.deadline', { fg = '#FFAAAA' }) + vim.api.nvim_set_hl(0, '@org.agenda.scheduled', { fg = '#AAFFAA' }) + -- Link to another highlight group + vim.api.nvim_set_hl(0, '@org.agenda.scheduled_past', { link = 'Statement' }) + end + }) < -vim -set statusline=%{v:lua.orgmode.statusline()} -> - ## Extract source code (tangle) - There is basic support for extracting source code with `tangle` and `noweb` (Orgmode link: [Extracting source code](https://orgmode.org/manual/Extracting-Source-Code.html)). - These options are supported: - 1. Setting `header-args` on multiple levels: - 1. Configuration ([org_babel_default_header_args](#org_babel_default_header_args)) - 2. File level property (`#+property: header-args :tangle yes`) - 3. Headline level property - ```org - * Headline - :PROPERTIES: - :header-args: :tangle yes - :END: - ``` - 4. Block level argument - ```org - #+begin_src lua :tangle yes - print('test') - #+end_src - ``` - 2. Tangling all blocks with these options: - 1. `:tangle no` - Do not tangle - 2. `:tangle yes` - Tangle to same filename as current org file, with different extension (If org file is `~/org/todo.org` and block is `#+block_src lua`, tangles to `/org/todo.lua`) - 3. `:tangle path` - Tangle to given filename. It can be absolute (`:tangle /path/to/file.ext`) or relative to current file (either `:tangle ./file.ext` or `:tangle file.ext`) - 3. Basic `:noweb` syntax (See [Noweb Reference Syntax](https://orgmode.org/manual/Noweb-Reference-Syntax.html)): - 1. `:noweb no` - Do not expand any references - 2. `:noweb yes` - Expand references via `#+name` directive on block. See example below. - 3. `:noweb tangle` - Same as `:noweb yes` - Example: Having this file in `~/org/todos.org` +For adding/changing TODO keyword colors see |orgmode-org-todo-keyword-faces| + + +Menu *orgmode-Menu* + +The menu is used when selecting further actions in `agenda`, `capture` and +`export`. Here is an example of the menu you see when opening `agenda`: + +>example + Press key for an agenda command + ------------------------------- + a Agenda for current week or day + t List of all TODO entries + m Match a TAGS/PROP/TODO query + M Like m, but only for TODO entries + s Search for keywords + q Quit < -org -* Headline 1 - Content - Block below will pick up reference from the 2nd block name - -#+begin_src lua :tangle yes :noweb yes - <> - print('Headline 1') - #+end_src - -* Headline 2 - Content - #+name: headline2block - #+begin_src lua :tangle yes - print('Headline 2') - #+end_src -> - Running [org_babel_tangle](#org_babel_tangle) will create file `~/org/todos.lua` with this content: +Users have the option to change the appearance of this menu. To do this, you +need to add a handler in the UI configuration section: + +>lua + require("orgmode").setup({ + ui = { + menu = { + handler = function(data) + -- your handler here, for example: + local options = {} + local options_by_label = {} + + for _, item in ipairs(data.items) do + -- Only MenuOption has `key` + -- Also we don't need `Quit` option because we can close the menu with ESC + if item.key and item.label:lower() ~= "quit" then + table.insert(options, item.label) + options_by_label[item.label] = item + end + end + + local handler = function(choice) + if not choice then + return + end + + local option = options_by_label[choice] + if option.action then + option.action() + end + end + + vim.ui.select(options, { + propmt = data.propmt, + }, handler) + end, + }, + }, + }) < - lua -print('Headline 2') -print('Headline 1') +When the menu is called, the handler receives a table `data` with the following +fields as input: + +- `title` (`string`) - menu title +- `items` (`table`) - array containing `MenuItem` (see below) +- `prompt` (`string`) - prompt text used to prompt a keystroke + +Each menu item `MenuItem` is one of two types: `MenuOption` and +`MenuSeparator`. + +`MenuOption` is a table containing the following fields: + +- `label` (`string`) - description of the action +- `key` (`string`) - key that will be processed when the keys are + pressed in the menu +- `action` (`function` _optional_) - handler that will be called when + the `key` is pressed in the menu. + +`MenuSeparator` is a table containing the following fields: -print('Headline 2') -> - To extract blocks to specific file, you can set file level property with default path, and maybe exclude 2nd block to not be repeated: +- `icon` (`string` _optional_) - character used as separator. The + default character is `-` +- `length` (`number` _optional_) - number of repetitions of the + separator character. The default length is 80 + +In order for the menu to work as expected, the handler must call `action` from +`MenuItem`. + + +Folds *orgmode-Folds* + +In Neovim 0.10+, folds are colored with the same highlight as when they are +expanded. This is enabled by default to be in line with how Emacs work. + +To use the old way of highlighting folds with `Folded` highlight group, add +this to config: + +>lua + require('orgmode').setup({ + ui = { + folds = { + colored = false + } + } + }) < -org -#+property: header-args :tangle ./my_tangled_file.lua -* Headline 1 - Content - #+begin_src lua :noweb yes - <> - print('Headline 1') - #+end_src - -* Headline 2 - Content - Here we disable tangling, so only first block will give results with the noweb - #+name: headline2block - #+begin_src lua :tangle no - print('Headline 2') - #+end_src -> - Running [org_babel_tangle](#org_babel_tangle) will create file `~/org/my_tangled_file.lua` with this content: + +TROUBLESHOOTING *orgmode-configuration-troubleshooting* + + +Indentation is not working *orgmode-Indentation-is-not-working* + +Make sure you are not overriding indentexpr in Org buffers with nvim-treesitter +indentation + + +I get treesitter/query.lua errors when opening agenda/capture prompt or org files*orgmode-I-get-treesitter/query.lua-errors-when-opening-agenda/capture-prompt-or-org-files* + +Tree-sitter parser might not be installed. Try running `:lua +require('orgmode.config'):reinstall_grammar()` to reinstall it. + + +Dates are not in English *orgmode-Dates-are-not-in-English* + +Dates are generated with Lua native date support, and it reads your current +locale when creating them. + +To use different locale you can add this to your `init.lua`: + +>lua + vim.cmd('language en_US.utf8') < - lua -print('Headline 2') -print('Headline 1') -``` +Just make sure you have `en_US` locale installed on your system. To see what +you have available on the system you can start the command `:language` and +press `` to autocomplete possible options. --------------------------------------------------------------------------------- -CHANGELOG *orgmode-changelog* -To track breaking changes, subscribe to Notice of breaking changes (https://github.com/nvim-orgmode/orgmode/issues/217) issue where those are announced. +Links are not concealed *orgmode-Links-are-not-concealed* -25 FEBRUARY 2024 *orgmode-25_february_2024* +Links are concealed with Vim's conceal feature (see `:help conceal`). To enable +concealing, add this to your `init.lua`: -* Add support for extracting source code Extract source code (tangle) (#extract-source-code-tangle) +>lua + vim.opt.conceallevel = 2 + vim.opt.concealcursor = 'nc' +< -21 JANUARY 2024 *orgmode-21_january_2024* -* Option `org_indent_mode` was deprecated in favor of org_startup_indented (#org_startup_indented). To remove the - warning use `org_startup_indented`. This was introduced to support Virtual Indent more in line with Emacs. +Jumping to file path is not working for paths with forward slash*orgmode-Jumping-to-file-path-is-not-working-for-paths-with-forward-slash* -24 OCTOBER 2021 *orgmode-24_october_2021* +If you are using Windows, paths are by default written with backslashes. To use +forward slashes, you must enable `shellslash` option (see `:help shellslash`). -* Help mapping was changed from `?` to `g?` to avoid conflict with built in backward search. See issue #106 (https://github.com/nvim-orgmode/orgmode/issues/106). +>lua + vim.opt.shellslash = true +< -10 OCTOBER 2021 *orgmode-10_october_2021* +More info on issue #281 + -* Mappings `org_increase_date` and `org_decrease_date` are deprecated in favor of org_timestamp_up (#org_timestamp_up) and org_timestamp_down (#org_timestamp_down). - If you have these mappings in your custom configuration, you will get a warning each time Orgmode is loaded. To remove the warning, rename the configuration properties accordingly. - To return the old functionality where mappings increase only the day, add `org_timestamp_up_day`/`org_timestamp_down_day` to your configuration. +Generated by panvimdoc +vim:tw=78:ts=8:noet:ft=help:norl: