Skip to content

Commit c81ff93

Browse files
jgollenzjgollenz
authored
README refactor (#415)
1 parent 743d921 commit c81ff93

File tree

1 file changed

+123
-88
lines changed

1 file changed

+123
-88
lines changed

‎README.md

Lines changed: 123 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -3,44 +3,82 @@
33
<div align="center">
44
<img alt="[org-neovim-blend" src="https://user-images.githubusercontent.com/1782860/124820564-eddc5000-df6d-11eb-9016-d0c073a9575c.png" width="250" />
55

6-
# Orgmode.nvim
6+
# nvim-orgmode
77

8+
<a href="/LICENSE">![License](https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square)</a><a href="https://ko-fi.com/kristijanhusak"> ![Kofi](https://img.shields.io/badge/support-kofi-00b9fe?style=flat-square&logo=kofi)</a><a> ![Chat](https://img.shields.io/matrix/neovim-orgmode:matrix.org?logo=matrix&server_fqdn=matrix.org&style=flat-square)</a>
89

9-
<a href="/LICENSE">![License](https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square)</a><a href="https://ko-fi.com/kristijanhusak"> ![Kofi](https://img.shields.io/badge/support-kofi-00b9fe?style=flat-square&logo=kofi)</a>
1010

11-
Orgmode clone written in Lua for Neovim 0.7.
11+
Orgmode clone written in Lua for Neovim 0.7+
12+
13+
[Setup](#setup) • [Docs](/DOCS.md) • [Showcase](#showcase) • [Treesitter](#treesitter-info) • [Troubleshoot](#troubleshoot) • [Plugins](#plugins) • [Development](#development) • [Kudos](#thanks-to)
1214

13-
[Installation](#installation) | [Setup](#setup) | [Troubleshoot](#troubleshoot) | [Gifs](#gifs) | [Docs](/DOCS.md) | [Tree-sitter info](#tree-sitter-info) | [Plugins](#plugins) | [Development](#development) | [Kudos](#thanks-to)
1415

1516
</div>
1617

17-
## Installation
18+
## Quickstart
19+
20+
### Requirements
21+
22+
* Neovim 0.7.0 or later
23+
* [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter)
24+
25+
### Installation
1826

1927
Use your favourite package manager:
2028

21-
* [vim-packager](https://github.com/kristijanhusak/vim-packager):
29+
<details>
30+
<summary><a href="https://github.com/kristijanhusak/vim-packager"><b>vim-packager</b></a></summary>
31+
</br>
2232

2333
```lua
2434
packager.add('nvim-treesitter/nvim-treesitter')
2535
packager.add('nvim-orgmode/orgmode')
2636
```
2737

28-
- [packer.nvim](https://github.com/wbthomason/packer.nvim)
38+
</details>
2939

30-
**Recommended**
40+
<details open>
41+
<summary><b><a href="https://github.com/wbthomason/packer.nvim">packer.nvim</a> (recommended)</b></summary>
42+
</br>
3143

3244
```lua
3345
use {'nvim-treesitter/nvim-treesitter'}
3446
use {'nvim-orgmode/orgmode', config = function()
35-
require('orgmode').setup{}
47+
require('orgmode').setup{}
3648
end
3749
}
3850
```
3951

40-
**Lazy loading (Not recommended)**
52+
</details>
53+
54+
<details>
55+
<summary><a href="https://github.com/junegunn/vim-plug"><b>vim-plug</b></a></summary>
56+
</br>
57+
58+
```vim
59+
Plug 'nvim-treesitter/nvim-treesitter'
60+
Plug 'nvim-orgmode/orgmode'
61+
```
62+
63+
</details>
64+
65+
<details>
66+
<summary><a href="https://github.com/Shougo/dein.vim"><b>dein.vim</b></a></summary>
67+
</br>
68+
69+
```vim
70+
call dein#add('nvim-treesitter/nvim-treesitter')
71+
call dein#add('nvim-orgmode/orgmode')
72+
```
73+
74+
</details>
75+
76+
<details>
77+
<summary><b>Lazy loading (not recommended)</b></summary>
78+
</br>
4179

4280
Lazy loading via `ft` option works, but not completely. Global mappings are not set because plugin is not initialized on startup.
43-
Above setup has startup time of somewhere between 1 and 3 ms, so there are no many benefits in lazy loading.
81+
Above setup has a startup time of somewhere between 1 and 3 ms, so there are not many benefits in lazy loading.
4482
If you want to do it anyway, here's the lazy load setup:
4583
```lua
4684
use {'nvim-treesitter/nvim-treesitter'}
@@ -52,34 +90,25 @@ use {'nvim-orgmode/orgmode',
5290
}
5391
```
5492

55-
- [vim-plug](https://github.com/junegunn/vim-plug)
56-
57-
```vim
58-
Plug 'nvim-treesitter/nvim-treesitter'
59-
Plug 'nvim-orgmode/orgmode'
60-
```
93+
</details>
6194

62-
- [dein](https://github.com/Shougo/dein.vim)
63-
64-
```vim
65-
call dein#add('nvim-treesitter/nvim-treesitter')
66-
call dein#add('nvim-orgmode/orgmode')
67-
```
68-
69-
## Setup
95+
### Setup
7096

7197
```lua
7298
-- init.lua
7399

74-
-- Load custom tree-sitter grammar for org filetype
100+
-- Load custom treesitter grammar for org filetype
75101
require('orgmode').setup_ts_grammar()
76102

77-
-- Tree-sitter configuration
78-
require'nvim-treesitter.configs'.setup {
79-
-- If TS highlights are not enabled at all, or disabled via `disable` prop, highlighting will fallback to default Vim syntax highlighting
103+
-- Treesitter configuration
104+
require('nvim-treesitter.configs').setup {
105+
-- If TS highlights are not enabled at all, or disabled via `disable` prop,
106+
-- highlighting will fallback to default Vim syntax highlighting
80107
highlight = {
81108
enable = true,
82-
additional_vim_regex_highlighting = {'org'}, -- Required for spellcheck, some LaTex highlights and code block highlights that do not have ts grammar
109+
-- Required for spellcheck, some LaTex highlights and
110+
-- code block highlights that do not have ts grammar
111+
additional_vim_regex_highlighting = {'org'},
83112
},
84113
ensure_installed = {'org'}, -- Or run :TSUpdate org
85114
}
@@ -90,115 +119,120 @@ require('orgmode').setup({
90119
})
91120
```
92121

93-
Or if you are using `init.vim`:
122+
Or if you are using `init.vim`, wrap the above snippet like so:
94123
```vim
95124
" init.vim
96125
lua << EOF
97126
98-
-- Load custom tree-sitter grammar for org filetype
99-
require('orgmode').setup_ts_grammar()
100-
101-
-- Tree-sitter configuration
102-
require'nvim-treesitter.configs'.setup {
103-
-- If TS highlights are not enabled at all, or disabled via `disable` prop, highlighting will fallback to default Vim syntax highlighting
104-
highlight = {
105-
enable = true,
106-
additional_vim_regex_highlighting = {'org'}, -- Required for spellcheck, some LaTex highlights and code block highlights that do not have ts grammar
107-
},
108-
ensure_installed = {'org'}, -- Or run :TSUpdate org
109-
}
127+
require('orgmode').setup_ts_grammar() ...
110128
111-
require('orgmode').setup({
112-
org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'},
113-
org_default_notes_file = '~/Dropbox/org/refile.org',
114-
})
115129
EOF
116130
```
131+
#### Completion
117132

118-
* **Open agenda prompt**: <kbd>\<Leader\>oa</kbd>
119-
* **Open capture prompt**: <kbd>\<Leader\>oc</kbd>
120-
* In any orgmode buffer press <kbd>g?</kbd> for help
121-
122-
If you are new to Orgmode, see [Getting started](/DOCS.md#getting-started-with-orgmode) section in Docs.
123-
124-
### Completion
125-
If you use [nvim-compe](https://github.com/hrsh7th/nvim-compe) and want
126-
to enable autocompletion, add this to your compe config:
133+
<details>
134+
<summary><a href="https://github.com/hrsh7th/nvim-compe"><b>nvim-compe</b></a></summary>
135+
</br>
127136

128137
```lua
129-
require'compe'.setup({
138+
require('compe').setup({
130139
source = {
131140
orgmode = true
132141
}
133142
})
134143
```
135144

136-
For [nvim-cmp](https://github.com/hrsh7th/nvim-cmp), add `orgmode` to list of sources:
145+
</details>
146+
147+
<details>
148+
<summary><a href="https://github.com/hrsh7th/nvim-cmp"><b>nvim-cmp</b></a></summary>
149+
</br>
150+
137151
```lua
138-
require'cmp'.setup({
152+
require('cmp').setup({
139153
sources = {
140154
{ name = 'orgmode' }
141155
}
142156
})
143157
```
144158

145-
For [completion.nvim](https://github.com/nvim-lua/completion-nvim), just add `omni` mode to chain complete list and add additional keyword chars:
159+
</details>
160+
161+
<details>
162+
<summary><a href="https://github.com/nvim-lua/completion-nvim"><b>completion-nvim</b></a></summary>
163+
</br>
164+
146165
```lua
147166
vim.g.completion_chain_complete_list = {
148167
org = {
149168
{ mode = 'omni'},
150169
},
151170
}
171+
-- add additional keyword chars
152172
vim.cmd[[autocmd FileType org setlocal iskeyword+=:,#,+]]
153173
```
154174

175+
</details>
176+
155177
Or just use `omnifunc` via <kbd>\<C-x\>\<C-o\></kbd>
156178

157-
### Gifs
158-
#### Agenda
179+
180+
### Usage
181+
182+
183+
* **Open agenda prompt**: <kbd>\<Leader\>oa</kbd>
184+
* **Open capture prompt**: <kbd>\<Leader\>oc</kbd>
185+
* In any orgmode buffer press <kbd>g?</kbd> for help
186+
187+
If you are new to Orgmode, see [Getting started](/DOCS.md#getting-started-with-orgmode) section in the Docs
188+
or a hands-on [[https://github.com/nvim-orgmode/orgmode/wiki/Getting-Started][tutorial]] in our wiki.
189+
190+
191+
## Showcase
192+
### Agenda
159193
![agenda](https://user-images.githubusercontent.com/1782860/123549968-8521f600-d76b-11eb-9a93-02bad08b37ce.gif)
160194

161-
#### Org file
195+
### Org file
162196
![orgfile](https://user-images.githubusercontent.com/1782860/123549982-90752180-d76b-11eb-8828-9edf9f76af08.gif)
163197

164-
#### Capturing and refiling
198+
### Capturing and refiling
165199
![capture](https://user-images.githubusercontent.com/1782860/123549993-9a972000-d76b-11eb-814b-b348a93df08a.gif)
166200

167-
#### Autocompletion
201+
### Autocompletion
168202
![autocomplete](https://user-images.githubusercontent.com/1782860/123550227-e8605800-d76c-11eb-96f6-c0a677d562d4.gif)
169203

170-
### Tree-sitter info
171-
Built in tree-sitter parser is used for parsing the org files.
204+
## Treesitter Info
205+
The built-in treesitter parser is used for parsing the org files.
172206
Highlights are experimental and partially supported.
173207

174-
#### Advantages of tree-sitter over built in parsing/syntax:
175-
* More reliable, since parsing is done with proper parsing tool
208+
### Advantages of treesitter over built in parsing/syntax:
209+
* More reliable, since parsing is done with a proper parsing tool
176210
* Better highlighting (Experimental, still requires improvements)
177-
* Future features will be easier to implement because grammar already parses some things that were not parsed before (tables, latex, etc.)
211+
* Future features will be easier to implement because the grammar already parses some things that were not parsed before (tables, latex, etc.)
178212
* Allows for easier hacking (custom motions that can work with TS nodes, etc.)
179213

180-
#### Known highlighting issues and limitations
214+
### Known highlighting issues and limitations
181215
* 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)
182216
* Anything that requires concealing ([org_hide_emphasis_markers](/DOCS.md#org_hide_emphasis_markers), links concealing) is not (yet) supported in TS highlighter
183217
* LaTex is still highlighted through syntax file
184218

185-
#### Improvements over Vim's syntax highlighting
219+
### Improvements over Vim's syntax highlighting
186220
* Better highlighting of certain parts (tags, deadline/schedule/closed dates)
187-
* [Tree-sitter highlight injections](https://github.com/nvim-treesitter/nvim-treesitter/blob/4f2265632becabcd2c5b1791fa31ef278f1e496c/CONTRIBUTING.md#injections) through `#BEGIN_SRC filetype` blocks
221+
* [Treesitter highlight injections](https://github.com/nvim-treesitter/nvim-treesitter/blob/4f2265632becabcd2c5b1791fa31ef278f1e496c/CONTRIBUTING.md#injections) through `#BEGIN_SRC filetype` blocks
188222
* Headline markup highlighting (https://github.com/nvim-orgmode/orgmode/issues/67)
189223

190-
#### Troubleshoot
191-
##### Folding is not working
224+
## Troubleshoot
225+
### Folding is not working
192226
Make sure you are not overriding foldexpr in Org buffers with [nvim-treesitter folding](https://github.com/nvim-treesitter/nvim-treesitter#folding)
193227

194-
##### Indentation is not working
228+
### Indentation is not working
195229
Make sure you are not overriding indentexpr in Org buffers with [nvim-treesitter indentation](https://github.com/nvim-treesitter/nvim-treesitter#indentation)
196230

197-
##### I get `treesitter/query.lua` errors when opening agenda/capture prompt or org files
231+
### I get `treesitter/query.lua` errors when opening agenda/capture prompt or org files
198232
Make sure you are using latest changes from [tree-sitter-org](https://github.com/milisims/tree-sitter-org) grammar.<br />
199233
by running `:TSUpdate org` and restarting the editor.
200234

201-
##### Dates are not in English
235+
### Dates are not in English
202236
Dates are generated with Lua native date support, and it reads your current locale when creating them.<br />
203237
To use different locale you can add this to your `init.lua`:
204238
```lua
@@ -211,7 +245,7 @@ language en_US.utf8
211245
Just make sure you have `en_US` locale installed on your system. To see what you have available on the system you can
212246
start the command `:language ` and press `<TAB>` to autocomplete possible options.
213247

214-
##### Links are not concealed
248+
### Links are not concealed
215249
Links are concealed with Vim's conceal feature (see `:help conceal`). To enable concealing, add this to your `init.lua`:
216250
```lua
217251
vim.opt.conceallevel = 2
@@ -225,7 +259,7 @@ set conceallevel=2
225259
set concealcursor=nc
226260
```
227261

228-
##### Jumping to file path is not working for paths with forward slash
262+
### Jumping to file path is not working for paths with forward slash
229263
If you are using Windows, paths are by default written with backslashes.
230264
To use forward slashes, you must enable `shellslash` option (see `:help 'shellslash'`).
231265

@@ -241,7 +275,8 @@ set shellslash
241275

242276
More info on issue [#281](https://github.com/nvim-orgmode/orgmode/issues/281#issuecomment-1120200775)
243277

244-
### Features (TL;DR):
278+
## Features
279+
### TL;DR
245280
* Agenda view
246281
* Search by tags/keyword
247282
* Clocking time
@@ -262,7 +297,7 @@ More info on issue [#281](https://github.com/nvim-orgmode/orgmode/issues/281#iss
262297
* Remote editing from agenda view
263298
* Repeatable mapping via [vim-repeat](https://github.com/tpope/vim-repeat)
264299

265-
### Features (Detailed breakdown):
300+
### Detailed breakdown
266301
* Agenda prompt:
267302
* Agenda view (<kbd>a</kbd>):
268303
* Ability to show daily(<kbd>vd</kbd>)/weekly(<kbd>vw</kbd>)/monthly(<kbd>vm</kbd>)/yearly(<kbd>vy</kbd>) agenda
@@ -329,9 +364,9 @@ See all available plugins on [orgmode-nvim](https://github.com/topics/orgmode-nv
329364

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

332-
**NOTE**: None of the Emacs Orgmode plugins will be built into orgmode.nvim.
367+
**NOTE**: None of the Emacs Orgmode plugins will be built into nvim-orgmode.
333368
Anything that's a separate plugin in Emacs Orgmode should be a separate plugin in here.
334-
Point of this plugin is to provide functionality that's built into Emacs Orgmode core,
369+
The point of this plugin is to provide functionality that's built into Emacs Orgmode core,
335370
and a good foundation for external plugins.<br />
336371
If you want to build a plugin, post suggestions and improvements on [Plugins infrastructure](https://github.com/nvim-orgmode/orgmode/issues/26)
337372
issue.
@@ -358,22 +393,22 @@ make format
358393
```
359394

360395
### Parser
361-
Parsing is done via builtin tree-sitter parser and [tree-sitter-org](https://github.com/milisims/tree-sitter-org) grammar.
396+
Parsing is done via builtin treesitter parser and [tree-sitter-org](https://github.com/milisims/tree-sitter-org) grammar.
362397

363-
## Plans
398+
## Roadmap
364399
* [X] Support searching by properties
365400
* [ ] Improve checkbox hierarchy
366401
* [X] Support todo keyword faces
367402
* [X] Support clocking work time
368403
* [X] Improve folding
369404
* [X] Support exporting (via existing emacs tools)
370405
* [ ] Support archiving to specific headline
371-
* [ ] Support tables
406+
* [X] Support tables
372407
* [ ] Support diary format dates
373408
* [ ] Support evaluating code blocks
374409

375410
## Thanks to
376411
* [@dhruvasagar](https://github.com/dhruvasagar) and his [vim-dotoo](https://github.com/dhruvasagar/vim-dotoo) plugin
377412
that got me started using orgmode. Without him this plugin would not happen.
378-
* [@milisims](https://github.com/milisims) for writing a tree-sitter parser for org
413+
* [@milisims](https://github.com/milisims) for writing a treesitter parser for org
379414
* [vim-orgmode](https://github.com/jceb/vim-orgmode) for some parts of the code (mostly syntax)

0 commit comments

Comments
 (0)