235 lines
8.8 KiB
Plaintext
235 lines
8.8 KiB
Plaintext
*org.txt* A minimal Org mode package providing only the necessities.
|
|
|
|
|
|
Org.vim Manual by Alex Vear~
|
|
|
|
|
|
Welcome to the org.vim user manual. *org* *org.vim* *vim-org* *outline*
|
|
|
|
1. Introduction ............................... |org-intro|
|
|
2. Installation ............................... |org-install|
|
|
3. Basic syntax ............................... |org-syntax|
|
|
4. Configuration .............................. |org-configuration|
|
|
5. Legal ...................................... |org-legal|
|
|
6. References ................................. |org-references|
|
|
|
|
==============================================================================
|
|
1. INTRODUCTION *org-intro*
|
|
|
|
Org.vim is a very minimal Org mode [2] and Outline mode [1] plugin for Vim
|
|
providing only syntax highlighting and folding.
|
|
|
|
This plugin aims to replicate Vim's existing Markdown editing experience on
|
|
Org mode (and Outline mode) files, rather than trying to be a full featured
|
|
Org mode plugin -- that is what Emacs is for.
|
|
|
|
==============================================================================
|
|
2. INSTALLATION *org-install*
|
|
|
|
Installation of Org.vim can be performed by using your favourite Vim
|
|
plugin/package management tool(s).
|
|
|
|
==============================================================================
|
|
3. BASIC SYNTAX *org-syntax*
|
|
|
|
Outline mode isn't used much anymore, one place it is still used is for GNU
|
|
Emacs release notes. It contains only a single piece of syntax: heading
|
|
levels denoted by asterisks.
|
|
>
|
|
* This is a heading
|
|
|
|
The first heading is equivalent to <h1> tags in HTML files.
|
|
|
|
** This is a sub-heading
|
|
|
|
This heading uses 2 asterisks to denote that it is a below the previous
|
|
heading.
|
|
|
|
*** This is a sub-sub-heading
|
|
|
|
* This is another top level heading
|
|
|
|
Org.vim supports as many heading levels as you want, and each of these
|
|
headings can use Vim's folding keys and fold navigation.
|
|
<
|
|
Org mode is a huge superset of Outline mode. It uses the same heading syntax
|
|
mentioned above, but supports many, many more features. Org.vim supports the
|
|
core subset of Org mode syntax, which should be suitable for most use cases.
|
|
|
|
The following is a short overview of essential Org mode syntax.
|
|
>
|
|
Org mode supports *bold*, /italic/, _underline_ and +strikethrough+ text
|
|
which is delimited by asterisks, forward-slashes, underscores, and pluses
|
|
respectively.
|
|
|
|
Paragraphs are separated by empty lines.
|
|
|
|
~monospaced~ and =verbatim= text are delimited by equals signs and tilde
|
|
respectively.
|
|
|
|
: Entire lines can be marked as verbatim by prepending with a colon.
|
|
|
|
# Comments are lines prepended with a hash.
|
|
|
|
This is a link to the Org.vim repository [[https://github.com/axvr/org.vim]]
|
|
|
|
This is also a link to the [[https://github.com/axvr/org.vim][Org.vim repository]]
|
|
where the text "Org.vim repository" is the title of the link (link text).
|
|
|
|
- This is an item in a list.
|
|
- This is another item in the same list.
|
|
- This is a sub-item for the above list item.
|
|
- This is a sub-item for the previous list item.
|
|
+ List items can also be denoted by using a plus sign
|
|
1. Or by numbering each item.
|
|
2. Like so.
|
|
- [ ] List items can also have checkboxes by using open and closing
|
|
square brackets.
|
|
- [X] By placing an uppercase X in between the square brackets you can
|
|
mark the item as "done".
|
|
<
|
|
Org.vim supports a lot more of Org mode's vast syntax than was mentioned here.
|
|
You can learn much more of Org mode's syntax online.
|
|
|
|
When Org.vim is installed, files ending with the extension `.org` will
|
|
automatically have syntax highlighting and folding support enabled. It can
|
|
also be manually enabled with the following command.
|
|
>
|
|
:set filetype=org
|
|
<
|
|
Outline mode doesn't have a file extension like Org mode so you will have to
|
|
enable it manually. This is simply done by opening the file and runing the
|
|
following command.
|
|
>
|
|
:set filetype=outline
|
|
<
|
|
==============================================================================
|
|
4. CONFIGURATION *org-configuration*
|
|
|
|
*org-folding*
|
|
|
|
To control how Org.vim handles folding, just use the standard Vim |folding|
|
|
options and commands.
|
|
|
|
For example if you want to enable or disable folding, use 'foldenable'.
|
|
>
|
|
autocmd FileType org,outline setlocal nofoldenable
|
|
<
|
|
Or if you want folding enabled and all folds opened by default, use
|
|
'foldlevelstart'.
|
|
>
|
|
autocmd FileType org,outline setlocal foldenable foldlevelstart=99
|
|
<
|
|
For more information on folding in Vim, refer to |fold.txt|.
|
|
|
|
------------------------------------------------------------------------------
|
|
*'b:org_state_keywords'* *'g:org_state_keywords'*
|
|
Value: list of strings~
|
|
Default: ['TODO', 'NEXT', 'DONE']~
|
|
|
|
To change the default state keywords set this variable to contain a list of
|
|
strings you would like to use.
|
|
>
|
|
let g:org_state_keywords = ['TODO', 'WAIT', 'DOING', 'DONE', 'CANCELED']
|
|
<
|
|
Note: state keywords are case sensitive.
|
|
|
|
State keywords can be set on specific buffers by using |'b:org_state_keywords'|
|
|
rather than |'g:org_state_keywords'|.
|
|
|
|
------------------------------------------------------------------------------
|
|
*'b:org_conceal_links'* *'g:org_conceal_links'*
|
|
Value: numeric~
|
|
Default: 1~
|
|
|
|
This option changes how Org mode links are rendered. If this option is
|
|
enabled, most of the link syntax will be collapsed to look as it would within
|
|
Emacs or a web browser; only showing the (underlined) link text.
|
|
>
|
|
[https://www.vim.org][Vim website] --> Vim website
|
|
<
|
|
When in insert mode with the cursor on that line, Vim will show the full link
|
|
syntax. This feature is enabled by default, however the way Vim treats
|
|
concealed text can be annoying, so it can be disabled.
|
|
|
|
To disable for all Org mode files, place the following line in your vimrc:
|
|
>
|
|
let g:org_conceal_links = 0
|
|
<
|
|
To disable for a specific file use this instead:
|
|
>
|
|
let b:org_conceal_links = 0
|
|
<
|
|
If you would like to modify how links are concealed, you can disable this
|
|
option, and manually set the |conceallevel| and |concealcursor| options from
|
|
an |autocmd| like so.
|
|
>
|
|
autocmd FileType org setlocal conceallevel=2 concealcursor=nc
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*'b:org_clean_folds'* *'g:org_clean_folds'*
|
|
Value: numeric~
|
|
Default: 0~
|
|
|
|
Vim's default styling for folds is quite ugly. Enabling this option will
|
|
remove much of the visual noise and suffix the folded heading text with an
|
|
ellipsis (`...`) making folds look the same as they do in Emacs' Org mode (and
|
|
Outline mode).
|
|
>
|
|
* Heading 1...
|
|
<
|
|
This option can be enabled for all buffers like so:
|
|
>
|
|
let g:org_clean_folds = 1
|
|
<
|
|
Alternatively it can be enabled for specific buffers:
|
|
>
|
|
let b:org_clean_folds = 1
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*'b:org_use_italics'* *'g:org_use_italics'*
|
|
Value: numeric~
|
|
Default: 1~
|
|
|
|
Display italic Org mode markup (e.g. `/this is italic Org mode markup/`) using
|
|
the italic variant of your font.
|
|
|
|
As some terminals, terminal multiplexers and monospaced fonts don't support
|
|
the use of italics, org.vim provides a mechanism to disable italic text.
|
|
|
|
To disable for all Org mode files place the following line in your vimrc:
|
|
>
|
|
let g:org_use_italics = 0
|
|
<
|
|
To disable italics only in a single buffer, use this instead:
|
|
>
|
|
let b:org_use_italics = 0
|
|
<
|
|
==============================================================================
|
|
5. LEGAL *org-legal*
|
|
|
|
Org.vim is based on the work of many other people (far too many to list here),
|
|
without them org.vim would not have been possible. The most notable of thse
|
|
works are:
|
|
|
|
* GNU Emacs' Outline mode [1].
|
|
* Carsten Dominik's Org mode [2].
|
|
|
|
Org.vim is distributed under the same terms as Vim itself.
|
|
|
|
Copyright (c) 2018-2020, Alex Vear.
|
|
|
|
A copy of the full licence text should have been provided with this extension
|
|
in the `LICENCE` file. The license can also be viewed on the web [3] or by
|
|
viewing the |license| section of the |uganda.txt| help doc from within Vim.
|
|
|
|
==============================================================================
|
|
6. REFERENCES *org-references*
|
|
|
|
[1]: <https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html>
|
|
[2]: <https://orgmode.org/>
|
|
[3]: <http://vimdoc.sourceforge.net/htmldoc/uganda.html#license>
|
|
|
|
------------------------------------------------------------------------------
|
|
vim:et:ts=4:sts=4:sw=4:tw=78:ft=help:norl:
|