*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*

                               *'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_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-2019, 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: