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 #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]

#215 is now merged into master, and tagged as 0.2 release.

[kristijanhusak]

org_agenda_templates was renamed to org_capture_templates as per #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
• Support the new conceal support for tree-sitter #261
• Bold/italic emphasis syntax is not rendered in headlines #67

[kristijanhusak]

Insert mode <CR> mapping was added with 35f4fb6 , for purposes of adding new row in a table which can now be formatted (per 87291af).

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 #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]

#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 (#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).