dotfiles/vim/plugged/vim-pandoc/doc/pandoc.txt

*pandoc.txt* Pandoc integration and utilities

Vim-pandoc provides facilities to integrate Vim with the |pandoc| document
converter and work with documents written in |pandoc's-markdown-variant|
variant (although textile documents are also supported). It is the main item
in |vim-pandoc-project|.

- *pandoc*:
    http://johnmacfarlane.net/pandoc/

- *pandoc's-markdown-variant*:
    http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown

- *vim-pandoc-project*:
    http://github.com/vim-pandoc

Vim-pandoc's goals are

 1) to provide advanced integration with pandoc,
 2) to offer a comfortable document writing environment,
 3) to allow great configurability.


CONTENTS                                                           *vim-pandoc*

- REQUIREMENTS |vim-pandoc-requirements|
- INSTALLATION |vim-pandoc-installation|
- SYNTAX |vim-pandoc-pandoc-syntax|
- MODULES |vim-pandoc-modules|
    - FORMATTING |vim-pandoc-formatting-module|
    - FOLDING |vim-pandoc-folding-module|
    - COMMAND |vim-pandoc-command-module|
      -- TEMPLATES |vim-pandoc-command-templates|
    - MENU |vim-pandoc-menu-module|
    - KEYBOARD |vim-pandoc-keyboard-module|
    - BIBLIOGRAPHIES |vim-pandoc-bibliographies-module|
    - COMPLETION |vim-pandoc-completion-module|
      --  AUTOCOMPLETE |vim-pandoc-complete-auto|
        -- DEOPLETE |vim-pandoc-complete-deoplete|
        -- NEOCOMPLETE |vim-pandoc-complete-neocomplete|
        -- NCM2 |vim-pandoc-complete-ncm2|
        -- NVIM-COMPLETION-MANAGER |vim-pandoc-complete-ncm|
        -- YOUCOMPLETEME |vim-pandoc-complete-youcompleteme|
        -- VIMCOMPLETESME |vim-pandoc-complete-vcm|
    - TOC |vim-pandoc-toc-module|
    - SPELL |vim-pandoc-spell-module|
    - HYPERTEXT |vim-pandoc-hypertext-module|
- CONFIGURATION
    - SETTINGS |vim-pandoc-settings|


REQUIREMENTS                                          *vim-pandoc-requirements*

* Vim 7.4
  Note: On vim versions < 7.4, some modules are automatically disabled (see
  |g:pandoc#modules#disabled|, but vim-pandoc is able to run in a degraded
  mode.
* python 3 support.
  Note: If python is not available, the features that require it are
  automatically disabled, allowing vim-pandoc to run in a degraded mode.
  However, vim-pandoc uses the new python API, so in versions under 7.4, even
  if python is available, some functions might not.

To check if the requirements are satisfied, check if

    :echo v:version >= 704 && has("python3")

outputs "1".

The warning message when modules are automatically disabled can be suppressed
by using
>
    let g:pandoc#modules#warn_disabled = 0


INSTALLATION                                          *vim-pandoc-installation*

The plugin follows the usual bundle structure, so it's easy to install it
using pathogen, Vundle or NeoBundle.

The most recent version is available at github. For those who need it, a
tarball is available from here.

- Using Vundle (recommended)

  Just add

    Plugin 'vim-pandoc/vim-pandoc'

  to your ~/.vimrc file and run :PluginInstall

NeoBundle users should replace `Plugin` in these instructions with
`NeoBundle`.

- Using Pathogen

    $ cd ~/.vim/bundle
    $ git clone git@github.com:vim-pandoc/vim-pandoc.git

- The repo is pathogen compatible and you can also just drop it in runtimepath.


SYNTAX                                               *vim-pandoc-pandoc-syntax*

vim-pandoc doesn't provide a syntax file for pandoc markdown files. Please
use https://github.com/vim-pandoc/vim-pandoc-syntax for this:

   Plugin 'vim-pandoc/vim-pandoc-syntax'

Note: this syntax file is used for both `markdown` and `pandoc` filetypes by
default, but you can opt out of it for markdown files by setting
|g:pandoc#filetypes#pandoc_markdown| to 0.

The reason we split the syntax file is it is much cleaner to track issues
separatedly. It also allows users not to use this syntax file if they want to
(notice that vim-pandoc-syntax is also configurable).


FILETYPES                                                *vim-pandoc-filetypes*

vim-pandoc is not a regular filetype plugin. Although it does define a
`pandoc` filetype, vim-pandoc can also attach to other filetypes, like
`markdown`, `rst` and `textile`. In that case, vim-pandoc uses the appropriate
filetype syntax file, but creates the Pandoc command and loads the extra
utilities. vim-pandoc also provides a convenience `beamer` filetype, that
simply clones the `pandoc` filetype. The `beamer` filetype is useful for
managing the behavior of |g:pandoc#command#autoexec_command| (see below). What
filetypes to attach to is determined by the value of the
|g:pandoc#filetypes#handled| variable.

Setting `pandoc#filetypes#pandoc_markdown` to 0 will disable all pandoc
functionality for markdown files, unless "pandoc" exists in the
`pandoc#filetypes#handled` array.

To enable pandoc functionality for markdown files while using  the markdown
filetype and syntax, use
>
     let g:pandoc#filetypes#handled = ["pandoc", "markdown"]
     let g:pandoc#filetypes#pandoc_markdown = 0

Note: vim-pandoc's developers mostly use pandoc's markdown syntax, so
coverage for it is more complete than for the other filetypes.

MODULES                                                    *vim-pandoc-modules*

vim-pandoc is split in several modules. They can be enabled and disabled
independently at startup, by adjusting the values of the
|g:pandoc#modules#enabled| and |g:pandoc#modules#disabled| variables.

For example, some people prefer not to use folds, so they would want to
disable the `folding` module, which creates folds for headers and some special
cases. To disable the module they should put

    let g:pandoc#modules#disabled = ["folding"]

in their .vimrc.

                                                      *vim-pandoc-modules-list*

Now, a description of the available modules

- FORMATTING                                     *vim-pandoc-formatting-module*

Handles basic writing settings, like the use of hard or soft line wraps. It is
recommended to leave this module enabled.

The module behavior is configured through the |g:pandoc#formatting#mode|
variable. For example, giving it the value 'ha' will enable hard breaks, and
autoformatting. The default is to use soft wraps. Some key maps are different
in soft and hard wrapping modes, see the info on the KEYBOARD module below.

If you use the hard wraps mode, you could want to adjust the textwidth value.
This can be done through the |g:pandoc#formatting#textwidth| variable, or
setting |textwidth| by hand.

A smart auto-formatting mode is provided, intended to use with the hard
wrapping mode. When enabled, (using the 'A' flag for
|g:pandoc#formatting#mode|), the plugin will be aware of what sort of block
the cursor is in and adjust |formatoptions| accordingly (so, for example,
headers won't be broken when they go beyond |textwidth|, and no autoformatting
will be used within codeblocks). Note this functionality requires the
|vim-pandoc-syntax| plugin to be installed, because it uses highlighting
information to work. By default, this kind of autoformatting is triggered on
entering and leaving insert mode, but it can be triggered when the cursor
moves in insert mode too if desired (it can be cleaner, although it might add
some lag), by setting |g:pandoc#formatting#smart_autoformat_on_cursormoved|.
The user can temporarily disable/enable this autoformatting feature on any
specific buffer by setting the value of *b:pandoc_autoformat_enabled* (which
can be done using the `pandoc#formatting#{Enable,Disable,Toggle}Autoformat()`
functions).

The formatting module also configures the program used for the |=| command,
which you can use to reformat your document (by default: wraps lines, returns
inline links and footnotes into reference links, etc.). This is configured
with the |g:pandoc#formatting#equalprg| and
|g:pandoc#formatting#extra_equalprg| variables. Please note that if you pass a
whole file through the default filter, it might delete some stuff, like LaTeX
macro definitions and title blocks.

- FOLDING                                            *vim-pandoc-folding-module*

Provides folding support for markdown and textile files.

The initial |'foldlevel'| is set with |g:pandoc#folding#level|. By default,
vim-pandoc will enable the |foldcolumn| with a width of 1. This can be
configured with the |g:pandoc#folding#fdc| variable.

As expected, folds are created for headers in markdown and textile files. The
folding level for the headers can be defined by two methods, configurable with
|g:pandoc#folding#mode|. The default mode, "syntax", uses the header syntax to
determine the level. So

    ### this is level 3
    #### this is level 4
    ###### this is level 6
    #### this is level 4
    # this is level 1

The "relative" mode counts the number of parents the header has, so

    ### this is level 1
    #### this is level 2
    ###### this is level 3
    #### this is level 2
    # this is level 1

The "stacked" mode counts all headers as first level, and it can be used to
view all the headers at once.

The mode can be changed on the fly using the *:PandocFolding* command which
takes as argument the options "syntax", "relative" and "stacked". If no
argument is given, then automatic folding will be disabled.

Besides this, some extensions are provided:

* If present, fold the document's YAML frontmatter (this is configurable with
  |g:pandoc#folding#fold_yaml|)
* The foldlevel for YAML frontmatter is 1 by default (this is configurable
  with |g:pandoc#folding#foldlevel_yaml|)
* Fold divs of the classes defined in |g:pandoc#folding#fold_div_classes|. For
  example, you might want to create notes for a presentation. pandoc
  understands

    <div class="notes">
    this is an observation
    </div foldend>

  is a note and will suppress it from the slides. Now, you might want to hide
  those while preparing the slides, and that's where this feature comes in
  handy (the `folding` module folds divs of the `notes` class by default, you
  can disable that clearing g:pandoc#folding#fold_div_classes).
  Note: You must add the `foldend` attribute to the closing `div` tag,
  otherwise the folding levels can get messed up.
* Fold in custom marked comments. For example, this will fold

    <!-- Custom fold fold-begin -->
    blah blah blah...
    <!-- fold-end -->

  Note: This also works in textile files, with `.. fold-begin` and `..
  fold-end`.
* Fold emulating vim's marker folding method (see 'foldmethod'). By default,
  this will only  work for marks within comments (see
  |g:pandoc#folding#markers_in_comments_only|).  For example,

  <!-- {{{3 -->
  this is a marked fold
  <!-- }}} -->

* Fold fenced codeblocks. By default, this is disabled, but can be turned on
  by setting |g:pandoc#folding#fold_fenced_codeblocks| to 1.
* To avoid the continuous recomputation of folds, in particular in insert mode,
  set |g:pandoc#folding#fastfolds| to 1 to defer it to the switches between
  insert and normal mode. For a plug-in that will make Vim recompute the folds
  only when need be, see https://github.com/konfekt/fastfold . This also
  disables the calculation of folds when using split windows, where the foldexpr
  function can get called many more times than usual.

- COMMAND                                            *vim-pandoc-command-module*

Note: Full functionality of this module requires python support.

The `command` module sets up a buffer-local *:Pandoc* command which handles
pandoc execution. This command builds an incantation for pandoc using
vim-pandocs configuration and the current state of the buffer
(bibliographies found, etc.).

The syntax of the :Pandoc command is as follows:

    :Pandoc[!] OUTPUT-FORMAT ARGS

Where OUTPUT-FORMAT is the value you would normally pass to the -t option in
pandoc, and ARGS are auxiliary arguments you want to pass pandoc. For example,

    :Pandoc beamer -Vlang:spanish

will create an incantation like:

    pandoc -t beamer -Vlang:spanish -o file.pdf file.pdc

:Pandoc will also use the value of |b:pandoc_biblio_bibs| to pass
`--bibliography` arguments, so the user shouldn't do that himself.

In nvim, vim-pandoc will open a terminal buffer and execute pandoc. If the
value of |g:pandoc#command#use_message_buffers| is 1 and some error occurred,
a buffer will open displaying the command output (this is unnecessary in nvim,
because it will always display the command output, so the default value for
`use_message_buffers' is 0). You can dismiss these buffers pressing 'q'.

Regardless of pandoc's execution status, the invocation used will be logged so
it can be checked using |:messages|.

If you write a bang ('!') after the command, vim-pandoc will try to open
the created file in its associated program. This behavior can be customized
through the |g:pandoc#command#custom_open| variable. The
 |g:pandoc#command#prefer_pdf| variable controls whether to prefer pdf files,
 if they exist.

Note: The pandoc execution is performed asynchronously if vim supports the
|clientserver| feature and the running instance is a valid server (this is the
default for gvim, but must be made explicit when running in a terminal, see
|x11-clientserver|). This feature also requires python to be available in the
system.

The :Pandoc command has argument completion for supported output formats and
pandoc option arguments.

Note: Previously, vim-pandoc used the executors system present in
vim-pandoc, which allowed for the execution of command pipelines. This is no
longer supported. If you want to pass the file through a filter, use pandoc's
-F option.

As a convenience, you can have vim-pandoc auto execute pandoc on writes. To
enable this functionality, set |g:pandoc#command#autoexec_on_writes| to 1 and
provide a command to execute like so:

    let |g:pandoc#command#autoexec_command| = "Pandoc! pdf"

You can use different commands for different filetypes, if needed. For example,

    autocmd FileType beamer let |g:pandoc#command#autoexec_command| = "Pandoc! beamer"
    autocmd FileType pandoc let |g:pandoc#command#autoexec_command| = "Pandoc! pdf"

You can also use a buffer local variable if you want to override the global
setting.

    let |b:pandoc_command_autoexec_command| = "Pandoc! html"

Notice that vim-pandoc also defines and sets a 'compiler' pandoc that can be
started by ':make' or ':lmake' and compiles the current file by pandoc.

                                                                *Pandoc-native*
If you vim doesn't have support for python, you can still use a limited
version of the Pandoc command, however this will not support autocompletion,
the convenience abbreviations or the ability to open the file after compiling
(these features might be supported in the feature). Thus, instead of

    Pandoc pdf

you would need to issue

    Pandoc -o myfile.pdf


-- TEMPLATES                                     *vim-pandoc-command-templates*

It might get tedious to reuse the same arguments over and over. For example,
the user might frequently execute

    :Pandoc! pdf -Vdocumentclass=memoir -Vdocumentclassoptions=article -Vmainfont='GFS Bodoni'

He can save this incantation as a 'template', so later he could simply run

    :Pandoc! #my_usual_article

Note: templates don't record if a bang was used for the Pandoc command, so once
#my_usual_article is defined, both ':Pandoc #my_usual_article' and ':Pandoc!
#my_usual_article' are possible.

                                                              *:PandocTemplate*
To save the latest :Pandoc incantation as a template, the user should execute

    :PandocTemplate save my_usual_article

It is also possible to save a custom incantation like this

    :PandocTemplate save fancy_article pdf -Vdocumentclass=memoir -Vmainfont='Helvetica Neue'

To review some template, use

    :PandocTemplate get my_usual_article

which should output the template definition.

- MENU                                                   *vim-pandoc-menu-module*

Creates a menu for pandoc handled files. If the `command` module is enabled,
you can build your documents from it.

- KEYBOARD                                           *vim-pandoc-keyboard-module*

Registers custom mappings for applying text styles, navigating the documents
and more. To keep things neat, this module loads mappings from submodules.
|g:pandoc#keyboard#enabled_submodules| determines which of those are enabled.
The default mappings can be disabled as a whole setting
|g:pandoc#keyboard#use_default_mappings| to 0. The mappings for individual
modules can be disabled using |g:pandoc#keyboard#blacklist_submodule_mappings|.

This is list of the mappings currently implemented (in brackets, the modes
where they are available):

- *<localleader>i*     toggles emphasis [vn]
- *<localleader>b*     toggles bold [vn]
- *<localleader>`*     toggles verbatim [vn]
- *<localleader>~~*    toggles strikeout [vn]
- *<localleader>^*     toggles superscript [vn]
- *<localleader>_*     toggles subscript [vn]
- *<localleader>#*     apply header (accepts a count) [n]
- *<localleader>hd*    remove header [n]
- *<localleader>hn*    move to next header [n]
- *<localleader>hb*    move to previous header [n]
- *<localleader>hh*    go to current header [n]
- *<localleader>hp*    go to current header's parent [n]
- *<localleader>hsn*   move to next sibling header [n]
- *<localleader>hsb*   move to previous sibling header [n]
- *<localleader>hcf*   move fo first child header [n]
- *<localleader>hcl*   move to last child header [n]
- *<localleader>hcn*   move to [count] nth child header [n]
- ]]                 [count] sections forward (like <localleader>hn) [n]
- [[                 [count] sections backwards [n]
- ][                 [count] move to the next section end [n]
- []                 [count] move to the previous section end [n]
- aS                 select a section, including header [vo]
- iS                 select a section, excluding header [vo]
- *<localleader>nr*    insert a ref definition after this paragraph [n]
- *<localleader>rg*    go to reference definition [n]
- *<localleader>rb*    go back to reference label [n]
- *<localleader>gl*    go to current link in current window
- *<localleader>sl*    go to current link in split window
- *<localleader>gb*    go back from link
- *<localleader>gB*    go back from link to the previous file
- *<localleader>ln*    move to next list item [n]
- *<localleader>lp*    move to previous list item [n]
- *<localleader>ll*    move to the current list item [n]
- *<localleader>llp*   move to parent of the current list item [n]
- *<localleader>lsn*   move to the next list item sibling [n]
- *<localleader>lsp*   move to the previous list item sibling [n]
- *<localleader>lcf*   move to the first list item child [n]
- *<localleader>lcl*   move to the last list item child [n]
- *<localleader>lcn*   move to the [count] nth list item child [n]
- *<localleader>cb*    toggle checkbox or insert empty checkbox in list item [vn]
- *<localleader>cd*    remove existing checkbox from list item [vn]

For |<localleader>#|, you can decide what header style to use (always atx, use
setex, append hashes at the end) by setting the
|g:pandoc#keyboard#sections#header_style| variable.

Some of the reference-related mappings use |mark-motions|. You can configure
what mark to use by setting the value of |g:pandoc#keyboard#references#mark|,
in case the default ("r") is not suitable or needs to serve a different
purpose.

Some key mappings are affected by the editing mode (soft/hard wraps). In soft
mode, vim-pandoc maps j and k to move across visible lines, not real ones, to
ease navigation. This is controlled by the |g:pandoc#keyboard#display_motions|
variable.

- BIBLIOGRAPHIES                               *vim-pandoc-bibliographies-module*

Note: This module requires python support.

Provides with support for bibliographic info completion and retrieval, and
also populates the |b:pandoc_biblio_bibs| variable, which the |:Pandoc|
command uses to build up the pandoc incantation.

vim-pandoc can handle BibTeX, RIS, MODS and JSON bibliographies.

The way the module populates the b:pandoc_biblio_bibs variable is determined
by the value of the |g:pandoc#biblio#sources| variable. Depending on it, the
module will gather bibliographies on the following order (between brackets,
the corresponding flag to give g:pandoc#biblio#sources):

1) [b] Search for any bibliography that shares the name of the current file in the
   current directory.
   So, if the document is named `paper.mkd`, it will look for `paper.bib`,
   `paper.ris`, and so on.
2) [c] Search for any bibliography in the current dir.
3) [l] Search for default bibliographies (`default.bib`, `default.ris`, etc.) in pandoc's
    data dir ("$HOME/.pandoc/" in *nix, "%APPDATA%/pandoc/" in Windows)
4) [t] Search for bibliographies in the local texmf tree (requires the
   `kpsewhich` program)
5) [g] Add any bibliographies listed in |g:pandoc#biblio#bibs|.
6) [y] Add any bibliographies specified in a YAML header.
7) [G] Add any bibliographies in the current git repository.

The default flags are "bcgyG". For the 'c', 'l', and 't' flags, the
|g:pandoc#biblio#bib_extensions| is taken into account. You can, of
course, modify the value of |b:pandoc_biblio_bibs| at any time.

The `bibliographies` module also provides the functions that allow the
`completion` module to give suggestions for citation keys (see below).

By default, this will only return matches for citekeys, but it is possible to
retrieve suggestions that match in any key by using the bibtool program. So,
if you are matching from

    @armstrong

you might retrieve both

    @armstrong1989    Armstrong, David M. - A Combinatorial Theory of Possibility
    @lewis1992        Lewis, David - Armstrong on Combinatorial Possibility

This is off by default, but can be turned on (if `bibtool` is available) by
setting the |g:pandoc#biblio#use_bibtool| variable to 1.

You can pass extra arguments to `bibtool` by setting
|g:pandoc#biblio#bibtool_extra_args|. The default is "-r biblatex", which
enables support for biblatex bibliographies (bibtex bibliographies will still
work).

TIP: If you use unite.vim, you might want to check https://github.com/msprev/unite-bibtex

- YAML                                                 *vim-pandoc-yaml-module*

This module gathers data from YAML headers, if present, and keeps it in the
*b:pandoc_yaml_data* variable. Other modules might be configured using this.

- COMPLETION                                     *vim-pandoc-completion-module*

Provides |omni-completion|. If the `bibliographies` module is active, it will
complete bibliographic references from the bibliography sources defined in
|g:pandoc#biblio#sources|.

The bibliographic completion has two backends, selected with the
|g:pandoc#completion#bib#mode| variable, 'fallback' and 'citeproc'. 'fallback'
uses internal information extractors for bibtex, ris and json bibliographies,
and 'citeproc' uses pandoc-citeproc for additional bibliography database types
and extra features. The 'citeproc' backend is experimental for now, but it is
planned to become the default in the future.

To use completion, start typing a citekey, e.g.,

    @geac

and then, while still in insert mode, hit CTRL-X CTRL-O (vim's shortcut
for |omni-completion|), and you'll get a popup window with a list of
matching keys, e.g.,

    @geach1970   Geach, P. T. – Entailment
    @geach1972   Geach, P. T. – Logic Matters

Regular expressions work too:

    @le.*90

should suggest both '@leftow1990' and '@lewis1990', assuming those are
both keys in your bibliography.

Tip: If you only want to complete from a list of citations, you could
create a file (let's say, `citations.dict`) that contains such a list, one
item at a time:

    @adams1967a
    @adams1971
    @adams1972a
    @adams1974
    @adams1977
    @adams1986a

and then add it to vim's |`dictionary`|, like so

    setlocal dictionary="citations.dict"

Then, you can complete from this list by pressing CTRL-X CTRL-K.

If the 'citeproc' backend is used, extra information can be displayed in the
preview window, depending on the value of
|g:pandoc#completion#bib#use_preview|.

-- AUTOCOMPLETE                                        *vim-pandoc-complete-auto*

Vim does not provide automatic completion by itself, but there exist several
plugins that provide this: |deoplete|, |neocomplete|, |ncm2|,
|nvim-completion-manager|, and |youcompleteme|. There is also |vimcompletesme|
that overrides <tab> to trigger different built-in completions, such as
the omni-completion by |vim-pandoc|, depending on the context. See below for
descriptions on how to set some of these up with |vim-pandoc|.

-- DEOPLETE                                        *vim-pandoc-complete-deoplete*

|deoplete| is a moder remake of |neocomplete|, and was originally written
specifically for Neovim, see here: https://github.com/Shougo/deoplete.nvim. It
is a highly customizable and flexible completion manager.

To configure for `vim-pandoc`, one may use: >

  " This is new style
  call deoplete#custom#var('omni', 'input_patterns', {
    \ 'pandoc': '@'
    \})

  " This is old style (deprecated)
  if !exists('g:deoplete#omni#input_patterns')
    let g:deoplete#omni#input_patterns = {}
  endif
  let g:deoplete#omni#input_patterns.pandoc = ['@']
<

-- NEOCOMPLETE                                  *vim-pandoc-complete-neocomplete*

|neocomplete| is also a flexible automatic completion engine for vim, although
active development has been stopped. Users are recommended to change to
|deoplete|, see also |vim-pandoc-complete-deoplete|. The plugin is available
here: https://github.com/Shougo/neovomplete.vim.

The following options may be used to enable automatic completion for pandoc
documents with |neocomplete| and `vim-pandoc`s omni completion function: >

  if !exists('g:neocomplete#sources#omni#input_patterns')
    let g:neocomplete#sources#omni#input_patterns = {}
  endif
  let g:neocomplete#sources#omni#input_patterns.pandoc =
    \ '@'

<

-- NCM2                                                *vim-pandoc-complete-ncm2*

|ncm2| is a modern remake and replacement of |nvim-completion-manager| and is
supposed to be a "Slim, Fast and Hackable Completion Framework for Neovim":
https://github.com/ncm2/ncm2

The following simple configuration should work well with `vim-pandoc`: >

  " include the following plugins (here using junnegun/vim-plug)
  Plug 'roxma/nvim-yarp'
  Plug 'ncm2/ncm2'

  augroup my_cm_setup
    autocmd!
    autocmd BufEnter * call ncm2#enable_for_buffer()
    autocmd Filetype pandoc call ncm2#register_source({
      \ 'name': 'pandoc',
      \ 'priority': 8,
      \ 'scope': ['pandoc'],
      \ 'mark': 'md',
      \ 'word_pattern': '\w+',
      \ 'complete_pattern': ['@'],
      \ 'on_complete': ['ncm2#on_complete#omni', 'pandoc#completion#Complete'],
      \ })
  augroup END

<

-- NVIM-COMPLETION-MANAGER                              *vim-pandoc-complete-ncm*

Note: |nvim-completion-manager| has been replaced by |ncm2|, and users are
recommended to change. See |vim-pandoc-compete-ncm2| for hints on how to setup
|ncm2| for |vim-pandoc|.

|nvim-completion-manager| is a fast, extensible, async completion framework
for neovim (and Vim version 8.0 and above). The project is available here:
https://github.com/roxma/nvim-completion-manager

To configure for `vim-pandoc`, one can use the following code: >

  augroup my_cm_setup
    autocmd!
    autocmd User CmSetup call cm#register_source({
      \ 'name': 'pandoc',
      \ 'priority': 8,
      \ 'scoping': 1,
      \ 'scopes': ['pandoc'],
      \ 'abbreviation', 'md',
      \ 'cm_refresh_patterns': ['@'],
      \ 'cm_refresh: {'omnifunc': 'pandoc#completion#Complete'},
      \ })
  augroup END

<

-- YOUCOMPLETEME                              *vim-pandoc-complete-youcompleteme*

|youcompleteme| is probably the most popular code-completion engine for Vim.
The github repository is here: https://github.com/Valloric/YouCompleteMe.
It is described as:

> YouCompleteMe is a fast, as-you-type, fuzzy-search code completion engine
> for Vim. It has several completion engines: an identifier-based engine that
> works with every programming language, a semantic, Clang [3]-based engine
> that provides native semantic code completion for the C-family languages,
> a Jedi [4]-based completion engine for Python, an OmniSharp [5]-based
> completion engine for C# and an omnifunc-based completer that uses data from
> Vim's omnicomplete system to provide semantic completions for many other
> languages (Ruby, PHP etc.).

To enable automatic completion with |youcompleteme| for `vim-pandoc`, use the
following options: >

  if !exists('g:ycm_semantic_triggers')
    let g:ycm_semantic_triggers = {}
  endif
  let g:ycm_semantic_triggers.pandoc = ['@']

  let g:ycm_filetype_blacklist = {}
<

-- VIMCOMPLETESME                                       *vim-pandoc-complete-vcm*

A plugin that maps <tab> to trigger the built-in completion that is most
suitable to the current context. The plugin is available here:
https://github.com/ajh17/VimCompletesMe.

The following options may be used to enable completion with the <tab> trigger
for pandoc documents with |vimcompletesme| and `vim-pandoc`s omni completion
function: >

  augroup VimCompletesMePandoc
    autocmd!
    autocmd FileType pandoc
      \ let b:vcm_omni_pattern = '@'
  augroup END

<

- TOC                                                     *vim-pandoc-toc-module*

Provides the *:TOC* command, which displays a table of contents for the
current file using vim's location list system. The position of the TOC window
is configured by the |g:pandoc#toc#position| variable.

When the user presses <CR> (the Enter key) in the TOC buffer, the cursor is
moved in the source window to the position selected. By default, the TOC
buffer is closed after this, but this can be circumvented by pressing <C-CR>.
This behavior can be reversed by setting |g:pandoc#toc#close_after_navigating|
to 0.

The indentation in the TOC buffer can be tuned by |g:pandoc#toc#shift|
variable, which definds the shift in number of spaces per level.

- SPELL                                                *vim-pandoc-spell-module*

Sets up spelling for files handled by vim-pandoc. Spelling is on by default,
but can be changed with the |g:pandoc#spell#enabled| variable. The user can
also specify what languages to use by default with the
|g:pandoc#spell#default_langs| variable.

- HYPERTEXT                                        *vim-pandoc-hypertext-module*

Adds some basic hypertext functions. Files and addresses can be opened in
system defined applications by pressing `gx`, or within vim, if possible, by
pressing `gf`.

Let's suppose you are editing the file "notes.md" with the contents:

     #) [important thing to do](important.html)
     #) [another thing to do](another.html)

and the files "important.md" and "another.md" are available. Pressing `gf`
over "important.html" will open "important.md" within the current vim instance
(this behavior of opening alternate files can be disabled by setting
|g:pandoc#hypertext#open_editable_alternates| to 0). `gx` would open
"important.html" in the browser, if the file existed.

See ||g:pandoc#hypertext#open_cmd| and |g:pandoc#hypertext#preferred_alternate| for
info on how to configure this modules's behavior.

There's an addition keyboard shortcut for following the link at cursor,
support `automatic link`, `inline link`, `reference link` and `images`. When
you press the shortcut, it will try to get the link address at cursor, and
then open it by VIM or system application. If the link address starts with a
`#`, then it will be treated as an header ID, and then will try to move the
cursor to specified header.
After moving, you can use |<localleader>gb| to move back to that link.

See |vim-pandoc-keyboard-module| ro detail.

SETTINGS                                                   *vim-pandoc-settings*

Module configuration variables defaults are initialized when the modules
themselves are initialized. This is so the global variable scope is not
cluttered with unused variables for users who have disabled some modules.

A description of the available configuration variables follows:

- *g:pandoc#filetypes#handled*
  default = ["pandoc", "rst", "textile"]
  	     + ["markdown"] (if |g:pandoc#filetypes#pandoc_markdown| is 1)

  A list of the kinds of files vim-pandoc will attach to. 'extra' includes
  .text and .txt files. For what values are valid here, see the
  pandoc_extensions_table variable in plugin/pandoc.vim

- *g:pandoc#filetypes#pandoc_markdown*
  Default = 1

  Should we set the pandoc filetype (and load vim-pandoc-syntax) for common
  markdown extensions (*.md, *.mkd, etc)? Since regular markdown and pandoc's
  markdown variant differ, someone might want to restrict those extensions to
  regular markdown. In that case, we use vim's default syntax highlighting for
  markdown. See |g:pandoc#filetypes#handled| above.

- *g:pandoc#modules#enabled*

  default = ["formatting", "folding", "bibliographies", "completion",
  "metadata", "menu", "executors", "keyboard", "toc", "spell", "hypertext"]

  A list of the modules to enable on the files determined by
  |g:pandoc#filetypes#handled|. See |vim-pandoc-modules|.

- *g:pandoc#modules#disabled*

  default = [], (["bibliographies", "command"] in vim < 7.4)

  Auxiliary module blacklist.

- *g:pandoc#formatting#mode*
  default = "s"

        h: use hard wraps
        a: autoformat
        A: smart autoformatting
        s: use soft wraps

- *g:pandoc#formatting#textwidth*
  default = 79

  Default textwidth, used for hard wraps mode. This is used by the default equalprg
  setting, so it must be set before it.

- *g:pandoc#formatting#smart_autoformat_on_cursormoved*
  default = 0

  Trigger smart autoformatting when moving the cursor in insert mode. If
  enabled, it might cause some lag.

- *g:pandoc#formatting#equalprg*
  default = "pandoc -t markdown [--columns {g:pandoc#formatting#textwidth}|--wrap=none]"

  What command to use for equalprg. If set to '', vim's default will be used.
  See |'equalprg'|.
  NOTE the default changes depending on whether the formatting mode uses hard
  or soft wraps.

- *g:pandoc#formatting#extra_equalprg*
  default = "--reference-links"

  Extra arguments to append to the value of equalprg. Useful when the default
  behavior of |g:pandoc#formatting#equalprg| wants to be preserved.

- *g:pandoc#command#use_message_buffers*
  default = 1

  Whether to display pandoc's output in a message buffer after execution.

- *g:pandoc#command#latex_engine*
  default = "xelatex"

  The LaTeX engine to use with pandoc. 'xelatex' is the default for greater
  unicode compatibility.

- *b:pandoc_command_latex_engine*
  default = None

  As |g:pandoc#command#latex_engine|, but for the current file.

- *g:pandoc#command#path*
  default = "pandoc"

  The name of the pandoc command. Can also be an absolute path if the program
  is not located in the $PATH.

- *g:pandoc#command#custom_open*
  default = ""

  A function to be used to open the created file. This function must take an
  argument, for the path of the file created, and return a string with the
  command that should open the file. For example: >

    let g:pandoc#command#custom_open = "MyPandocOpen"

	function! MyPandocOpen(file)
		let file = shellescape(fnamemodify(a:file, ':p'))
		let file_extension = fnamemodify(a:file, ':e')
		if file_extension is? 'pdf'
			if !empty($PDFVIEWER)
				return expand('$PDFVIEWER') . ' ' . file
			elseif executable('zathura')
				return 'zathura ' . file
			elseif executable('mupdf')
				return 'mupdf ' . file
			endif
		elseif file_extension is? 'html'
			if !empty($BROWSER)
				return expand('$BROWSER') . ' ' . file
			elseif executable('firefox')
				return 'firefox ' . file
			elseif executable('chromium')
				return 'chromium ' . file
			endif
		elseif file_extension is? 'odt' && executable('okular')
			return 'okular ' . file
		elseif file_extension is? 'epub' && executable('okular')
			return 'okular ' . file
		else
			return 'xdg-open ' . file
		endif
	endfunction
<
- *g:pandoc#command#prefer_pdf*
   default = 0

   Open a pdf file preferrably, if it exists.

- *g:pandoc#command#autoexec_on_writes*
  default = 0

  Execute a command automatically on writes.

- *g:pandoc#command#autoexec_command*
  default = ''

  Which command to autoexecute on writes if
  |g:pandoc#command#autoexec_on_writes| is enabled.

- *b:pandoc_command_autoexec_command*
  default = unset

  Buffer-local override for |g:pandoc#command#autoexec_command|.

- *g:pandoc#command#templates_file*
  default = split(&runtimepath, ",")[0]."/vim-pandoc-templates"

  Where to save and retrieve command templates.

- *g:pandoc#compiler#command*
  default = "{g:pandoc#command#path}"

  The name of the command invoked in |:Pandoc|. Can also be an absolute path
  if the program is not located in the $PATH.

  The difference to |g:pandoc#command#path| is that the latter is used for
  internal purposes. For example, if you want to use Panzer: >

    let g:pandoc#compiler#command = "panzer"
<
- *g:pandoc#compiler#arguments*
  default = ''

  Additional arguments for the command invoked in |:Pandoc|.
  For example, if you're using Panzer this setting is recommended: >

    let g:pandoc#compiler#arguments = "---quiet ---strict"
<
- *g:pandoc#biblio#sources*
  default = "bcgy"

  Where to look for bibliographies:

    b: use files with the same name as the current file, in the working dir
    c: use any bibliography in the working dir
    l: look in pandoc's local dir
    t: look in the local texmf tree
    g: append items in |g:pandoc#biblio#bibs|
    y: look in the current file's YAML header

- *g:pandoc#biblio#bib_extensions*
  default = ["bib", "bibtex", "ris", "mods", "enl", "wos", "medline", "copac"]

  What extensions to use for 'c', 'l', and 't' values in
  |g:pandoc#biblio#sources|.

- *g:pandoc#biblio#bibs*
  default = []

  A list of bibliographies to use globally if 'g' is in
  |g:pandoc#biblio#sources|.

- *b:pandoc_biblio_bibs*
  default = []

  Extra bibliographies to use for the |:Pandoc| command, local to the buffer.

- *g:pandoc#biblio#use_bibtool*
  default = 0

  Use bibtool for queries, if available (might help performance).

- *g:pandoc#completion#bib#mode*
  default = 'fallback'

  Which backend to use for retrieving bibliographic information. 'fallback'
  uses internal implementations for bibtex, ris, mods and json files.
  'citeproc' uses pandoc-citeproc for support of additional bibliography types
  and extra features. Note: The 'citeproc' backend is experimental for now,
  but will become the default in the future.

- *g:pandoc#completion#bib#use_preview*
  default = 1

  Should extra bibliographic completion information be displayed in the
  |preview-window|? Requires the 'citeproc' backend.

- *g:pandoc#keyboard#enabled_submodules*
  default = ["lists", "references", "styles", "sections", "links", "checkboxes"]

  What mapping groups to enable.

- *g:pandoc#keyboard#display_motions*
  default = 1

  Use display motions when using the soft wrap mode.

- *g:pandoc#keyboard#wrap_cursor*
  default = 0

  Wrap the cursor around line boundaries (see |onemore|)

- *g:pandoc#keyboard#references#mark*
  default = "r"

  What mark to use (i.e, when navigating references, to keep track of original
  position).

- *g:pandoc#keyboard#sections#header_style*
  default = "a"

  What style to use when applying headers. Default is to use atx headers
  everywhere. "s" enables setext headers for level 1 and 2 headers, "2"
  appends atx marks at both ends of the header.

- *g:pandoc#keyboard#use_default_mappings*
  default = 1

  Use default mappings. Otherwise, the user should provide his own.

- *g:pandoc#keyboard#blacklist_submodule_mappings*
  default = []

  A list of submodules of the keyboard module whose mappings should be
  disabled. Allows finer handling of default mappings than
  |g:pandoc#keyboard#use_default_mappings|.

- *g:pandoc#folding#level*
  default = &foldlevel

  The value of |'foldlevel'| for opened files.

- *g:pandoc#folding#fdc*
  default = 1

  Width of the window's |foldcolumn|. To disable, set to 0.

- *g:pandoc#folding#mode*
  default = 'syntax'

  How to decide what level the headers are. Default value follows syntax
  rules, 'relative' uses information about the header parents. For example, in
  this document >

      ## header

      blah blah

      #### header

      blah blah blah
<
  the level of "## header" is 2 using the default method, but 1 using
  relative, and the level of "#### header" is 4 using the default method, but
  2 using relative.

  'stacked' takes all headers as first level.

- *g:pandoc#folding#fold_yaml*
  default = 0

  Fold YAML frontmatters.

- *g:pandoc#folding#foldlevel_yaml*
  default = 1

  Foldlevel for YAML frontmatters.

- *g:pandoc#folding#fold_div_classes*
  default = ["notes"]

  What div classes to fold. NOTE: you need to end the folds using the
  `foldend` attribute in the closing tag, like so: >

      <div class="notes">
      test
      </div foldend>
<
- *g:pandoc#folding#fastfolds*
  default = 0

  Defer recomputation of folds to the switches between insert and normal mode.
  For a plug-in that will make Vim recompute the folds only when need be, see
  https://github.com/konfekt/fastfold

- *g:pandoc#folding#fold_vim_markers*
  default = 1

  Emulate vim's "marker" foldmethod.

- *g:pandoc#folding#vim_markers_in_comments_only*
  default = 1

  Only emulate marker foldmethod for marks inside HTML comments.

- *g:pandoc#folding#fold_fenced_codeblocks*
  default = 0

  Fold fenced codeblocks.

- *b:pandoc_folding_basic*
  buffer local. default = 0

  When set, forces vim-pandoc to use basic folding in the current buffer.

- *g:pandoc#toc#position*
  default = "right"

  Where to show the TOC window. Can be "top", "left", "right", "bottom".

- *g:pandoc#toc#close_after_navigating*
  default = 1

  Must the TOC window close after selecting a location? This also controls the
  behavior of the <CR> key. If '1', <CR> navigates and closes the TOC, <C-CR>
  simply navigates. If '0', this behavior is reversed.

- *g:pandoc#toc#shift*
  default = 2

  Defines the number of spaces per level to indent the higher level
  positions in TOC buffer.

- *g:pandoc#spell#enabled*
  default = 1

  Enable spelling for files handled by vim-pandoc.

- *g:pandoc#spell#default_langs*
  default = []

  What languages to use for spelling by default for files handled by
  vim-pandoc.

- *g:pandoc#hypertext#open_editable_alternates*
  default = 1

  If opening locally files matching
  |g:pandoc#hypertext#editable_alternates_extensions|, try to open a vim
  editable file instead. For example, if you try to open "test.html" and
  "test.md" is available in the same folder, vim will try to edit "test.md".

- *g:pandoc#hypertext#editable_alternates_extensions*
  default = '\(pdf\|htm\|odt\|doc\)'

  A regular expression determining for what files a vim editable file
  should be opened instead when opening locally.

- *g:pandoc#hypertext#preferred_alternate*
  default = "md"

  What alternate extension should be preferred, for cases where several
  editable files are available when opening locally and
  |g:pandoc#hypertext#open_editable_alternates| is 1.

- *g:pandoc#hypertext#split_open_cmd*
  default = "botright vsplit"

  How to split-open files within vim.

- *g:pandoc#hypertext#edit_open_cmd*
  default = "edit"

  How to edit-open files within vim.

- *g:pandoc#hypertext#autosave_on_edit_open_link*
  default = 0

  Automatically save the current file when following some link in the same
  window for editing.

- *g:pandoc#hypertext#create_if_no_alternates_exists*
  default = 0

  When open the link at cursor, and it does not exist, set this to `1` to
  automatically create the file with the given extension or the extension of
  |g:pandoc#hypertext#preferred_alternate|.

  To use this for alternate files, the value of
  |g:pandoc#hypertext#open_editable_alternates| should be 1.

- *g:pandoc#hypertext#use_default_mappings*
  default = 1

  Use default mappings.

FAQ                                                           *vim-pandoc-faq*

Q: On opening a pandoc file the current work dir is not that of the file,
   what's wrong?

A: Add to your `vimrc` the line
>
  autocmd FileType pandoc :lchdir %:p:h
<
  As a possible alternative, see also *autochdir* and the plug-in
>
  https://github.com/fmoralesc/vim-extended-autochdir
<
Q: Editing text is laggy. What's wrong?

A: See |g:pandoc#folding#fastfolds|.

CONTRIBUTE                                              *vim-pandoc-contribute*

vim-pandoc welcomes any contribution, in the form of bug reports, patches,
code, suggestions, etc. To do so, please open an issue in our issue tracker on
Github at https://github.com/vim-pandoc/vim-pandoc/issues or email the
maintainer (see below). See also |vim-pandoc-devel| for documentation.

WHO                                                            *vim-pandoc-who*

The current vim-pandoc's maintainer is Felipe Morales (fmoralesc), whom you
can reach at hel.sheep@gmail.com

vim-pandoc is the fruit of the labor of a bunch of people. It includes, in one
shape or the other, the work of dsanson, lyokha, jtanguy, tlvince, ehamberg,
blaenk, gokcechan, shelhamer, clvv, PiPeep, mwhite, wunki, ulel, lyeoh, ulel,
felixSchl, zmanji, lmullen, Propatsch, ivotron, tpoisot, 00Davo. We have
borrowed from Jeremy Schultz, plasticboy and cirosantilli, too. Many thanks to
all of them.

vim:tw=78:ts=8:noet:ft=help:fdm=marker