neovimcraft

plugins about

note-taking

1,817

CREATED

2021-05-13

UPDATED

6 days ago

nvim-orgmode

Orgmode clone written in Lua for Neovim 0.7+

Setup • Docs • Showcase • Treesitter • Troubleshoot • Plugins • Development • Kudos

Quickstart

Requirements

Neovim 0.7.0 or later
nvim-treesitter

Installation

Use your favourite package manager:

packager.add('nvim-treesitter/nvim-treesitter')
packager.add('nvim-orgmode/orgmode')

use {'nvim-treesitter/nvim-treesitter'}
use {'nvim-orgmode/orgmode', config = function()
  require('orgmode').setup{}
end
}

Plug 'nvim-treesitter/nvim-treesitter'
Plug 'nvim-orgmode/orgmode'

call dein#add('nvim-treesitter/nvim-treesitter')
call dein#add('nvim-orgmode/orgmode')

Lazy loading via ft option works, but not completely. Global mappings are not set because plugin is not initialized on startup. Above setup has a startup time of somewhere between 1 and 3 ms, so there are not many benefits in lazy loading. If you want to do it anyway, here's the lazy load setup:

use {'nvim-treesitter/nvim-treesitter'}
use {'nvim-orgmode/orgmode',
    ft = {'org'},
    config = function()
            require('orgmode').setup{}
    end
    }

Setup

-- init.lua

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

-- Treesitter 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,
    -- Required for spellcheck, some LaTex highlights and
    -- code block highlights that do not have ts grammar
    additional_vim_regex_highlighting = {'org'},
  },
  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, wrap the above snippet like so:

" init.vim
lua << EOF

require('orgmode').setup_ts_grammar() ...

EOF

Completion

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

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

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

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

Usage

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 the Docs or a hands-on tutorial in our wiki.

Showcase

Agenda

agenda

Org file

orgfile

Capturing and refiling

capture

Autocompletion

autocomplete

Treesitter Info

The built-in treesitter parser is used for parsing the org files. Highlights are experimental and partially supported.

Advantages of treesitter over built in parsing/syntax:

More reliable, since parsing is done with a proper parsing tool
Better highlighting (Experimental, still requires improvements)
Future features will be easier to implement because the 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 (https://github.com/neovim/neovim/issues/14762, https://github.com/neovim/neovim/issues/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)
Treesitter highlight injections through #BEGIN_SRC filetype blocks
Headline markup highlighting (https://github.com/nvim-orgmode/orgmode/issues/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

Jumping to file path is not working for paths with forward slash

If you are using Windows, paths are by default written with backslashes. To use forward slashes, you must enable shellslash option (see :help 'shellslash').

vim.opt.shellslash = true

Or if you are using init.vim:

set shellslash

More info on issue #281

Features

TL;DR

Agenda view
Search by tags/keyword
Clocking time
Repeatable dates, date and time ranges
Capturing to default notes file/destination
Archiving (archive file or ARCHIVE tag)
Exporting (via emacs, pandoc and custom export options)
Notifications (experimental, see Issue #49)
Calendar popup for easier navigation and date updates
Various org file mappings:
- Promote/Demote
- Change TODO state
- Change dates
- Insert/Move/Refile headlines
- Change tags
- Toggle checkbox state
Clocking time
Remote editing from agenda view
Repeatable mapping via vim-repeat

Detailed breakdown

Agenda prompt:
- Agenda view (a):
  - Ability to show daily(vd)/weekly(vw)/monthly(vm)/yearly(vy) agenda
  - Support for various date settings:
    - DEADLINE: Warning settings - example: <2021-06-11 Fri 11:00 -1d>
    - SCHEDULED: Delay setting - example: <2021-06-11 Fri 11:00 -2d>
    - All dates - Repeater settings:
      - Cumulate type: <2021-06-11 Fri 11:00 +1w>
      - Catch-up type: <2021-06-11 Fri 11:00 ++1w>
      - Restart type: <2021-06-11 Fri 11:00 .+1w>
    - Time ranges - example: <2021-06-11 Fri 11:00-12:30>
    - Date ranges - example: <2021-06-11 Fri 11:00-12:30>--<2021-06-13 Sun 22:00>
  - Properly lists tasks according to defined dates (DEADLINE,SCHEDULED,Plain date)
  - Navigate forward (f)/backward(b) or jump to specific date (J)
  - Go to task under cursor in current window(<CR>) or other window(<TAB>)
  - Print category from ":CATEGORY:" property if defined
- List tasks that have "TODO" state (t):
- Find headlines matching tag(s) (m):
- Search for headlines (and it's content) for a query (s):
- Advanced search for tags/todo kewords/properties
- Notifications (experimental, see Issue #49)
- Clocking time
Capture:
- Define custom templates
- Fast capturing to default notes file via <C-c>
- Capturing to specific destination <Leader>or
- Abort capture with <Leader>ok
Org files
- Clocking time
- Refile to destination/headline: <Leader>or
- Increase/Decrease date under cursor: <C-a>/<C-x>
- Change date under cursor via calendar popup: cid
- Change headline TODO state: forwardcit or backwardciT
- Open hyperlink or date under cursor: <Leader>oo
- Toggle checkbox: <C-space>
- Toggle current line to headline and vice versa: <Leader>o*
- Toggle folding of current headline: <TAB>
- Toggle folding in whole file: <S-TAB>
- Archive headline: <Leader>o$
- Add archive tag: <Leader>oA
- Change tags: <Leader>ot
- Promote headline: <<
- Demote headline: >>
- Promote subtree: <s
- Demote subtree: >s
- Add headline/list item/checkbox: <Leader><CR>
- Insert heading after current heading and it's content: <Leader>oih
- Insert TODO heading after current line: <Leader>oiT
- Insert TODO heading after current heading and it's content: <Leader>oit
- Move headline up: <Leader>oK
- Move headline down: <Leader>oJ
- Highlighted code blocks (#+BEGIN_SRC filetype)
- Exporting (via emacs, pandoc and custom export options)

Link to detailed documentation: DOCS

Plugins

org-bullets.nvim - Show org mode bullets as UTF-8 characters
headlines.nvim - Add few highlight options for code blocks and headlines
sniprun - For code evaluation in blocks
vim-table-mode - For table support

See all available plugins on orgmode-nvim

If you built a plugin please add "orgmode-nvim" topic to it.

NOTE: None of the Emacs Orgmode plugins will be built into nvim-orgmode. Anything that's a separate plugin in Emacs Orgmode should be a separate plugin in here. The point of this plugin is to provide functionality that's built into Emacs Orgmode core, and a good foundation for external plugins. If you want to build a plugin, post suggestions and improvements on Plugins infrastructure issue.

Development

Tests

To run tests, plenary.nvim and nvim-treesitter must be present in the nvim-orgmode directory:

git clone https://github.com/nvim-treesitter/nvim-treesitter
git clone https://github.com/nvim-lua/plenary.nvim
make test

Documentation

Hosted documentation is on: https://nvim-orgmode.github.io/

Vim documentation is auto generated from DOCS.md file with md2vim.

Formatting

Formatting is done via StyLua. To format everything run:

make format

Parser

Parsing is done via builtin treesitter parser and tree-sitter-org grammar.

Roadmap

Support searching by properties
Improve checkbox hierarchy
Support todo keyword faces
Support clocking work time
Improve folding
Support exporting (via existing emacs tools)
Support archiving to specific headline
Support tables
Support diary format dates
Support evaluating code blocks

Thanks to

@dhruvasagar and his vim-dotoo plugin that got me started using orgmode. Without him this plugin would not happen.
@milisims for writing a treesitter parser for org
vim-orgmode for some parts of the code (mostly syntax)

neovimcraft

neovimcraft

nvim-orgmode/orgmode

CREATED

2021-05-13

UPDATED

6 days ago

nvim-orgmode

Quickstart

Requirements

Installation

Setup

Completion

Usage

Showcase

Agenda

Org file

Capturing and refiling

Autocompletion

Treesitter Info

Advantages of treesitter over built in parsing/syntax:

Known highlighting issues and limitations

Improvements over Vim's syntax highlighting

Troubleshoot

Folding is not working

Indentation is not working

I get treesitter/query.lua errors when opening agenda/capture prompt or org files

Dates are not in English

Links are not concealed

Jumping to file path is not working for paths with forward slash

Features

TL;DR

Detailed breakdown

Plugins

Development

Tests

Documentation

Formatting

Parser

Roadmap

Thanks to

I get `treesitter/query.lua` errors when opening agenda/capture prompt or org files