Notice of breaking changes

[kristijanhusak]

This pinned issue is used to announce breaking changes and other important information to the users.

Breaking changes will be announced at least a week in advance.

[kristijanhusak]

org tree-sitter grammar recently got a major overhaul. This breaks current code on master. Updated version is on PR https://github.com/nvim-orgmode/orgmode/pull/215. This will be merged in a week or so and tagged as v0.2 release. Going forward, there will be more frequent releases of minor and patch versions.

Changes that are required: https://github.com/nvim-orgmode/orgmode/pull/215/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L74-R75

Replace this:

local parser_config = require "nvim-treesitter.parsers".get_parser_configs()
parser_config.org = {
  install_info = {
    url = 'https://github.com/milisims/tree-sitter-org',
    revision = 'f110024d539e676f25b72b7c80b0fd43c34264ef',
    files = {'src/parser.c', 'src/scanner.cc'},
  },
  filetype = 'org',
}

With this:

require('orgmode').setup_ts_grammar()

And run:

:TSUpdate org

If above change is not done, proper error message will be printed out with instructions.

[kristijanhusak]

https://github.com/nvim-orgmode/orgmode/pull/215 is now merged into master, and tagged as 0.2 release.

[kristijanhusak]

org_agenda_templates was renamed to org_capture_templates as per https://github.com/nvim-orgmode/orgmode/issues/223. Old org_agenda_templates option will keep working, but everyone should switch to the new one.

[kristijanhusak]

Support for Neovim versions under v0.7 will be dropped due to nvim-treesitter requiring Neovim v0.7. Nvim-treesitter doesn't have any versioning so it's hard to follow proper nvim-treesitter version for older Neovim.

[kristijanhusak]

Master branch got an update for markup highlighting and concealing. Everyone who uses treesitter highlights should get new improved markup highlighting. This change addresses these issues:

• Combining highlights (for example, italic inside bold)
• Links inside headlines
• https://github.com/nvim-orgmode/orgmode/issues/261
• https://github.com/nvim-orgmode/orgmode/issues/67

[kristijanhusak]

Insert mode <CR> mapping was added with https://github.com/nvim-orgmode/orgmode/commit/35f4fb6faf7b26d8c09e382092f0ece0bc11ebd7 , for purposes of adding new row in a table which can now be formatted (per https://github.com/nvim-orgmode/orgmode/commit/87291af2c909adaddf4dcf97fbf9bf7154e03bd1).

If your <CR> is misbehaving, you can disable the mapping like this:

require('orgmode').setup({
  mappings = {
    org_return = false
  }
})

Please report any issues found with it.

[kristijanhusak]

Headline tags in org files are now right aligned according to the org_tags_column setting instead of left aligned, to match Emacs Orgmode implementation. This shouldn't cause any breaking changes, but changing tags on a headline from now on will most likely be differently aligned than before.

Before:

* TODO Something                                                                :TEST:
* TODO Something  else                                                          :TESTING:

After:

* TODO Something                                                          :TEST:
* TODO Something  else                                                 :TESTING:

[kristijanhusak]

Official support for Neovim versions < 0.8 will be dropped in the following weeks. Most likely nothing will break for some time, but since nvim-treesitter requires 0.8+, support for lower versions would be impossible.

[kristijanhusak]

Folding is now using nvim-treesitter folding via tree-sitter queries instead of custom implementation (PR https://github.com/nvim-orgmode/orgmode/pull/523). If anyone finds any differences or bugs between old and new implementation please open up an issue.

[kristijanhusak]

Support for Neovim versions < 0.8.3 are officially dropped. Everything should still work, but future changes might cause some breaking issus.

[kristijanhusak]

https://github.com/nvim-orgmode/orgmode/pull/654 changed the default mapping for inserting link from <prefix>il (default <leader>oil) to <prefix>li (default <leader>oli).

[kristijanhusak]

master branch is now tagged behind https://github.com/nvim-orgmode/orgmode/releases/tag/0.3. This is the last version that has a mix of old and new ways of parsing (direct tree-sitter queries and parsing + storing results in objects/classes), which complicated the development. master branch will stay intact for another 1 - 2 weeks, and then nightly branch will be merged into it.

nightly branch is a cleanup + rewrite of the functionality to work directly with tree-sitter. It is advised to use nightly Neovim versions due to faster tree-sitter parser, but changes are also fully compatible with v0.9.2+.

If you are using any of the internals, especially ones under orgmode.parser.* namespace, consider switching to API. It was not changed and is fully compatible with the previous version. All files from that namespace were removed, with an exception of files.lua that will show deprecation notice. If you are missing some of the functionality that you use from internals, please open up an issue and we can extend API where necessary.

The biggest change regarding the functionality is the removal of the old syntax highlighting in the #+begin_src blocks. If you need highlighting in the blocks for any of the language, consider installing a tree-sitter parser for it with :TSInstall {language}.

Any help on testing a nightly branch before it gets merged is highly appreciated. If you find anything, please open up an issue and add [nightly] before the title. This is just a temporary requirement until nightly gets merged into master.

[kristijanhusak]

The nightly branch was merged into master (https://github.com/nvim-orgmode/orgmode/pull/665). There are some improvements to the markup rendering correctness and performance, besides what was mentioned above. Master works best with the Neovim nightly, but is compatible with 0.9.2+ versions, but it might perform a bit slower (due to older tree-sitter version).

[kristijanhusak]

https://github.com/nvim-orgmode/orgmode/pull/676 introduced two bigger changes to highlighting:

1. Old Vim syntax was completely removed. Now it always relies on tree-sitter for highlights
2. Highlight groups were renamed and change to be more inline with treesitter highlights (see :h treesitter-highlights). To override any colors, follow the instructions in docs https://github.com/nvim-orgmode/orgmode/blob/master/DOCS.md#colors

To use old highlights add this to your init.lua:

local orgmode_highlights = {
  ['@org.timestamp.active'] = 'PreProc',
  ['@org.timestamp.inactive'] = 'Comment',
  ['@org.bullet'] = 'Identifier',
  ['@org.checkbox'] = 'PreProc',
  ['@org.checkbox.halfchecked'] = 'PreProc',
  ['@org.checkbox.checked'] = 'PreProc',
  ['@org.properties'] = 'Constant',
  ['@org.drawer'] = 'Constant',
  ['@org.tag'] = 'Function',
  ['@org.plan'] = 'Constant',
  ['@org.comment'] = 'Comment',
  ['@org.directive'] = 'Comment',
  ['@org.block'] = 'Comment',
  ['@org.latex'] = 'Statement',
  ['@org.hyperlink'] = 'Underlined',
  ['@org.code'] = 'String',
  ['@org.code.delimiter'] = 'String',
  ['@org.verbatim'] = 'String',
  ['@org.verbatim.delimiter'] = 'String',
  ['@org.bold'] = { bold = true },
  ['@org.bold.delimiter'] = { bold = true },
  ['@org.italic'] = { italic = true },
  ['@org.italic.delimiter'] = { italic = true },
  ['@org.strikethrough'] = { strikethrough = true },
  ['@org.strikethrough.delimiter'] = { strikethrough = true },
  ['@org.underline'] = { underline = true },
  ['@org.underline.delimiter'] = { underline = true },
}

for new_hl, old_hl in pairs(orgmode_highlights) do
  if type(old_hl) == 'table' then
    vim.api.nvim_set_hl(0, new_hl, old_hl)
  else
    vim.api.nvim_set_hl(0, new_hl, { link = old_hl })
  end
end

[kristijanhusak]

Support for nvim-compe was removed in https://github.com/nvim-orgmode/orgmode/pull/678 since that plugin is no longer maintained.

[kristijanhusak]

Dependency on https://github.com/nvim-treesitter/nvim-treesitter will be removed when https://github.com/nvim-orgmode/orgmode/pull/707 is merged. TS grammar is now installed and compiled by orgmode. There will be a tagged release before merging this change to master.

This means that require('orgmode').setup_ts_grammar() can now be removed. This is how the setup should be done with lazy:

return {
  'nvim-orgmode/orgmode',
  event = 'VeryLazy',
  config = function()
    -- Setup orgmode
    require('orgmode').setup({
      org_agenda_files = '~/orgfiles/**/*',
      org_default_notes_file = '~/orgfiles/refile.org',
    })

    -- NOTE: If you are using nvim-treesitter with `ensure_installed = "all"` option
    -- add `org` to ignore_install
    -- require('nvim-treesitter.configs').setup({
    --   ensure_installed = 'all',
    --   ignore_install = { 'org' },
    -- })
  end,
}

[kristijanhusak]

Dependency on nvim-treesitter is now officially removed. The last version that depends on it is https://github.com/nvim-orgmode/orgmode/releases/tag/0.3.1.

[kristijanhusak]

org_note_show_help mapping was removed in https://github.com/nvim-orgmode/orgmode/commit/f874118c470c6d6cc7522df2de6b1f9989a57529, and it will fall back to org_show_help