Configuration

This page contains information about all configuration that can be provided to the plugin.

Global settings
Agenda settings
Calendar settings
Tags settings
Mappings
Features
User interface

Global settings

org_agenda_files

Type: string | string[]
Default: ''

Single or multiple paths from where the org files are being read.

Examples:

~/org/*
{'~/Dropbox/org/**/*', '~/orgfiles/*'}

org_default_notes_file

Type: string
Default: ''

Path to a file that will be used as a default target file when refiling.

Example: ~/orgfiles/refile.org

org_todo_keywords

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.

For entries where a fast access key is not set, the first character of the keyword is used as the fast access key.

Examples (Without fast access):

{'TODO', 'NEXT', '|', 'DONE'}
{'TODO', 'WAITING', '|', 'DONE', 'DELEGATED'}

Examples (With fast access):

{'TODO(t)', 'NEXT(n)', '|', 'DONE(d)'}
{'TODO(t)', 'NEXT', '|', 'DONE'} - Same as above. Fast key is derived from first char.

NOTE: Make sure fast access keys do not overlap. If that happens, first entry in list gets it.

org_todo_repeat_to_state

Type: string | nil
Default: nil

Set an entry from org_todo_keywords to use as the "starting" state for repeatable todos.

If provided value does not exist in org_todo_keywords, first entry from that list is used.

win_split_mode

Type: string | function | [string, number]
Default: 'horizontal'

This option determines how to open agenda and capture window.

Available string values:

horizontal - Always split horizontally
vertical - Always split vertically
auto - Determine between horizontal and vertical split depending on the current window size
float - Open in float window that has width of 70% of the screen centered
{'float', 0.9} - Open in float window and provide custom scale (in this case it's 90% of screen size), must be value between 0 and 1

If none of the options above suit your needs, there are 2 other ways to customize this:

Provide a custom command string (see :help <mods>). Few examples:
- Always open in tab: tabnew
- Always open vertically: vsplit
- Always open horizontally with specific height of 20 lines: 20split

Custom function

lua

win_split_mode = function(name)
+  -- Make sure it's not a scratch buffer by passing false as 2nd argument
+  local bufnr = vim.api.nvim_create_buf(false, false)
+  --- Setting buffer name is required
+  vim.api.nvim_buf_set_name(bufnr, name)
+
+  local fill = 0.8
+  local width = math.floor((vim.o.columns * fill))
+  local height = math.floor((vim.o.lines * fill))
+  local row = math.floor((((vim.o.lines - height) / 2) - 1))
+  local col = math.floor(((vim.o.columns - width) / 2))
+
+  vim.api.nvim_open_win(bufnr, true, {
+    relative = "editor",
+    width = width,
+    height = height,
+    row = row,
+    col = col,
+    style = "minimal",
+    border = "rounded"
+  })
+end

win_border

Type: string | string[]
Default: 'single'

Border style for floating windows. Available options:

none - No border (default)
single - A single line box
double - A double line box
rounded - Like "single", but with rounded corners ("╭" etc.)
solid - Adds padding by a single whitespace cell
shadow - A drop shadow effect by blending with the background
{'╔', '═' ,'╗', '║', '╝', '═', '╚', '║' } - Specify border characters in a clock-wise fashion
{'/', '-', '\\', '|' } - If less than eight chars the chars will start repeating

See :help nvim_open_win()

Applies to:

always - calendar pop-up, help pop-up, notification pop-up
win_split_mode is set to float - agenda window , capture window

org_startup_folded

Type: string
Default: 'overview'

How many headings and other foldable items should be shown when an org file is opened. Available options:

overview - Only show top level elements (default)
content - Only show the first two levels
showeverything - Show all elements
inherit - Use the fold level set in Neovim's global foldlevel option

org_todo_keyword_faces

Type: table<string, string>
Default: {}

Custom colors for todo keywords. Available options:

foreground - :foreground hex/colorname. Examples: :foreground #FF0000, :foreground blue
background - :background hex/colorname. Examples: :background #FF0000, :background blue
weight - :weight bold
underline - :underline on
italic - :slant italic

Full configuration example with additional todo keywords and their colors:

lua

require('orgmode').setup({
+  org_todo_keywords = {'TODO', 'WAITING', '|', 'DONE', 'DELEGATED'},
+  org_todo_keyword_faces = {
+    WAITING = ':foreground blue :weight bold',
+    DELEGATED = ':background #FFFFFF :slant italic :underline on',
+    TODO = ':background #000000 :foreground red', -- overrides builtin color for `TODO` keyword
+  }
+})

org_archive_location

Type: string
Default: '%s_archive::'

Destination file for archiving. %s indicates the current file. :: is used as a separator for archiving to headline which is currently not supported. This means that if you do a refile from a file ~/my-orgs/todos.org, your task will be archived in ~/my-orgs/todos.org_archive.

Example value: '~/my-orgs/default-archive-file.org::'

📝 NOTE: This value can be overridden per file basis with a org special keyword #+ARCHIVE.

org_hide_leading_stars

Type: boolean
Default: false

Hide leading stars for headings. Example:

Disabled (default):

org

* TODO First item
+** TODO Second Item
+*** TODO Third item

Enabled:

org

* TODO First item
+ * TODO Second Item
+  * TODO Third item

📝 NOTE: Stars are hidden by applying highlight group that masks them with color that's same as background color. If this highlight group does not suit you, you can apply different highlight group to it:

lua

vim.cmd[[autocmd ColorScheme * hi link @org.leading.stars MyCustomHlGroup]]

To set specific characters instead of using asterisk, check org-bullets.nvim plugin plugin.

org_hide_emphasis_markers

Type: boolean
Default: false

Conceal bold/italic/underline/code/verbatim markers.

Ensure your :h conceallevel is set properly in order for this to function.

org_ellipsis

Type: string
Default: '...'

Marker used to indicate a folded headline.

org_log_done

Type: string|false
Default: time

Possible values:

time - adds CLOSED date when marking headline as done
note - adds CLOSED date as above, and prompts for closing note via capture window. Confirm note with org_note_finalize (Default <C-c>), or ignore providing note via org_note_kill (Default <Leader>ok)
false - Disable any logging

org_log_repeat

Type: string|false
Default: time

Possible values:

time - adds LAST_REPEAT date to properties when marking headline with a repeater date as done
note - adds LAST_REPEAT date as above, and prompts for closing note via capture window. Confirm note with org_note_finalize (Default <C-c>), or ignore providing note via org_note_kill (Default <Leader>ok)
false - Disable logging the LAST_REPEAT date

org_log_into_drawer

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

Type: string|nil
Default: nil

📝 NOTE: This option is experimental

Possible values:

native - Includes whole latex syntax file into the org syntax. It can potentially cause some highlighting issues and slowness.
entities - Highlight latex only in these situations (see Orgmode latex fragments):
- 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

Type: boolean
Default: false

Possible values:

true - Uses Virtual indents to align content visually. The indents are only visual, they are not saved to the file.
false - Do not add any Virtual indentation.

You can toggle Virtual indents on the fly by executing command :Org indent_mode when in a org buffer. This additionally sets the buffer variable vim.b.org_indent_mode to true or false, depending on the current state. Value of this buffer variable is then used to determine behavior of few options below.

org_adapt_indentation

Type: boolean
Default: true

Possible values:

true - Use hard indents for content under headlines. Files will save with indents relative to headlines.
false - Do not add any hard indents. Files will save without indentation relative to headlines.

org_indent_mode_turns_off_org_adapt_indentation

Type: boolean
Default: true

Possible values:

true - Disable org_adapt_indentation by default when org_startup_indented is enabled.
false - Do not disable org_adapt_indentation by default when org_startup_indented is enabled.

org_indent_mode_turns_on_hiding_stars

Type: boolean
Default: true

Possible values:

true - Enable org_hide_leading_stars by default when org_indent_mode is enabled for buffer (vim.b.org_indent_mode = true).
false - Do not modify the value in org_hide_leading_stars by default when org_indent_mode is enabled for buffer (vim.b.org_indent_mode = true).

org_src_window_setup

Type: string | function
Default: '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_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_edit_src_filetype_map

Type: table<string, string>
Default: {}

This filetype map associates the language name from an Org source block with the corresponding Vim filetype, which is then applied to the temporary buffer.

org_custom_exports

Type: table
Default: {}

Add custom export options to the export prompt. Structure:

example

[shortcut:string] = {
+  [label:string] = 'Label in export prompt',
+  [action:function] = function(exporter)
+    return exporter(command:table, target:string, on_success?:function, on_error?:function)
+  end
+}

Breakdown:

shortcut - single char that will be used to select the export. Make sure it doesn't conflict with existing options
action - function that provides exporter function for generating the exports
exporter - function that calls the command provided via job
- command - table (array like) that contains command how to generate the export
- target - target file name that will be generated
- on_success? - function that is triggered when export succeeds (command exit status is 0). Provides table parameter with command output. Optional, defaults to prompt to open target file.
- on_error? - function that is triggered when export fails (command exit status is not 0). Provides table parameter with command output. Optional, defaults to printing output as error.

For example, lets add option to export to rtf format via pandoc:

lua

require('orgmode').setup({
+  org_custom_exports = {
+    f = {
+      label = 'Export to RTF format',
+      action = function(exporter)
+        local current_file = vim.api.nvim_buf_get_name(0)
+        local target = vim.fn.fnamemodify(current_file, ':p:r')..'.rtf'
+        local command = {'pandoc', current_file, '-o', target}
+        local on_success = function(output)
+          print('Success!')
+          vim.api.nvim_echo({{ table.concat(output, '\n') }}, true, {})
+        end
+        local on_error = function(err)
+          print('Error!')
+          vim.api.nvim_echo({{ table.concat(err, '\n'), 'ErrorMsg' }}, true, {})
+        end
+        return exporter(command , target, on_success, on_error)
+      end
+    }
+  }
+})

org_time_stamp_rounding_minutes

Type: number
Default: 5

Number of minutes to increase/decrease when using org_timestamp_up/org_timestamp_down

org_cycle_separator_lines

Type number
Default: 2

Minimum number of empty lines needed at the end of the headline to show a single empty line when headline is folded.

For example, given this structure:

org

* One empty space headline
+  Content
+
+* Two empty space headline
+  Content
+
+
+* Three empty space headline
+  Content
+
+
+
+* Last headline
+  Content

When folded, it will appear like this:

org

* One empty space headline ...
+* Two empty space headline ...
+
+* Three empty space headline ...
+
+* Last headline ...

When value is 0, all empty lines are folded together with headline.

Cannot be negative.

org_blank_before_new_entry

Type: table<string, boolean>
Default: { heading = true, plain_list_item = false }

Determine if blank line should be prepended when:

Adding heading via org_meta_return and org_insert_* mappings
Adding a list item via org_meta_return

org_id_uuid_program

Type: string
Default: uuidgen

External program used to generate uuid's for id module

org_id_ts_format

Type: string
Default: %Y%m%d%H%M%S

Format of the id generated when org_id_method is set to ts.

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 to generate the id
ts - Generate id from current timestamp using format org_id_ts_format
org - Generate a random 12 digit number and prepend org_id_prefix

org_id_prefix

Type: string | nil
Default: nil

Prefix added to the generated id when org_id_method is set to org.

org_id_link_to_org_use_id

Type: boolean
Default: false

If true, generate ID with the Org ID module and append it to the headline as property. More info on org_store_link

org_use_property_inheritance

Type: boolean | string | string[]
Default: false

Determine whether properties of one headline are inherited by sub-headlines.

false - properties only pertain to the file or headline that defines them
true - properties of a headlines also pertain to all its sub-headlines
string[] - only the properties named in the given list are inherited
string - only properties matching the given regex are inherited

Note that for a select few properties, the inheritance behavior is hard-coded within their special applications. See Property Inheritance for details.

org_babel_default_header_args

Type: table<string, string>
Default: { [':tangle'] = 'no', [':noweb'] = no }

Default header args for extracting source code. See Extract source code (tangle) for more details.

calendar_week_start_day

Type: number
Default: 1

Available options:

0 - start week on Sunday
1 - start week on Monday

Determine on which day the week will start in calendar modal (ex: changing the date under cursor)

emacs_config

Type: table
Default: { executable_path = 'emacs', config_path=nil }

Set configuration for your emacs. This is useful for having the emacs export properly pickup your emacs config and plugins. If config_path is not provided, exporter tries to find a configuration file from these locations:

~/.config/emacs/init.el
~/.emacs.d/init.el
~/.emacs.el

If there is no configuration found, it will still process the export.

If it finds a configuration and export attempt fails because of the configuration issue, there will be a prompt to attempt the same export without the configuration file.

Agenda settings

org_deadline_warning_days

Type: number
Default: 14

Number of days during which deadline becomes visible in today's agenda. Example: If Today is 2021-06-10, and we have these tasks:

Task 1 has a deadline date 2021-06-15
Task 2 has a deadline date 2021-06-30
Task 1 is visible in today's agenda
Task 2 is not visible in today's agenda until 2021-06-16

org_agenda_span

Type: string|number
Default: 'week'

possible string values: day, week, month, year Default time span shown when agenda is opened.

org_agenda_start_on_weekday

Type: number
Default: 1

From which day in week (ISO weekday, 1 is Monday) to show the agenda. Applies only to week and number span. If set to false, starts from today

org_agenda_start_day

Type: string
Default: nil

example values: +2d, -1d offset to apply to the agenda start date. Example: If org_agenda_start_on_weekday is false, and org_agenda_start_day is -2d, agenda will always show current week from today - 2 days

org_agenda_custom_commands

Type: table<string, OrgAgendaCustomCommand>
Default: {}

Define custom agenda views that are available through the org_agenda mapping. It is possible to combine multiple agenda types into single view. Available options for each agenda type are explained down below the example:

lua

require('orgmode').setup({
+  org_agenda_files = {'~/org/**/*'},
+  org_agenda_custom_commands = {
+    -- "c" is the shortcut that will be used in the prompt
+    c = {
+      description = 'Combined view', -- Description shown in the prompt for the shortcut
+      types = {
+        {
+          type = 'tags_todo', -- Type can be agenda | tags | tags_todo
+          match = '+PRIORITY="A"', --Same as providing a "Match:" for tags view <leader>oa + m, See: https://orgmode.org/manual/Matching-tags-and-properties.html
+          org_agenda_overriding_header = 'High priority todos',
+          org_agenda_todo_ignore_deadlines = 'far', -- Ignore all deadlines that are too far in future (over org_deadline_warning_days). Possible values: all | near | far | past | future
+        },
+        {
+          type = 'agenda',
+          org_agenda_overriding_header = 'My daily agenda',
+          org_agenda_span = 'day' -- can be any value as org_agenda_span
+        },
+        {
+          type = 'tags',
+          match = 'WORK', --Same as providing a "Match:" for tags view <leader>oa + m, See: https://orgmode.org/manual/Matching-tags-and-properties.html
+          org_agenda_overriding_header = 'My work todos',
+          org_agenda_todo_ignore_scheduled = 'all', -- Ignore all headlines that are scheduled. Possible values: past | future | all
+        },
+        {
+          type = 'agenda',
+          org_agenda_overriding_header = 'Whole week overview',
+          org_agenda_span = 'week', -- 'week' is default, so it's not necessary here, just an example
+          org_agenda_start_on_weekday = 1, -- Start on Monday
+          org_agenda_remove_tags = true -- Do not show tags only for this view
+        },
+      }
+    },
+    p = {
+      description = 'Personal agenda',
+      types = {
+        {
+          type = 'tags_todo',
+          org_agenda_overriding_header = 'My personal todos',
+          org_agenda_category_filter_preset = 'todos', -- Show only headlines from `todos` category. Same value providad as when pressing `/` in the Agenda view
+          org_agenda_sorting_strategy = {'todo-state-up', 'priority-down'} -- See all options available on org_agenda_sorting_strategy
+        },
+        {
+          type = 'agenda',
+          org_agenda_overriding_header = 'Personal projects agenda',
+          org_agenda_files = {'~/my-projects/**/*'}, -- Can define files outside of the default org_agenda_files
+        },
+        {
+          type = 'tags',
+          org_agenda_overriding_header = 'Personal projects notes',
+          org_agenda_files = {'~/my-projects/**/*'},
+          org_agenda_tag_filter_preset = 'NOTES-REFACTOR' -- Show only headlines with NOTES tag that does not have a REFACTOR tag. Same value providad as when pressing `/` in the Agenda view
+        },
+      }
+    }
+  }
+})

These arguments are shared between all of the agenda types:

org_agenda_overriding_header (string) - Override the header of the agenda view
org_agenda_files (string | string[]) - Set custom files to be loaded into this view. In same format as org_agenda_files
org_agenda_tag_filter_preset string - Custom tags filter for the view. Same format as org_agenda_files, but applies only for tags.
org_agenda_category_filter_preset string - Custom category filter for the view. Same format as org_agenda_files, but applies only for categories.
org_agenda_sorting_strategy string[] - List of sorting functions. See org_agenda_sorting_strategy
org_agenda_remove_tags boolean - Remove tags from the view. Default: false

agenda type arguments:

org_agenda_span string|number - Set custom span for the view. In same format as org_agenda_span
org_agenda_start_on_weekday number - Set custom start day for the view. In same format as org_agenda_start_on_weekday
org_agenda_start_day string - Set custom start day offset for the view. In same format as org_agenda_start_day

tags and tags_todo type arguments:

org_agenda_todo_ignore_scheduled('past' | 'future' | 'all' | nil') - Do not show headlines that have scheduled task according to the value. Default: nil
org_agenda_todo_ignore_deadlines('near' | 'far' | 'all' | 'past' | 'future' | nil') - Do not show headlines that have deadline task according to the value. Default: nil
- far - Do not show deadlines that are too far in future (over org_deadline_warning_days)
- near - Do not show deadlines that are too near in future (under org_deadline_warning_days)

org_agenda_hide_empty_blocks

Type: boolean
Default: false

Should custom agenda commands be hidden if they have no entries to show. Does not work for agenda type since it shows days.

org_agenda_sorting_strategy

Type:

table<'agenda' | 'todo' | 'tags', OrgAgendaSortingStrategy[]>

Default:

{ agenda = {'time-up', 'priority-down', 'category-keep'}, todo = {'priority-down', 'category-keep'}, tags = {'priority-down', 'category-keep'}} List of sorting strategies to apply to a given view. Available strategies:

time-up - Sort entries by time of day. Applicable only in agenda view
time-down - Opposite of time-up
priority-down - Sort by priority, from highest to lowest
priority-up - Sort by priority, from lowest to highest
tag-up - Sort by sorted tags string, ascending
tag-down - Sort by sorted tags string, descending
todo-state-up - Sort by todo keyword by position (example: 'TODO, PROGRESS, DONE' has a sort value of 1, 2 and 3), ascending
todo-state-down - Sort by todo keyword, descending
clocked-up - Show clocked in headlines first
clocked-down - Show clocked in headlines last
category-up - Sort by category name, ascending
category-down - Sort by category name, descending
category-keep - Keep default category sorting, as it appears in org-agenda-files

org_agenda_block_separator

Type: string
Default: -

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

Type: boolean
Default: false

Should tags be hidden from all agenda views.

org_agenda_time_grid

Type: { type: ('daily', 'weekly', 'require-timed', 'remove-match', 'remove-range-match')[], times: number[], time_separator: string, time_label: string }

Default:

lua

{
+  type = { 'daily', 'today', 'require-timed' },
+  times = { 800, 1000, 1200, 1400, 1600, 1800, 2000 },
+  time_separator = '┄┄┄┄┄',
+  time_label = '┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄'
+}

Settings for the time grid visible in agenda. To disable showing the time grid altogether, set org_agenda_use_time_grid to false.

type: List of options where all have to apply to show the grid
- daily - Show grid in daily agenda (1 day view)
- weekly - Show grid in any agenda type
- today - Show grid only for today
- require-timed - Show grid only if day has any entries with time specification
- remove-match - Hide grid entries that overlap with the existing time slot taken by an agenda item
- remove-range-match - Hide grid entries that overlap with the existing time range taken by an agenda item
times: List of times (in 24h format) to show on the grid. It should be integer value, example 1030 represents 10:30
time_separator: Value that is showed after the grid time as a separator
time_label: Value that is showed after the time_separator to fill in the place that is usually for the agenda item title

To customize the label for the current time, check org_agenda_current_time_string

org_agenda_use_time_grid

Type: boolean
Default: true

Show time grid in agenda. See org_agenda_time_grid for configuration options.

org_agenda_current_time_string

Type: string
Default: <- now -----------------------------------------------

Label value for the current time in the agenda time grid. See org_agenda_time_grid for time grid configuration or org_agenda_use_time_grid to disable the grid.

org_agenda_show_future_repeats

Type: boolean | number | 'next'
Default: true

How many future repeated tasks to show in agenda. Possible values:

true - Show all future repeats (default)
false - Do not show future repeats
number - Show only given number of future repeats
'next' - Show only the next repeat

org_capture_templates

Type: table<string, table>
Default:

{ t = { description = 'Task', template = '* TODO %?\n %u' } } Templates for capture/refile prompt. Variables:

%f: Prints the file of the buffer capture was called from
%F: Like %f but inserts the full path
%n: Inserts the current $USER
%t: Prints current date (Example: <2021-06-10 Thu>)
%^t: Prompt for current date (Example: <2021-06-10 Thu>)
%^{Name}t: Prompt for current date for given Name (visible in calendar title) (Example: <2021-06-10 Thu>)
%T: Prints current date and time (Example: <2021-06-10 Thu 12:30>)
%^T: Prompt for current date and time (Example: <2021-06-10 Thu 12:30>)
%^{Name}T: Prompt for current date and time for given Name (visible in calendar title) (Example: <2021-06-10 Thu 12:30>)
%u: Prints current date in inactive format (Example: [2021-06-10 Thu])
%^u: Prompt for current date in inactive format (Example: [2021-06-10 Thu])
%^{Name}u: Prompt for current date in inactive format for given Name (visible in calendar title) (Example: [2021-06-10 Thu])
%U: Prints current date and time in inactive format (Example: [2021-06-10 Thu 12:30])
%^U: Prompt for current date and time in inactive format (Example: [2021-06-10 Thu 12:30])
%^{Name}U: Prompt for current date and time in inactive format for given Name (visible in calendar title) (Example: [2021-06-10 Thu 12:30])
%a: File and line number from where capture was initiated (Example: [[file:/home/user/projects/myfile.txt +2]])
%<FORMAT>: Insert current date/time formatted according to lua date 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 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',
+  target = '~/org/todo.org'
+} }

Journal example:

lua

{
+  j = {
+    description = 'Journal',
+    template = '\n*** %<%Y-%m-%d> %<%A>\n**** %U\n\n%?',
+    target = '~/sync/org/journal.org'
+  },
+}

Journal example with dynamic target, i.e. a separate file per month:

lua

{
+  J = {
+    description = 'Journal',
+    template = '\n*** %<%Y-%m-%d> %<%A>\n**** %U\n\n%?',
+    target = '~/sync/org/journal/%<%Y-%m>.org'
+  },
+}

Nested key example:

lua

{
+  e =  'Event',
+  er = {
+    description = 'recurring',
+    template = '** %?\n %T',
+    target = '~/org/calendar.org',
+    headline = 'recurring'
+  },
+  eo = {
+    description = 'one-time',
+    template = '** %?\n %T',
+    target = '~/org/calendar.org',
+    headline = 'one-time'
+  }
+}
+-- or
+{
+  e = {
+    description = 'Event',
+    subtemplates = {
+      r = {
+        description = 'recurring',
+        template = '** %?\n %T',
+        target = '~/org/calendar.org',
+        headline = 'recurring'
+      },
+      o = {
+        description = 'one-time',
+        template = '** %?\n %T',
+        target = '~/org/calendar.org',
+        headline = 'one-time'
+      },
+    },
+  },
+}

Lua expression example:

lua

{
+  j = {
+    description = 'Journal',
+    template = '* %(return vim.fn.getreg "w")',
+    -- get the content of register "w"
+    target = '~/sync/org/journal.org'
+  },
+}

org_agenda_min_height

Type: number
Default: 16

Indicates the minimum height that the agenda window will occupy.

org_priority_highest

Type: string|number
Default: A

Indicates highest priority for a task in the agenda view. Example:

org

* TODO [#A] This task has the highest priority

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

Type: string|number
Default: C

Indicates lowest priority for a task in the agenda view. Example:

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

Type: boolean
Default: false

Hide scheduled entries from agenda if they are in a "DONE" state.

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

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

Adjust behavior of the calendar modal (ex: changing the date under cursor).

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.min_big_step

Type: number
Default: 15

The step size for changing the minutes while the cursor is on the first digit.

calendar.min_small_step

Type: number
Default: same as org_time_stamp_rounding_minutes

The step size for changing the minutes while the cursor is on the second digit.

Tags settings

org_tags_column

Type: number
Default: 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.

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.

org_tags_exclude_from_inheritance

Type: string[]
Default: {}

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

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 <Leader>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',
+  mappings = {
+    disable_all = true
+  }
+})

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',
+  mappings = {
+    global = {
+      org_agenda = false,
+      org_capture = 'gC'
+    },
+  }
+})

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',
+  mappings = {
+    global = {
+      -- providing a string
+      org_agenda = '<D-a>',
+      -- providing a table
+      org_capture = { '<D-c>' }
+    },
+  }
+})

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 = { '<D-c>', 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.

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 which is a normal mode mapping. If you want to have an insert mode mapping there are two options:

If your terminal supports it, map a key like Shift + Enter to the meta return mapping (Recommended):

lua

vim.api.nvim_create_autocmd('FileType', {
+  pattern = 'org',
+  callback = function()
+    vim.keymap.set('i', '<S-CR>', '<cmd>lua require("orgmode").action("org_mappings.meta_return")<CR>', {
+      silent = true,
+      buffer = true,
+    })
+  end,
+})

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: <Leader>oa

Opens up agenda prompt.

org_capture

Mapped to: <Leader>oc

Opens up capture prompt.

These live under mappings.global and can be overridden like this:

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:

lua

require('orgmode').setup({
+  org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'},
+  org_default_notes_file = '~/Dropbox/org/refile.org',
+  mappings = {
+    global = {
+      org_agenda = {'gA', '<Leader>oa'},
+      org_capture = {'gC', '<Leader>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: <CR>

Open selected agenda item in the same buffer.

org_agenda_goto

Mapped to: {'<TAB>'}

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 for more details.

org_agenda_clock_out

Mapped to: O

Clock out currently active clock item. See Clocking for more details.

org_agenda_clock_cancel

Mapped to: X

Cancel clock on currently active clock item. See Clocking for more details.

org_agenda_clock_goto

Mapped to: <Leader>oxj

Jump to currently clocked in headline. See 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 for more details.

org_agenda_priority

Mapped to: <Leader>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: <Leader>o$

Archive headline item to archive location.

org_agenda_toggle_archive_tag

Mapped to: <Leader>oA

Toggle "ARCHIVE" tag of a headline item.

org_agenda_set_tags

Mapped to: <Leader>ot

Set tags on current headline item.

org_agenda_deadline

Mapped to: <Leader>oid

Insert/Update deadline date on current headline item.

org_agenda_schedule

Mapped to: <Leader>ois

Insert/Update scheduled date on current headline item.

org_agenda_refile

Mapped to: <Leader>or

Refile current headline to a destination org-file. Same as org_refile but from agenda view.

org_agenda_add_note

Mapped to: <Leader>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 <TAB> in filter prompt autocompletes categories and tags.

org_agenda_preview

Mapped to: K Preview the agenda item in a floating window. For configuring the floating window, check Agenda section in ui configuration.

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

Mappings used in capture window.

org_capture_finalize

Mapped to: <C-c>

Save current capture content to org_default_notes_file and close capture window.

org_capture_refile

Mapped to: <Leader>or

Refile capture content to specific destination.

org_capture_kill

Mapped to: <Leader>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 = '<Leader>w',
+      org_capture_refile = 'R',
+      org_capture_kill = 'Q'
+    }
+  }
+})

Note mappings

Mappings used in closing note window.

org_note_finalize

Mapped to: <C-c>

Save note window content as closing note for a headline. Ignores first comment (if exists).

org_note_kill

Mapped to: <Leader>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 = '<Leader>w',
+      org_note_kill = 'Q'
+    }
+  }
+})

Org mappings

Mappings for org files.

org_refile

Mapped to: <Leader>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/<headline>. If there are multiple headlines with the same name in the destination file, the first occurence will be used.

org_timestamp_up

Mapped to: <C-a>

Increase date part under under cursor. Accepts count: (Example: 5<C-a>) | 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 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: <C-x>

Decrease date part under under cursor. Same as org_timestamp_up, just opposite direction.

org_timestamp_up_day

Mapped to: <S-UP>

Increase date under cursor by 1 or "count" day(s) (Example count: 5<S-UP>).

org_timestamp_down_day

Mapped to: <S-DOWN>

Decrease date under cursor by 1 or "count" day(s) (Example count: 5<S-UP>).

org_change_date

Mapped to: cid

Change date under cursor. Opens calendar to select new date.

org_toggle_timestamp_type

Mapped to: <Leader>od!

Switches the timestamp under the cursor between inactive and active.

org_priority

Mapped to: <Leader>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) if it's enabled.

org_todo_prev

Mapped to: ciT

Cycle todo keyword backward on current headline.

org_toggle_checkbox

Mapped to: <C-Space>

Toggle current line checkbox state.

org_toggle_heading

Mapped to: <Leader>o*

Toggle current line to headline and vice versa. Checkboxes will turn into TODO headlines.

org_insert_link

Mapped to: <Leader>oli

Insert a hyperlink at cursor position. When the cursor is on a hyperlink, edit that hyperlink. In visual mode, uses selected text as link description. If there are any links stored with org_store_link, pressing <TAB> 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: <Leader>ols

Generate a link to the closest headline. If 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. When 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: <Leader>oo

Open hyperlink or date under cursor. When date is under the cursor, open the agenda for that day.

org_edit_special

Mapped to: <Leader>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

Mapped to: <Leader>ona

Add note to the current headline.

org_cycle

Mapped to: <TAB>

Cycle folding for current headline.

org_global_cycle

Mapped to: <S-TAB>

Cycle global folding.

org_archive_subtree

Mapped to: <Leader>o$

Archive current headline to archive location.

org_set_tags_command

Mapped to: <Leader>ot

Set tags on current headline.

org_toggle_archive_tag

Mapped to: <Leader>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: <s

Promote subtree.

org_demote_subtree

Mapped to: >s

Demote subtree.

org_meta_return

Mapped to: <Leader><CR>

Add headline, list item or checkbox below, depending on current line.

org_insert_heading_respect_content

Mapped to: <Leader>oih

Add headline after current headline + it's content with same level.

org_insert_todo_heading

Mapped to: <Leader>oiT

Add TODO headline right after the current headline.

org_insert_todo_heading_respect_content

Mapped to: <Leader>oit

Add TODO headliner after current headline + it's content.

org_move_subtree_up

Mapped to: <Leader>oK

Move current headline + it's content up by one headline.

org_move_subtree_down

Mapped to: <Leader>oJ

Move current headline + it's content down by one headline.

org_export

Mapped to: <Leader>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 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: <Leader>oid

Insert/Update deadline date.

org_schedule

Mapped to: <Leader>ois

Insert/Update scheduled date.

org_time_stamp

Mapped to: <Leader>oi.

Insert/Update date under cursor.

org_time_stamp_inactive

Mapped to: <Leader>oi!

Insert/Update inactive date under cursor.

org_clock_in

Mapped to: <Leader>oxi

Clock in headline under cursor. See Clocking for more details.

org_clock_out

Mapped to: <Leader>oxo

Clock out headline under cursor. See Clocking for more details.

org_clock_cancel

Mapped to: <Leader>oxq

Cancel currently active clock on current headline. See Clocking for more details.

org_clock_goto

Mapped to: <Leader>oxj

Jump to currently clocked in headline. See Clocking for more details.

org_set_effort

Mapped to: <Leader>oxe

Set effort estimate property on for current headline. See Clocking for more details.

org_babel_tangle

Mapped to: <leader>obt

Tangle current file. See 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:

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: <Leader>ok

Abort changes made to temporary buffer created from the content of a SRC block, see above.

org_edit_src_save

Mapped to: <Leader>ow

Apply changes from the special buffer to the source Org buffer.

org_edit_src_save_exit

Mapped to: <Leader>'

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 for visual preview.

📝 NOTE: Some mappings can clash with other plugin mappings, like 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:

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 plugin.

Features

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

Clocking

There is partial support for Clocking work time.

Supported actions:

Clock in

Org file mapping: =<leader>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: =<leader>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: =<leader>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: <leader>oxj Agenda view mapping: <leader>oxj Jump to currently clocked in headline in the current window.

Set effort

Org file mapping: <leader>oxe
Agenda view mapping: <leader>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 <TAB>/<CR> (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_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).

vim

set statusline=%{v:lua.orgmode.statusline()}

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 for more info)
Clock entries total time is recalculated (see Recalculating totals in Clocking section)

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.
Your own custom type (see below)

Custom hyperlink types

To add your own custom hyperlink type, provide a custom handler to hyperlinks.sources setting. Each handler needs to have a get_name() method that returns a name for the handler. Additionally, follow(link) and autocomplete(link) optional methods are available to open the link and provide the autocompletion. Here's an example of adding a custom "ping" hyperlink type that opens the terminal and pings the provided URL and provides some autocompletion with few predefined URLs:

lua

local LinkPingType = {}
+
+---Unique name for the handler. MUST NOT be one of these: "http", "id", "line_number", "custom_id", "headline"
+---This method is required
+---@return string
+function LinkPingType:get_name()
+  return 'ping'
+end
+
+---This method is in charge of "executing" the link. For "http" links, it would open the browser, for example.
+---In this example, it will open the terminal and ping the value of the link.
+---The value of the link is passed as an argument.
+---For example, if you have a link [[ping:google.com][ping_google]], doing an `org_open_at_point` (<leader>oo by default)
+---anywhere within the square brackets, will call this method with `ping:google.com` as an argument.
+---It's on this method to figure out what to do with the value.
+---If this method returns `true`, it means that the link was successfully followed.
+---If it returns `false`, it means that this handler cannot handle the link, and it will continue to the next source.
+---This method is optional.
+---@param link string - The current value of the link, for example: "ping:google.com"
+---@return boolean - When true, link was handled, when false, continue to the next source
+function LinkPingType:follow(link)
+  if not vim.startswith(link, 'ping:') then
+    return false
+  end
+  -- Get the part after the `ping:` part
+  local url = link:sub(6)
+  -- Open terminal in vertical split and ping the URL
+  vim.cmd('vsplit | term ping ' .. url)
+  return true
+end
+
+---This is an optional method that will provide autocompletion for your link type.
+---This method needs to pre-filter the list of possible completions based on the current value of the link.
+---For example, if this source has `ping:google.com` and `ping:github.com` as possible completions,
+---And the current value of the link is `ping:go`, this method should return `{'ping:google.com'}`.
+---This method is optional.
+---@param link string - The current value of the link, for example: "ping:go"
+---@return string[]
+function LinkPingType:autocomplete(link)
+  local items = {
+    'ping:google.com',
+    'ping:github.com'
+  }
+  return vim.tbl_filter(function(item) return vim.startswith(item, link) end, items)
+end
+
+require('orgmode').setup({
+  hyperlinks = {
+    sources = {
+      LinkPingType,
+      -- Simpler types can be inlined like this:
+      {
+        get_name = function() return 'my_custom_type' end,
+        follow = function(self, link) print('Following link:', link) return true end,
+        autocomplete = function(self, link) return {'my_custom_type:my_custom_link'} end
+      }
+    }
+  }
+})

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
+
+      -- Example: if you use Snacks, you can do something like this (THis is not implemented)
+      Snacks.notifier.notify(table.concat(result, '\n'), vim.log.levels.INFO, {
+        title = 'Orgmode',
+        ft = 'org'
+      })
+    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.system({
+            'notify-send',
+            '--icon=/path/to/orgmode/assets/nvim-orgmode-small.png',
+            '--app-name=orgmode',
+            title,
+            string.format('%s\n%s', subtitle, date),
+          })
+        end
+
+        -- MacOS
+        if vim.fn.executable('terminal-notifier') == 1 then
+          vim.system({ 'terminal-notifier', '-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 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

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")'

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

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    |

Advanced search

Part of Advanced search functionality is implemented.

To leverage advanced search, open up agenda prompt (default <Leader>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

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:

Setting header-args on multiple levels:
1. Configuration (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 #+begin_src lua :tangle yes
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)
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 <<headline2block>>print('Headline 1') #+end_src

#+name: headline2block #+begin_src lua :tangle yesprint('Headline 2') #+end_src #+end_src

Running org_babel_tangle 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 <<headline2block>> 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 noprint('Headline 2') #+end_src

Running org_babel_tangle will create file ~/org/my_tangled_file.lua with this content:

#+begin_src lua print('Headline 2') print('Headline 1')#+end_src

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.block: A begin/end block (example: #begin_src) - linked to @comment
@org.inline_block: A src_lang block (example: print('foo') ) - linked to @comment
@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 without description (example: [[file:/this/is/link]]) - linked to @markup.link,
@org.hyperlink.url: Url part of the link with description (example: [[file:/this/is/url][description]]) - linked to @markup.link.url,
@org.hyperlink.desc: Description part of the link with description (example: [[file:/path/to/file][description]]) - linked to @markup.link.label,
@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.time_grid: Time grid line - 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:

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
+})

For adding/changing TODO keyword colors see org-todo-keyword-faces

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

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,
+    },
+  },
+})

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.3+, 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
+    }
+  }
+})

Input

By default, Vim's built-in input() function is used for input prompts. To use Neovim's vim.ui.input() function, add this to config:

lua

require('orgmode').setup({
+  ui = {
+    input = {
+      use_vim_ui = true
+    }
+  }
+})

📝 NOTE: If you are using a plugin for vim.ui.input, make sure it supports autocompletion for better experience. snacks.nvim input module supports autocompletion.

Agenda

Use this section to customize the styling of the Agenda preview floating window (See org_agenda_preview mapping). To see available options for the preview window, check :help vim.lsp.util.open_floating_preview.Opts. Here's an example how to configure it:

lua

require('orgmode').setup({
+  ui = {
+    agenda = {
+      preview_window = {
+        wrap = false, -- This option is set by default
+        border = 'single'
+      }
+    }
+  }
+})

📝 NOTE: This preview should be used only as read only view of the headline and it's content. Modifying the file from the preview window is not supported.

Changelog ​

0.7.2 (2025-12-03) ​

Breaking changes ​

Features ​

Bug fixes ​

0.7.1 (2025-09-06) ​

Breaking changes ​

Bug fixes ​

0.7.0 (2025-09-05) ​

Breaking changes ​

Features ​

Bug fixes ​

0.6.0 (2025-05-11) ​

Breaking changes ​

Features ​

Bug fixes ​

0.5.3 (2025-03-26) ​

Breaking changes ​

Features ​

Bug fixes ​

0.5.2 (2025-03-07) ​

Bug fixes ​

0.5.1 (2025-03-05) ​

Features ​

Bug fixes ​

0.5.0 (2025-03-02) ​

Breaking changes ​

Features ​

Bug fixes ​

0.4.32 (2025-02-23) ​

Features ​

Bug fixes ​

0.4.31 (2025-02-20) ​

Bug fixes ​

0.4.3 (2025-02-20) ​

Features ​

Bug fixes ​

0.4.2 (2025-02-01) ​

Features ​

Bug fixes ​

0.4.1 (2025-01-28) ​

Features ​

Bug fixes ​

0.4.0 (2025-01-24) ​

Features ​

Bug fixes ​

0.3.9 (2025-01-21) ​

Breaking changes ​

Features ​

Bug fixes ​

0.3.8 (2025-01-06) ​

Breaking changes ​

Features ​

Bug fixes ​

0.3.7 (2024-09-24) ​

Bug fixes ​

0.3.61 (2024-09-23) ​

Bug fixes ​

0.3.6 (2024-09-23) ​

Breaking changes ​

Features ​

Bug fixes ​

0.3.5 (2024-08-22) ​

Breaking changes ​

Features ​

Bug fixes ​

Configuration ​

Global settings ​

org_agenda_files ​

org_default_notes_file ​

org_todo_keywords ​

org_todo_repeat_to_state ​

win_split_mode ​

win_border ​

org_startup_folded ​

org_todo_keyword_faces ​

org_archive_location ​

org_hide_leading_stars ​

org_hide_emphasis_markers ​

org_ellipsis ​

Changelog

0.7.2 (2025-12-03)

Breaking changes

Features

Bug fixes

0.7.1 (2025-09-06)

Breaking changes

Bug fixes

0.7.0 (2025-09-05)

Breaking changes

Features

Bug fixes

0.6.0 (2025-05-11)

Breaking changes

Features

Bug fixes

0.5.3 (2025-03-26)

Breaking changes

Features

Bug fixes

0.5.2 (2025-03-07)

Bug fixes

0.5.1 (2025-03-05)

Features

Bug fixes

0.5.0 (2025-03-02)

Breaking changes

Features

Bug fixes

0.4.32 (2025-02-23)

Features

Bug fixes

0.4.31 (2025-02-20)

Bug fixes

0.4.3 (2025-02-20)

Features

Bug fixes

0.4.2 (2025-02-01)

Features

Bug fixes

0.4.1 (2025-01-28)

Features

Bug fixes

0.4.0 (2025-01-24)

Features

Bug fixes

0.3.9 (2025-01-21)

Breaking changes

Features

Bug fixes

0.3.8 (2025-01-06)

Breaking changes

Features

Bug fixes

0.3.7 (2024-09-24)

Bug fixes

0.3.61 (2024-09-23)

Bug fixes

0.3.6 (2024-09-23)

Breaking changes

Features

Bug fixes

0.3.5 (2024-08-22)

Breaking changes

Features

Bug fixes

Configuration

Global settings

org_agenda_files

org_default_notes_file

org_todo_keywords

org_todo_repeat_to_state

win_split_mode

win_border

org_startup_folded

org_todo_keyword_faces

org_archive_location

org_hide_leading_stars

org_hide_emphasis_markers

org_ellipsis