Setup

-- init.lua

-- Load custom tree-sitter grammar for org filetype
require('orgmode').setup_ts_grammar()

-- Tree-sitter configuration
require'nvim-treesitter.configs'.setup {
  -- If TS highlights are not enabled at all, or disabled via ``disable`` prop, highlighting will fallback to default Vim syntax highlighting
  highlight = {
    enable = true,
    disable = {'org'}, -- Remove this to use TS highlighter for some of the highlights (Experimental)
    additional_vim_regex_highlighting = {'org'}, -- Required since TS highlighter doesn't support all syntax features (conceal)
  },
  ensure_installed = {'org'}, -- Or run :TSUpdate org
}

require('orgmode').setup({
  org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'},
  org_default_notes_file = '~/Dropbox/org/refile.org',
})

Or if you are using init.vim:

" init.vim
lua << EOF

-- Load custom tree-sitter grammar for org filetype
require('orgmode').setup_ts_grammar()

-- Tree-sitter configuration
require'nvim-treesitter.configs'.setup {
  -- If TS highlights are not enabled at all, or disabled via `disable` prop, highlighting will fallback to default Vim syntax highlighting
  highlight = {
    enable = true,
    disable = {'org'}, -- Remove this to use TS highlighter for some of the highlights (Experimental)
    additional_vim_regex_highlighting = {'org'}, -- Required since TS highlighter doesn't support all syntax features (conceal)
  },
  ensure_installed = {'org'}, -- Or run :TSUpdate org
}

require('orgmode').setup({
  org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'},
  org_default_notes_file = '~/Dropbox/org/refile.org',
})
EOF

• Open agenda prompt: <Leader>oa
• Open capture prompt: <Leader>oc
• In any orgmode buffer press g? for help

If you are new to Orgmode, see Getting started section in Docs.

Completion

If you use nvim-compe and want to enable autocompletion, add this to your compe config:

require'compe'.setup({
  source = {
    orgmode = true
  }
})

For nvim-cmp, add orgmode to list of sources:

require'cmp'.setup({
  sources = {
    { name = 'orgmode' }
  }
})

For completion.nvim, just add omni mode to chain complete list and add additional keyword chars:

vim.g.completion_chain_complete_list = {
  org = {
    { mode = 'omni'},
  },
}
vim.cmd[[autocmd FileType org setlocal iskeyword+=:,#,+]]

Or just use omnifunc via <C-x><C-o>

Tree-sitter info

Built in tree-sitter parser is used for parsing the org files. Highlights are experimental and partially supported.

Advantages of tree-sitter over built in parsing/syntax:

• More reliable, since parsing is done with proper parsing tool
• Better highlighting (Experimental, still requires improvements)
• Future features will be easier to implement because grammar already parses some things that were not parsed before (tables, latex, etc.)
• Allows for easier hacking (custom motions that can work with TS nodes, etc.)

Known highlighting issues and limitations

• Performance issues. This is generally an issue in Neovim that should be resolved before 0.6 release (neovim Issue #14762, neovim Issue #14762)
• Anything that requires concealing (org_hide_emphasis_markers, links concealing) is not (yet) supported in TS highlighter
• LaTex is still highlighted through syntax file

Improvements over Vim’s syntax highlighting

• Better highlighting of certain parts (tags, deadline/schedule/closed dates)
• Tree-sitter highlight injections through #BEGIN_SRC filetype blocks
• Headline markup highlighting (Issue #67)

Troubleshoot

• Folding is not working

Make sure you are not overriding foldexpr in Org buffers with nvim-treesitter folding

• 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

Make sure you are using latest changes from tree-sitter-org grammar by running :TSUpdate org and restarting the editor.

• 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:

vim.cmd('language en_US.utf8')

or init.vim:

language en_US.utf8

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 <TAB> to autocomplete possible options.

• Links are not concealed

Links are concealed with Vim’s conceal feature (see :help conceal). To enable concealing, add this to your init.lua:

vim.opt.conceallevel = 2
vim.opt.concealcursor = 'nc'

Or if you are using init.vim:

set conceallevel=2
set concealcursor=nc