Vim ❤️ Asciidoc

Table of Contents

• Intro
• Installation
  • Vim8 built-in packages
  • vim-plug
• Setup
• Commands
• Usage
  • HTML output
  • DOCX output
  • PDF output
• Paste images from clipboard
• Bibliography completion
• Misc
  • Generate HTML on file save
  • Highlight group names
• Limitations
  • Indented text is highlighted for all table cells
  • Setext-style headers highlighting
  • URL Conceal

Intro

Vim has a native syntax highlighting for asciidoc. And it 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).

Installation

Vim8 built-in packages

You can use git command on your command line:

git clone https://github.com/DavidFederl/vim-asciidoc.git ~/.vim/pack/my-packages/start/vim-asciidoc

For windows users you should change ~/.vim to %USERPROFILE%/vimfiles

git clone https://github.com/DavidFederl/vim-asciidoc.git %USERPROFILE%/vimfiles/pack/my-packages/start/vim-asciidoc

or minpac package manager (to add to your .vimrc):

call minpac#add('DavidFederl/vim-asciidoc')

vim-plug

Add to your .vimrc next to your other plugs

Plug 'DavidFederl/vim-asciidoc'

Setup

Note	To use basic asciidoc with vim you do not have to setup anything in vim. At least this was the intention. :)

The following is an example setup. Part of it might not work for you if you do not have asciidoc extensions installed. Or you do not have custom PDF themes and fonts.

asciidoc

" What to use for HTML, default `asciidoctor`.
let g:asciidoc_executable = 'asciidoctor'

" What extensions to use for HTML, default `[]`.
let g:asciidoc_extensions = ['asciidoctor-diagram', 'asciidoctor-rouge']

" Path to the custom css
let g:asciidoc_css_path = '~/docs/AsciiDocThemes'

" Custom css name to use instead of built-in
let g:asciidoc_css = 'custom-asciidoc.css'

asciidoc-pdf

" What to use for PDF, default `asciidoctor-pdf`.
let g:asciidoc_pdf_executable = 'asciidoctor-pdf'

" What extensions to use for PDF, default `[]`.
let g:asciidoc_pdf_extensions = ['asciidoctor-diagram']

" Path to PDF themes, default `''`.
let g:asciidoc_pdf_themes_path = '~/docs/AsciiDocThemes'

" Path to PDF fonts, default `''`.
let g:asciidoc_pdf_fonts_path = '~/docs/AsciiDocThemes/fonts'

asciidoc-docx

" What to use for DOCX, default `pandoc`.
" The DOCX 'compilation' process is to generate `docbook` using
" `g:asciidoc_executable` and then to generate DOCX out of `docbook`
" using `pandoc`.
let g:asciidoc_pandoc_executable = 'pandoc'

"" --data-dir
let g:asciidoc_pandoc_data_dir = '~/docs/.pandoc'

" Other parameters you want to feed pandoc
let g:asciidoc_pandoc_other_params = '--toc'

" Reference document to reuse styles
" If not set up asciidoc looks for the theme name
" :pdf-style: mytheme
" in the first 30 lines and generate reference-doc filename:
" g:asciidoc_pandoc_data_dir + mytheme + '-reference.docx'
" for example: ~/docs/.pandoc/mytheme-reference.docx
let g:asciidoc_pandoc_reference_doc = 'custom-reference.docx'

folding

" Fold sections, default `0`.
let g:asciidoc_folding = 1

" Fold options, default `0`.
let g:asciidoc_fold_options = 1

syntax

" Conceal *bold*, _italic_, `code` and urls in lists and paragraphs, default `0`.
" See limitations in end of the README
let g:asciidoc_syntax_conceal = 1

" Highlight indented text, default `1`.
let g:asciidoc_syntax_indented = 0

syntax highlighting for languages in [source] blocks

" List of filetypes to highlight, default `[]`
let g:asciidoc_fenced_languages = ['python', 'c', 'javascript']

default mappings…​ there are no default mappings

" Function to create buffer local mappings and add default compiler
fun! AsciidocMappings()
    nnoremap <buffer> <leader>oo :AsciidocOpenRAW<CR>
    nnoremap <buffer> <leader>op :AsciidocOpenPDF<CR>
    nnoremap <buffer> <leader>oh :AsciidocOpenHTML<CR>
    nnoremap <buffer> <leader>ox :AsciidocOpenDOCX<CR>
    nnoremap <buffer> <leader>ch :Asciidoc2HTML<CR>
    nnoremap <buffer> <leader>cp :Asciidoc2PDF<CR>
    nnoremap <buffer> <leader>cx :Asciidoc2DOCX<CR>
    nnoremap <buffer> <leader>p :AsciidocPasteImage<CR>
    " :make will build pdfs
    compiler asciidoc2pdf
endfun

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

Commands

All commands are buffer local — available only for asciidoc files (set filetype=asciidoc)

• Asciidoc2HTML — convert current file to HTML.

• Asciidoc2PDF — convert current file to PDF.

• Asciidoc2DOCX — convert current file to DOCX.

• AsciidocOpenRAW — open current file in a browser. Chrome and Mozilla Firefox has extentsions to render barebone adoc files.

• AsciidocOpenPDF — open PDF of the current file using default PDF viewer.

• AsciidocOpenHTML — open HTML of the current file using default web browser.

• AsciidocOpenDOCX — open DOCX of the current file using default DOCX viewer. (I haven’t tried it with LibreOffice or whatever else there might be. Also haven’t tried it on linux and OSX…​)

Note	Commands: Asciidoc2HTML, Asciidoc2PDF should convert files if asciidoc and asciidoc-pdf are installed. Command Asciidoc2DOCX should also have pandoc installed.

Usage

1. Open ~/test.adoc

2. Enter:

   = Asciidoc Title: Hanging around
   
   This is the first para and it will be rendered with bigger text.
   
   == Section 1
   
   Text of section 1
   
   == Section 2
   
   Text of section 2

3. Save it and export to HTML

   :w<CR>
   :Asciidoc2HTML<CR>

4. Open the HTML file:

   :AsciidocOpenHTML<CR>

HTML output

That should look something like this:

Figure 1. HTML output

DOCX output

If you use :Asciidoc2DOCX and :AsciidocOpenDOCX commands instead, you should see something like this (provided you have pandoc and MSWord installed:)

Figure 2. DOCX output

PDF output

And if you use :Asciidoc2PDF and :AsciidocOpenPDF commands, you should see something like this (I have my own default theme and fonts, so you probably see it a bit different) :

Figure 3. PDF title page output

Figure 4. PDF first page output

Paste images from clipboard

Vim can’t access graphical part of clipboard thus an external tool should be used to save clipboard image to a png file.

• For Windows I use GraphicsMagic (could be installed using scoop)

• For OSX I use pngpaste (could be installed using brew)

• For Linux — xclip could be used (thx Matthias Fulz @mfulz)

setup

" first `%s` is a path
" second `%s` is an image file name
" this is default for windows
let g:asciidoc_img_paste_command = 'gm convert clipboard: %s%s'

" for osx
" let g:asciidoc_img_paste_command = 'pngpaste %s%s'

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



" first `%s` is a base document name:
" (~/docs/hello-world.adoc => hello-world)
" second `%s` is a number of the image.
let g:asciidoc_img_paste_pattern = 'img_%s_%s.png'

If there is :imagesdir: as an option set up in a document, clipboard image is saved there (relative to the document). Otherwise image is saved in the documents directory.

The name of the image is generated according to the pattern. By default it is

img_ + document_base_name + next_image_number + .png

Bibliography completion

There is initial support for bibliography completion. Works with *.bib files placed to the same folder as file being edited.

No setup is needed although additional setting for a base bibtex folder might be added in the future.

It uses vim’s completefunc which is usually called in insert mode with <C-X><C-U>, and it works for

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

Note

To create bibliography in asciidoc, i.e., to put it into PDF or HTML you should install asciidoc-bibtex extension and provide it to vim-asciidoc extension list(s): " For asciidoc backend let g:asciidoc_extensions = ['asciidoctor-bibtex'] " For asciidoc-pdf backend let g:asciidoc_pdf_extensions = ['asciidoctor-bibtex']

Misc

Generate HTML on file save

Add following snippet to your vim config to generate an HTML file upon saving:

augroup ON_ASCIIDOC_SAVE | au!
    au BufWritePost *.adoc :Asciidoc2HTML
augroup end

If you want to add text files to the mix you can have something similar to:

func! ConvertAsciidocToHTML()
    " Text file with asciidoc contents?
    if &filetype == 'text' && getline(1) =~ '^= .*$'
        " text files have no asciidoc commands
        set filetype=asciidoc
        Asciidoc2HTML
        set filetype=text
    elseif &filetype == 'asciidoc'
        Asciidoc2HTML
    endif
endfunc
augroup ON_ASCIIDOC_SAVE | au!
    au BufWritePost *.adoc,*.txt call ConvertAsciidocToHTML()
augroup end

Note	if you have vim-dispatch installed HTML conversion would be done in background.

Highlight group names

Colorschemes can use following highlight groups to redefine default highlighting:

Highlight Group Name	Default Value
asciidocTitle	Title
asciidocSetextHeader	Title
asciidocH1	Title
asciidocH2	Title
asciidocH3	Title
asciidocH4	Title
asciidocH5	Title
asciidocH6	Title
asciidocTitleDelimiter	Type
asciidocH1Delimiter	Type
asciidocH2Delimiter	Type
asciidocH3Delimiter	Type
asciidocH4Delimiter	Type
asciidocH5Delimiter	Type
asciidocH6Delimiter	Type
asciidocSetextHeaderDelimiter	Type
asciidocListMarker	Delimiter
asciidocOrderedListMarker	asciidocListMarker
asciidocListContinuation	PreProc
asciidocComment	Comment
asciidocIndented	Comment
asciidocPlus	PreProc
asciidocPageBreak	PreProc
asciidocCallout	Float
asciidocCalloutDesc	String
asciidocListingBlock	Comment
asciidocLiteralBlock	Comment
asciidocFile	Underlined
asciidocUrl	Underlined
asciidocEmail	Underlined
asciidocUrlAuto	Underlined
asciidocEmailAuto	Underlined
asciidocUrlDescription	String
asciidocLink	Underlined
asciidocAnchor	Underlined
asciidocAttribute	Identifier
asciidocCode	Constant
asciidocOption	PreProc
asciidocBlock	PreProc
asciidocBlockOptions	PreProc
asciidocTableSep	PreProc
asciidocTableCell	PreProc
asciidocTableEmbed	PreProc
asciidocInlineAnchor	PreProc
asciidocMacro	Macro
asciidocIndexTerm	Macro
asciidocBold	gui=bold cterm=bold
asciidocItalic	gui=italic cterm=italic
asciidocBoldItalic	gui=bold,italic cterm=bold,italic

If you want to change highlight yourself for existing colorscheme without touching it, add the following to you vimrc:

func! AsciidocHighlight()
    " Highlight asciidoc syntax with colors you like.
    " For solarized8 colorscheme
    if get(g:, "colors_name", "default") == "solarized8"
        hi asciidocTitle guifg=#ff0000 gui=bold ctermfg=red cterm=bold
        hi asciidocOption guifg=#00ff00 ctermfg=green
        hi link asciidocH1 Directory
    elseif get(g:, "colors_name", "default") == "default"
        hi link asciidocIndented PreProc
    endif
endfunc
augroup ASCIIDOCTOR_COLORS | au!
    au Colorscheme * call AsciidocHighlight()
    au BufNew,BufRead *.adoc call AsciidocHighlight()
augroup end

Limitations

Indented text is highlighted for all table cells

Works for all table cells, although should only be applied to a| cells.

[cols=".^1,.^2", options="header"]
|===
| header1
| header1

| Regular table cell

    Indented text is highlighted as indented
    which is kind of incorrect

a| Asciidoc cell

    Indented text is highlighted as indented
    which is correct

|===

Setext-style headers highlighting

Proper setext-style highlighting should have equal numbers of underlined chars:

This Header level 1
===================

This Header level 2
-------------------

This Header level 3
~~~~~~~~~~~~~~~~~~~

This Header level 4
^^^^^^^^^^^^^^^^^^^

This Header level 5
+++++++++++++++++++

Vim can’t do it so setext-style headers are highlighted no matter if there is matched underline or not.

This Header level 1
======================

This Header level 2
-----

This Header level 3
~~~~~~~~~~~~~~~~

This Header level 4
^^^^^^^^^^^^^^^^^^^^

This Header level 5
+++++++++++++

You can also use following mappings:

" Underline current line
func! s:underline(chars)
    let nextnr = line('.') + 1
    let underline = repeat(a:chars[0], strchars(getline('.')))
    if index(a:chars, trim(getline(nextnr))[0]) != -1
        call setline(nextnr, underline)
    else
        call append('.', underline)
    endif
endfunc
nnoremap <leader>- :call <SID>underline(['-', '=', '~', '^', '+'])<CR>
nnoremap <leader>= :call <SID>underline(['=', '-', '~', '^', '+'])<CR>
nnoremap <leader>~ :call <SID>underline(['~', '=', '-', '^', '+'])<CR>
nnoremap <leader>^ :call <SID>underline(['^', '=', '-', '~', '+'])<CR>
nnoremap <leader>+ :call <SID>underline(['+', '=', '-', '~', '^'])<CR>

URL Conceal

Links with additional attributes are not concealed to description:

https://discuss.asciidoc.org[Discuss Asciidoc,role=external,window=_blank]
https://discuss.asciidoc.org[Discuss Asciidoc^]
https://example.org["Google, Yahoo, Bing^",role=teal]

With set conceallevel=3 looks like:

Discuss Asciidoc,role=external,window=_blank
Discuss Asciidoc^
"Google, Yahoo, Bing^",role=teal

Although it should look like:

Discuss Asciidoc
Discuss Asciidoc
Google, Yahoo, Bing