*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
this is an observation
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 blah blah blah... 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, 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): - *i* toggles emphasis [vn] - *b* toggles bold [vn] - *`* toggles verbatim [vn] - *~~* toggles strikeout [vn] - *^* toggles superscript [vn] - *_* toggles subscript [vn] - *#* apply header (accepts a count) [n] - *hd* remove header [n] - *hn* move to next header [n] - *hb* move to previous header [n] - *hh* go to current header [n] - *hp* go to current header's parent [n] - *hsn* move to next sibling header [n] - *hsb* move to previous sibling header [n] - *hcf* move fo first child header [n] - *hcl* move to last child header [n] - *hcn* move to [count] nth child header [n] - ]] [count] sections forward (like 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] - *nr* insert a ref definition after this paragraph [n] - *rg* go to reference definition [n] - *rb* go back to reference label [n] - *gl* go to current link in current window - *sl* go to current link in split window - *gb* go back from link - *gB* go back from link to the previous file - *ln* move to next list item [n] - *lp* move to previous list item [n] - *ll* move to the current list item [n] - *llp* move to parent of the current list item [n] - *lsn* move to the next list item sibling [n] - *lsp* move to the previous list item sibling [n] - *lcf* move to the first list item child [n] - *lcl* move to the last list item child [n] - *lcn* move to the [count] nth list item child [n] - *cb* toggle checkbox or insert empty checkbox in list item [vn] - *cd* remove existing checkbox from list item [vn] For |#|, 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 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 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 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 (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 . 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 |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: >
test
< - *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 key. If '1', navigates and closes the TOC, 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