250 lines
9.4 KiB
Plaintext
250 lines
9.4 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. Change log ................................. |org-changelog|
|
||
6. Legal ...................................... |org-legal|
|
||
7. 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|.
|
||
|
||
------------------------------------------------------------------------------
|
||
*org-conceal-links*
|
||
|
||
You can tell Vim to conceal links by using the built-in 'conceallevel' and
|
||
'concealcursor' options.
|
||
|
||
For example, you can make Vim collapse an Org mode link to look like it would
|
||
within Emacs or a Web browser (i.e. only showing the link title).
|
||
>
|
||
[[https://www.vim.org][Vim website]] --> Vim website
|
||
<
|
||
This is achieved with this |autocmd|:
|
||
>
|
||
autocmd FileType org setlocal conceallevel=2 concealcursor=nc
|
||
<
|
||
Note: long concealed text can act weird when "hard-wraping" text in Vim.
|
||
|
||
------------------------------------------------------------------------------
|
||
*'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_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. CHANGE LOG *org-changelog*
|
||
|
||
v1.2 [2020-02-15]~
|
||
|
||
* Improved syntax highlighting of links and turned off link concealing.
|
||
* Added |org_conceal_links| doc section on how turn on link concealing.
|
||
* Syntax highlight list item bullets and numbers.
|
||
* Make Vim correctly format lists without messing up indentation.
|
||
* Allow lower case in option keys and dynamic block markers.
|
||
* Remove a couple of unnecessary 'fillchars' rules.
|
||
* Minor README content update.
|
||
|
||
v1.1 [2020-01-05]~
|
||
|
||
* Added documentation on folding configuration (|org-folding|).
|
||
* Added 'g:org_clean_folds' option.
|
||
* Improved accuracy of in-line delimiter matching.
|
||
* Various minor documentation fixes.
|
||
* Rewrote README in Org mode.
|
||
* Enabled rendering of italics by default.
|
||
|
||
v1.0 [2019-09-28]~
|
||
|
||
* Initial stable release.
|
||
|
||
==============================================================================
|
||
6. 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.
|
||
|
||
==============================================================================
|
||
7. 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:
|