*asciidoctor.txt*  Vim :heart: Asciidoctor

Author:  Maxim Kim <https://habamax.github.io>
URL:     https://github.com/habamax/vim-asciidoctor
License: MIT


INTRODUCTION                                                     *asciidoctor*


Vim has syntax highlighting for asciidoc out of the box. And it is/was really
slow for me, probably because it tries to be very smart about syntax.

This plugin:

    - has different syntax highlighting;
    - is way faster (your vim lags less :) );
    - has folding;
    - has commands to compile documents (html, pdf, docx).


SETTINGS                                                *asciidoctor-settings*

It should work out of the box (at least it was the intention). But sometimes
one needs settings to set.


*g:asciidoctor_executable*            What to use for HTML.
                                    Default: asciidoctor
  Example: >

  let g:asciidoctor_executable = '~/projects/asciidoctor/bin/asciidoctor'


*g:asciidoctor_extensions*            What extensions to use with HTML.
                                    Default: []
  Example: >

  let g:asciidoctor_extensions = ['asciidoctor-diagram', 'asciidoctor-rouge']


*g:asciidoctor_css_path*              Path to custom CSS to use with HTML.
                                    Default: ''
  Example: >

  let g:asciidoctor_css_path = '~/docs/ascidoctor-themes/'


*g:asciidoctor_css*                   Custom CSS file name to use with HTML.
                                    Default: ''
  Example: >

  let g:asciidoctor_css = 'mytheme.css'


*g:asciidoctor_pdf_executable*        What to use for PDF.
                                    Default: asciidoctor-pdf
  Example: >

  let g:asciidoctor_pdf_executable = '~/asciidoctor-pdf/bin/asciidoctor-pdf'


*g:asciidoctor_use_fullpath*          Use full path when pass a file for a
                                    compilation.
                                    Default: v:true
  Example: >

  let g:asciidoctor_use_fullpath = v:false

Might be useful if for some reason file passed for a compilation should not
have full path. For example asciidoctor-pdf in docker might use the following
setup to be able to create PDFs: >

  let g:asciidoctor_pdf_executable = 'docker run --rm -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf'

Note that you might need to have proper current working directory.
Available for |:Asciidoctor2HTML| and |:Asciidoctor2PDF| commands only.


*g:asciidoctor_pdf_extensions*        What extensions to use with PDF.
                                    Default: []
  Example: >

  let g:asciidoctor_pdf_extensions = ['asciidoctor-diagram']


*g:asciidoctor_pdf_themes_path*       Path to custom themes.
                                    Default: ''
  Example: >

  let g:asciidoctor_pdf_themes_path = '~/docs/ascidoctor-themes/'


*g:asciidoctor_pdf_fonts_path*        Path to fonts used in themes.
                                    Default: ''
  Example: >

  let g:asciidoctor_pdf_fonts_path = '~/docs/fonts/'


*g:asciidoctor_pandoc_executable*     What to use for DOCX. The process is to
                                    convert ADOC to DOCBOOK with
                                    |g:asciidoctor_executable| and then
                                    DOCBOOK to DOCX with pandoc.
                                    Default: 'pandoc'
  Example: >

  let g:asciidoctor_pandoc_executable = '~/bin/pandoc'


*g:asciidoctor_pandoc_data_dir*       Set --data-dir for pandoc.
                                    Default: ''
  Example: >

  let g:asciidoctor_pandoc_data_dir = '~/docs/.pandoc'


*g:asciidoctor_pandoc_reference_doc*  Set --reference-doc for pandoc.
                                    What docx file to use as a reference
                                    document (use styles defined there)
                                    Default: ''
  Example: >

  let g:asciidoctor_pandoc_referenc_doc = 'custom-reference.docx'


*g:asciidoctor_pandoc_other_params*   Set additional parameteres for pandoc.
                                    Default: ''
  Example: >

  let g:asciidoctor_pandoc_other_params = '--toc'


*g:asciidoctor_folding*               Fold sections (headers).
                                    Default: 0
  Example: >

  let g:asciidoctor_folding = 1

if enabled all sections would be foldable. Title has the same fold level as
sections level 1, higher level sections would have higher fold level (folded
under section level-1): >

 = Title
 == Section 1
 === Section 2
 === Section 2
 == Section 1

When folded: >

 = Title -----------------------------------
 == Section 1 ------------------------------
 == Section 1 ------------------------------


*g:asciidoctor_foldnested*            Fold nested sections.
                                    Default: 1
  Example: >

  let g:asciidoctor_foldnested = 0

if disabled all sections would have the same foldlevel (=1) no matter what
section level is.

Then >

 = Title
 hello world
 == Section 1
 hello world
 === Section 2
 hello world
 === Section 2
 hello world
 == Section 1
 hello world

Would be folded to: >

 = Title -----------------------------------
 == Section 1 ------------------------------
 === Section 2 -----------------------------
 === Section 2 -----------------------------
 == Section 1 ------------------------------


*g:asciidoctor_foldtitle_as_h1*       Fold title as level 1 sections.
                                    Default: 1

  Example: >

  let g:asciidoctor_foldtitle_as_h1 = 0

When on, following >

 = Title
 hello world
 == Section 1
 hello world
 === Section 2
 hello world

would be folded to: >

 = Title -----------------------------------
 == Section 1 ------------------------------

Otherwise to >

 = Title -----------------------------------


*g:asciidoctor_syntax_indented*       Enable highlight for indented blocks.
                                    Default: 1
  Example: >

  let g:asciidoctor_syntax_indented = 0


*g:asciidoctor_syntax_conceal*        Enable concealable syntax.
                                    Currently only bold, italic, bolditaclic,
                                    code and links are concealed.
                                    Default: 0
  Example: >

  let g:asciidoctor_syntax_conceal = 1

NOTE: It doesn't automatically set conceallevel.


*g:asciidoctor_fold_options*          Fold options (usually under the title).
                                    Default: 0
  Example: >

  let g:asciidoctor_fold_options = 1

if enabled asciidoctor options would be foldable: >

    = Title
    :author: Maxim Kim
    :experimental:
    :toc: left
    :toclevels: 3
    :icons: font
    :autofit-option:
    :source-highlighter: rouge
    :rouge-style: github
    :source-linenums-option:
    :revdate: 2018-11-19
    :imagesdir: images

When folded: >

    = Title
    :author: Maxim Kim ------------------------


*g:asciidoctor_fenced_languages*      Highlight syntax of source blocks
                                    Default: []
  Example: >

  let g:asciidoctor_fenced_languages = ['python', 'c', 'javascript']

Then in your asciidoctor document: >

  [source,python]
  ----
  def hello():
      print("hello world")
  ----

should be highlighted with python syntax.


*g:asciidoctor_img_paste_command*     Command to save clipboard image to a
                                    file.
                                    Default: 'gm convert clipboard: %s%s'
                                    Where first %s is a path, second %s is an
                                    image file name.
  Example: >

  " for OSX
  let g:asciidoctor_img_paste_command = 'pngpaste %s%s'

  " for linux
  let g:asciidoctor_img_paste_command = 'xclip -selection clipboard -t image/png -o > %s%s'


*g:asciidoctor_img_paste_pattern*     Pattern of the saved clipboard image file.
                                    Default: 'img_%s_%s.png'
                                    Where first %s is a document base name,
                                    second %s is an image number.
  Example: >

  let g:asciidoctor_img_paste_pattern = '%s_img_%s.png'

So if you edit 'README.adoc` document and paste a clipboard image there it
would have name 'README_img_1.png'. Next one would have name
'README_img_2.png' etc.


*g:asciidoctor_opener*                Shell command to open asciidoctor files.
                                    Used in |:AsciidoctorOpenRAW|,
                                    |:AsciidoctorOpenPDF|,
                                    |:AsciidoctorOpenHTML| and
                                    |:AsciidoctorOpenDOCX| commands.
                                    Default Windows: ':!start'
                                    Default Linux:   ':!xdg-open'
                                    Default OSX:     ':!open'
  Example: >

  let g:asciidoctor_opener = ':!firefox'




COMMANDS                                                *asciidoctor-commands*

These commands are local to the asciidoctor buffers.


                                                           *:Asciidoctor2HTML*
:Asciidoctor2HTML          Convert current file to HTML.
                           Uses |g:asciidoctor_executable|.


                                                            *:Asciidoctor2PDF*
:Asciidoctor2PDF           Convert current file to PDF.
                           Uses |g:asciidoctor_pdf_executable|.


                                                           *:Asciidoctor2DOCX*
:Asciidoctor2DOCX          Convert current file to DOCX.
                           Uses combination of |g:asciidoctor_executable| to
                           generate docbook file and
                           |g:asciidoctor_pandoc_executable| to generate
                           result DOCX file.


                                                         *:AsciidoctorOpenRAW*
:AsciidoctorOpenRAW        Open current file in Web browser. Chrome and
                           Firefox have extension to render barebone .adoc
                           files. Uses |g:asciidoctor_opener|.


                                                        *:AsciidoctorOpenHTML*
:AsciidoctorOpenHTML       Open HTML file of the current file. It should exist
                           (created first with |:Asciidoctor2HTML| command).
                           Uses |g:asciidoctor_opener|.


                                                         *:AsciidoctorOpenPDF*
:AsciidoctorOpenPDF        Open PDF file of the current file. It should exist
                           (created first with |:Asciidoctor2PDF| command).
                           Uses |g:asciidoctor_opener|.


                                                        *:AsciidoctorOpenDOCX*
:AsciidoctorOpenDOCX       Open DOCX file of the current file. It should exist
                           (created first with |:Asciidoctor2DOCX| command).
                           Uses |g:asciidoctor_opener|.


                                                      *:AsciidoctorPasteImage*
:AsciidoctorPasteImage     "Paste" image from clipboard into buffer.
                           1. Image file name is generated according to
                           |g:asciidoctor_img_paste_pattern|.
                           2. Clipboard image is saved in :imagesdir:
                           directory (asciidoctor option defined in a
                           document) or in the directory of the buffer.
                           3. Image file name is inserted into the buffer.
                           4. External dependency should be set up, see
                           |g:asciidoctor_img_paste_command|.



MAPPINGS                                                *asciidoctor-mappings*

*<Plug>(AsciidoctorFold)*    Fold sections in a special way.

If
* no count is provided, toggle current fold;
* count is n, open folds up to foldlevel n.


*<Plug>(AsciidoctorPromoteSection)*    Promote section including subsections.

This >

  = Title
  [cursor]
  == Section 1
  === Section 2
  == Section 3

Would become >

  == Title
  [cursor]
  === Section 1
  ==== Section 2
  === Section 3

*<Plug>(AsciidoctorDemoteSection)*     Demote section including subsections.

This >

  == Title
  [cursor]
  === Section 1
  ==== Section 2
  === Section 3

Would become >

  = Title
  [cursor]
  == Section 1
  === Section 2
  == Section 3



DEFAULT MAPPINGS

There are no default mappings. You can setup yours with: >


    " Function to create buffer local mappings
    fun! AsciidoctorMappings()
        nnoremap <buffer> <leader>oo :AsciidoctorOpenRAW<CR>
        nnoremap <buffer> <leader>op :AsciidoctorOpenPDF<CR>
        nnoremap <buffer> <leader>oh :AsciidoctorOpenHTML<CR>
        nnoremap <buffer> <leader>ox :AsciidoctorOpenDOCX<CR>
        nnoremap <buffer> <leader>ch :Asciidoctor2HTML<CR>
        nnoremap <buffer> <leader>cp :Asciidoctor2PDF<CR>
        nnoremap <buffer> <leader>cx :Asciidoctor2DOCX<CR>
        nmap <buffer> <space><tab> <Plug>(AsciidoctorFold)
    endfun

    " Call AsciidoctorMappings for all `*.adoc` and `*.asciidoc` files
    augroup asciidoctor
        au!
        au BufEnter *.adoc,*.asciidoc call AsciidoctorMappings()
    augroup END


BIBLIOGRAPHY COMPLETION                               *asciidoctor-completion*

There is initial support for bibtex citation added.

Usage:

Place your bibtex files next to your asciidoctor file (to the same path). Then
completion would be available for: >

  cite:[cit<C-X><C-U>
  citenp:[cit<C-X><C-U>


 vim:tw=78:et:ft=help:norl: