The .vimrc file in this gist contains insert-mode mappings that will save you even more typing when writing in AsciiDoc (as if switching from DocBook wasn’t already an improvement :)).
The mappings leverage the "leader" variable, a special string that is used to indicate that a command is incoming. This configuration uses a semi-colon, ;, as the leader. That means in insert mode you will type a semi-colon immediately followed by one of the defined keystroke combinations (e.g., ;qb). After a brief timeout, the semi-colon will be inserted if you didn’t type any of the mapped keystrokes.
To use these mappings, copy the lines from the .vimrc file into your .vimrc file (or simply move this one into place). The mappings are configured to apply locally to a buffer holding an asciidoc file (existing or new).
Here’s how you use the various commands, most of which apply to insert mode. In each result, the pipe indicates the location of the cursor.
To insert a quote block in insert mode, type:
;qb
Result:
____ | ____
Now just type between the lines. When you are done, you can jump below the bottom of the block by typing <C-j> (from insert mode).
You can also setup a quote block after the fact from normal mode. While on the line you want to quote, type ;qb as you did in insert mode.
The other blocks follow the same pattern. For instance, to insert a listing block in insert mode, type:
;cb
Result:
---- | ----
You can insert a single-line admonition in insert mode by typing:
;n.
Result:
NOTE: |
You setup a multi-line admonition in insert mode just like you did a block:
;nb
Result:
[NOTE] ==== | ====
This works for all admonition types, where the first character after the leader is selected as follows: (NOTE ⇒ n, TIP ⇒ t, IMPORTANT ⇒ !, WARNING ⇒ w, CAUTION ⇒ $).
Support for text formatting is also provided using the leader prefix. The mapping sets up the quotes and positions the cursor between them. Here’s how you would prepare to make bold text in insert mode:
;*
Result:
*|*
Once you are done typing the bold text, you can jump outside of the quotes by typing <C-]>.
This works for *, ', ", `, + and :.
There are also shortcuts for setting up brackets in insert mode, such as square brackets:
;[
Result:
[|]
This works for [, < and (.
You can format after the fact. In normal mode, place the cursor over the word and type ;q* for strong, ;q' for emphasis and so on. (Note that nasty looking mapping for adding emphasis. That’s escaping single quotes already present in the string…it was quite a chore to get it working).
You can insert a horizontal rule in insert mode by typing:
;r
Result:
'''
You can setup an image in insert mode by typing:
;i.
Result:
image:|[]
You can setup a link (w/ the link prefix) in insert mode by typing:
;l.
Result:
link:|[]
When you get to the end of typing the image file name, type <C-o>a to advance the cursor between the square brackets to type the alt text.
The double carriage returns (hitting enter twice) is mapped to <C-i> in insert mode. This makes it easy to advance to a new paragraph in a single keybinding.
Typing first paragraph.<C-i> Typing second paragraph.
Happy documenting!
Should put this in a plugin, perhaps along with some other stuff. Or a listing of other plugins that help with editing asciidoc files.