Vim reStructured Text

Author: Mikolaj Machowski
Title: Vim reStructured Text - HTML and LaTeX output
Keywords: Vim, LaTeX, PDF, HTML, XML
Version: 1.4
License: GPL v. 2
Date: 4 Nov 2006

For a long time Vim users were asking for "real" export to HTML. This is, I believe, first real try to achieve this effect. This is Vim version of reStructuredText, popular Python language documentation tool (so I borrowed parts of its documentation).

Contents

Introduction

Structured means Vim script recognizes some patterns and translates them into form recognizable by WWW browsers. In fact, Vim creates quasi-XML form which can be exported into HTML and LaTeX.

Major office suites OpenOffice.org and MS-Office can import HTML (KOffice also can do this but results aren't good) and save files in their native formats.

Download

All forms of documentation were created from the same txt source without any corrections:

Installation

Put archive vst.zip into your ~/.vim (Unices) or vimfiles (MS-Windows) directory and unpack it there. It will create files: 

 |- doc2/vst.txt           <- documentation
 |- doc2/vst-s5.txt        <- example of S5 presentation
 |- doc2/test.png          <- to complete documentation
 |- plugin/vstplugin.vim   <- small plugin file with commands
 |- autoload/vst/vst.vim   <- main script
 |- autoload/vst/myhtmlvst.vim <- examples of macros
 \- autoload/vst/s5ui/*    <- S5 style files

Usage

Transformation is called with command: 

 :Vst [{format}]

Where {format} is format of exported file. Format argument is optional and without it default value (HTML) will be used. Argument name is case-insensitive: HTML, html, Html are equivalents. Formatted file will be opened in new buffer without name.

g:vst_write_export

Boolean (0). If true, write file immediately with extension specific to export format (html, tex, xml). Overwrite existing files without warning. How to set it read :help :let.

Second command: 

 :Vsti [{format}]

Instantly writes file with extension specific to export, overwrite existing files without warning.

Third command: 

 :Vstm

Is calling menus.

Project file

User can write variables specific to project into special file vstrc.vim, located into the same directory as processed file. This is regular Vim script file which will be sourced at the time of export.

Export to HTML

These commands will create XHTML 1.0 file: 

 :Vst html
 :Vst

Vst command (with any export argument) accepts range: 

 :[range]Vst {[export]}

When file use exclusively lists starting from 1/a/A/etc. doctype is Strict, in other case it is Transitional.

From special characters/entities Vim reStructured Text handles at the moment: 

 <, >, &, ©

Results in: <, >, &, ©.

List can be extended on request.

g:vst_html_post

String (empty). Filename, sourced after whole processing. In that file user can put specialized formatting commands, replacing custom or export dependent templates from replacements etc. For examples check macros section. How to set it read :help :let.

User CSS

User can manipulate how CSS will be attached by combinations of these two variables (how to use Vim variables read :help :let):

g:vst_css_default

String (empty). When unmodified default CSS will be included in HTML file. When non-empty default CSS will be written to external file. Existing file will be overwritten without warning. If equal to NONE (case sensitive) any reference to default CSS will be skipped.

g:vst_css_user

String (empty). When non-empty link to specified file will be included.

Default CSS is in separate file in autoload/vst/default.css so it is easy to make global-local modifications.

Export to S5

Command: 

 :Vst s5

Will create S5 -- Simple Standards Based Slide Show System. XHTML file steered by JavaScript and CSS created by Eric Meyer.

Not every document will be good S5 presentation. All elements but table of contents are supported but not every one will be good thing to place in one screen.

S5 document

File should begin with first level header. It will be title of document. Each slide will begin with second level header. Author and date to place in footer will be taken from appropriate fields of field list.

Tip

Vim reStructured Text provides predefined classes. Both can be introduced by class or container directives:

handout

Elements marked with that class will not be seen in presentation mode, only handout mode.

incremental

Elements marked with that class will be displayed gradually, when using normal forward. This one can be also introduced as a role -- usage of this element is easier with default role directive.

Good example of S5 document was prepared by George V. Reilly and its text form is included in tarball (doc2/vst-s5.txt). Result can be viewed here.

Export to LaTeX

These commands will LaTeX version of Vim reStructured Text file: 

 :Vst latex
 :Vst tex

Document will use hyperref package and it will be fully hyperlinked. It is better to compile it with pdflatex, directly to PDF than use pure latex.

g:vst_tex_preamble

String (empty). User can define his own command (to use in raw latex) or change some defaults. Should be absolute or relative path to processed file. Contents of file will be included with \input{}.

g:vst_tex_post

String (empty). Filename, sourced after whole processing. In that file user can put specialized formatting commands, replacing custom or export dependent templates from replacements etc.

Current differences between HTML and LaTeX export:

Export to PDF

This command will immediately compile PDF document after creation of LaTeX source: 

 :Vst pdf

Additional tuning of this command with variables (how to use variables read :help :let):

g:vst_pdf_view

Boolean (0). When equal 1 immediately show result of compilation.

g:vst_pdf_viewer

String (default for unices is xpdf, for MS-Windows empty -- properly setup system will take care about choosing application).

g:vst_pdf_clean

Boolean (0). When equal 1 remove auxiliary files of PDF compilation (including tex source -- use with caution!)

g:vst_pdf_command

String (pdflatex -interaction=nonstopmode). Value of this string will be used to produce PDF document. User may need to modify this variable, especially if document needs some preprocessing.

Export to XML

This command will produce XML-like code: 

 :Vst xml

For debugging purposes.

Export to reST

This command will remove incompatibilities with reST: 

 :Vst rest

Warning

This export can result in losing of some formatting.

Auxiliary commands

Vim reStructured Text script provides set of auxiliary commands to make easier editing of bigger files and especially navigating through them.

head

It is possible to lost orientation which type of underscore was used to mark certain level of sections: 

 :Vst head

Will show small table with level name and symbols used to mark them: 

 Level               Symbol
 h1                  =========d
 h2                  --------- 
 h3                  ~~~~~~~~~ 
 h4                  +++++++++

This is result of Vst head for this manual. Letter d at the end of ornament shows this is double ornament.

toc

In longer text documents it is very easy to be lost: 

 :Vst toc

This command will present table of contents for current document. Here is fragment of table of contents of this manual: 

 h3 ~~~~~~~~~   5.3  Inline markup rules                553
 h3 ~~~~~~~~~   5.4  Special characters                 587
 h3 ~~~~~~~~~   [[[ 5.5  Roles ]]]                      625
 h4 `````````   5.5.1  Predefined roles                 652
 h5 '''''''''   5.5.1.1  Title reference                658
 h5 '''''''''   5.5.1.2  Subscript                      670

It gives plenty of information. First column is name of section level; second column shows decoration for that level; third column are section titles with numbers of sections as they will be shown in HTML and LaTeX export. Title of section were cursor was at the moment of invoking command is taken into [[[ ]]]; fourth column are line numbers of section titles -- user can immediately issue Vim command, eg. :625 to go to Roles section.

link and slink

Commands will show all external links and internal explicit targets in chronological order: 

 :Vst link

In alphabetical order: 

 :Vst slink

Fragment of link table for this document (in chronological order): 

 Text                Link
 Vim                 http://www.vim.org
 reStructuredText    http://docutils.sf.net
 starting point      http://www.vim.org
 comment
 Opera               http://www.opera.com
 vst.pdf             http://skawina.eu.org/mikolaj/vst.pdf

Item without Link part (second column) is internal explicit target.

rep and srep

Commands will show replace declarations. In chronological order: 

 :Vst rep

And in alphabetical: 

 :Vst srep

Replace table for this document (in chronological order): 

 Symbol              Replacement
 H2O                 H\ :sub:`2`\ O
 from                image:image.jpg width:20 height:20 target:URL
 VST                 Vim reStructured Text

Folding

Vim reStructured Text offers whole family of commands for folding of file.

This command will create simple folds for document, each section has its own fold on the same level: 

 :Vst fold

Folds are created based on regular expressions and when you add new text to section fold will be expanded to include them. New sections won't be recognized automatically and you should recreate folds to include new sections.

In front of header text you will see numbers of section as they will be visible in HTML and LaTeX formats.

At the end of line enclosed in parenthesis are charaters used as ornament of section title.

Command: 

 :Vst foldr

Will create folds recursively, each level of headers will have its own level of folding.

Commands: 

 :Vst fold1
 :Vst fold2
 :Vst fold3
 :Vst fold4
 :Vst fold5

Will create one level of folds down to this level of headers. This is can be useful for visualization of table of contents and faster navigation by big structures of text.

Folding by directive

For easier finding of some directives user can use special case of folding: 

 :Vst f{directive}

Where {directive} is name of directive, eg.: container, blockquote, image, figure, tip, note, etc. Directive name is case insensitive.

Special case is: 

 :Vst fblank

Document will be folded by paragraphs -- fragments of text separated by blank lines.

help

This command will show short summary of Vim reStructured Text commands: 

 :Vst help

preproc

This command will preprocess file and include in file all including commands: 

 :Vst preproc

This command is recursive. For details see including commands

Ornament mapping

Manual insertion of sections or transitions ornaments is boring. To speed things up in Vim way auxiliary mapping was created: <C-B>o.

When placed below line of text and above empty one it will fill line to length of line above. It may use character before cursor, when not available it will use last single ornamented section title as hint.

When placed above line of text and below empty line it will embrace line below in section ornaments. It may use character before cursor, when not available it will use last double ornamented section title as hint.

When placed between empty lines it will fill it as transition element. It may use character before cursor, when not available it will use last transition as hint.

Vim settings

Set of Vim settings which can be useful for editing of Vim reStructured Text files: 

 set nocompatible
 set autoindent
 set formatoptions+=tqn
 set formatlistpat=^\\s*\\(\\d\\+\\\|[a-z]\\)[\\].)]\\s*
 set textwidth=78    " purely arbitrary value, just remember to set it
 set expandtab
 set softtabstop=4   " less than 4 may result in breaking of lists
 set shiftwidth=4
 set formatoptions+=tqn

Syntax highlighting

Structure of document will be more visible with syntax highlighting. It is possible to use Vim default syntax highlighting file by Nicolai Weibull just by issuing Vim command: 

 :set ft=rst

On vim-online site is another syntax file by Estienne Swart.

You can plase filetype declaration in Vim modeline, it will be removed from output file to not confuse Vim filetype detection (modelines have the highest priority). But it will work only if filetype setting is in separate Vim reStructured Text comment, line matching: 

 ^\s*\.\. vim:

This line has to be also inside of 'modelines' Vim option range.

Command: 

 :Vstm

in GUI version (gvim) will create menu with most common commands:

Export to HTML: export to HTML
Export to LaTeX: export to LaTeX
Export to PDF: export to PDF
Export to reST: export to reST
Fold: folding of document
Headers: show symbols of headers for various levels
TOC: show contents of text document
Help: show short help at the bottom of screen

To show menu always put this command in .vimrc:

g:vst_showmenu

Boolean (0). When 1 and set in .vimrc it will always show menu.

Structure

Paragraphs

Base unit of text is paragraph, text separated by at least one blank line. All lines in paragraphs must have the same indentation. Paragraph indented will be displayed as quotation (blockquote). It is possible to embed any type and any number of elements inside blockquote -- respecting their own rules of embedding. Example: 

 This is example of paragraph. This
 is continuation of paragraph.

     This is indented paragraph. Looking
     like quoted text.

         This is quoted quoted text. Indented two times.

 This is another one.

Results in:

This is example of paragraph. This is continuation of paragraph.

This is indented paragraph. Looking like quoted text.

This is quoted quoted text. Indented two times.

This is another one.

Embedding of elements is supported for paragraphs, blockquotes, ordered lists, unordered lists and tip, note, warning directives. In all of them can be embedded the rest of one-level elements.

Text styles

Inside of paragraph (and other text elements you can use another markup -- italics with *italics*, bold with **bold**, ``double back-quotes`` for typewriter text.

This text is italicised.

This text is strongly emphasised.

This text is a code.

If you find that you want to use one of the "special" characters in text, it should be OK -- Vim reStructured Text can deal with most typical situations. For example, this * asterisk is handled just fine. If you actually want text *surrounded by asterisks* to not be italicised, then you need to indicate that the asterisk is not special. You do this by placing a backslash just before it, like so "\\*". Remember: special treatment of these few characters is entering inline literals -- even there you have to escape it with double backslash: 

 ``\\*``

For another method of font manipulation check Roles.

Inline markup rules

These rules apply for text styles and all other types of inline markup, especially links.

The inline markup start-string and end-string recognition rules are as follows. If any of the conditions are not met, the start-string or end-string will not be recognized or processed.

  1. Inline markup start-strings must start a text block or be immediately preceded by whitespace or one of: 

     ' " ( [ { < - / :

  2. Inline markup start-strings must be immediately followed by non-whitespace.

  3. Inline markup end-strings must be immediately preceded by non-whitespace.

  4. Inline markup end-strings must end a text block or be immediately followed by whitespace or one of: 

     ' " ) ] } > - / : . , ; ! ? \

  5. If an inline markup start-string is immediately preceded by a single or double quote, "(", "[", "{", or "<", it must not be immediately followed by the corresponding single or double quote, ")", "]", "}", or ">".

  6. An inline markup end-string must be separated by at least one character from the start-string.

Special characters

Sometimes it is necessary to escape special treatment of some characters (or give that meaning). Then you have to put backslash \ before them.

Remove space: 

 this\ that

Result: thisthat

Do not italicise word: 

 not \*this* word

Result: not *this* word

Insert non-breaking space: 

 non\-breaking\-space

Result: non breaking space (&nbsp; in HTML)

Note

This construction should be avoided and use non-breaking space instead. It will be replaced with tilde in LaTeX export and leaved as-is in HTML (it is correctly interpreted by browsers.

To input non-breaking space in Vim use:

Backslash should be escaped by putting before it another backslash only in case when backslash could be used in special character. Slight inconsistency but generally makes text more readable.

Roles

Vim reStructured Text supports additional methods of text manipulation. They are called roles. Usual form is: 

 :name:`text`

Roles are requiring white spaces or non-word characters around them. You can escape them so they will be: 

 H\ :sub:`2`\ O

Result: H2O

It looks awkwardly, especially if repeated many times in text. You can help it with replacement: 

 |H2O|

 .. |H2O| replace:: H\ :sub:`2`\ O

Result is: H2O

Predefined roles

All predefined roles can be recognized as arguments for default role directive.

Title reference

This role will should be used to display Titles of books and similar citation sources. There are three ways to declare it in text: 

 :title-reference:`Title`
 :title:`Title`
 :t:`Title`

Title reference is default role for interpreted text.

Subscript

This role will show small text below normal line of text: 

 :sub:`small text below`
Superscript

This role will show small text over normal line of text: 

 :sup:`small text over`
Big

This role will show some bigger text: 

 :big:`bigger text`
Small

This role will show some smaller text: 

 :small:`smaller text`
Strong

This role will show bold text: 

 :strong:`bold text`
Emphasis

This role will show emphasised text: 

 :emphasis:`emphasised text`
Literal

This role will show monospaced text: 

 :literal:`monospaced text`

Custom roles

You can use custom roles which will be marked in Vim reStructured Text source as: 

 :custom:`special text`

And in HTML output: 

 <span class="custom">special text</span>

In LaTeX output: 

 \vstcustom{special text}

Note vst prefix to avoid possible conflicts with built-in (La)TeX commands. In preamble will be inserted simple template to allow compilation of document without stopping on unknown commands: 

 \newcommand{\vstcustom}[1]{\textnormal{#1}}

It will be inserted before declaration of extension of preamble by external file. If user wants to declare there these new commands he should use renewcommand LaTeX command.

Roles have to be declared through role directive. When not declared will be silently ignored and any sign of them will be removed from output. Declaration of role: 

 .. role:: custom

May be used for example to underline fragment of text (style of decoration not supported by reST or Vim reStructured Text): 

 .. role:: ul

 This fragment :ul:`will be underlined`

And in user CSS file: 

 span.ul { text-decoration: underline }

Role directive may have an option class: 

 .. role:: name
    :class: special

It will turn: 

 This is :name:`wonderful` feature.

Into: 

 This is <span class="special">wonderful</span> feature.

Useful when CSS name is long or not meaningful.

Reversed notation

Vim reStructured Text supports also reversed notation of roles: 

 `text`:name:

But be careful. Use of it in some cases (replacement-link combo) can give weird results.

Lists

Lists of items come in three main flavours: enumerated, bulleted and definitions. List element can contain many body elements.

Lists must always start a new paragraph -- that is, they must appear after a blank line.

Enumerated lists

Start a line off with a number or letter followed by a period ".", right bracket ")" or colon ":", also enclosed in parenthesis (a). Following forms are recognised: 

 1. numbers

 A. upper-case letters
    and it goes over many lines and may contain body elements like

    1. sub-
    2. -lists

    ::

        Or preformatted text

 a. lower-case letters

 1) numbers again

 i. lower roman numerals

 I. and upper roman literals

 (a) enumerator enclosed in parenthesis

Results in:

  1. numbers

  1. upper-case letters and it goes over many lines and may contain body elements like

    1. sub-

    2. -lists 

     Or preformatted text

    Or many other elements.

  1. lower-case letters

  1. numbers again

  1. lower roman numerals

  1. and upper roman literals

  1. enumerator enclosed in parenthesis

Vim reStructured Text is taking numeration of first element as numeration of whole list. This code: 

 a. alpha list
 2. decimal list

Will be rendered as:

  1. alpha list

  2. decimal list

Two lists of the same type must have separator between them. In other cause they will be rendered as one: 

 1. List1 Elem1
 2. List1 Elem2

 1. List2 Elem1
 2. List2 Elem2

Results in:

  1. List1 Elem1

  2. List1 Elem2

  3. List2 Elem1

  4. List2 Elem2

Placing between them empty comment is enough. Anyway, short description is always good thing.

List does not have to start from 1, a or A. Example: 

 5. First element of list
 #. Second element

Will become:

  1. First element of list

  2. Second element

And: 

 h. lower alpha list
 #. also don't have to start from a

Results in:

  1. lower alpha list

  2. also don't have to start from a

Also roman numerals can begin not only with i/I. Note however they have to begin with number containing more than one letter (xl, iii, CV), in other case they will be treated as alpha lists. Also each list beginning with i/I will be treated as roman, never as alpha which begins at 9th letter of Latin alphabet.

Warning

In LaTeX export starting of lists not from 1/a/A/i/I requires enumitem package.

Auto numerated lists

Lists can be auto numerated. Begin list item with #: 

 #. First item of list
 #. Second item of list

All lists created with # will be displayed as numerated lists. Result:

  1. First item of list

  2. Second item of list

Bulleted lists

Just like enumerated lists, start the line off with a bullet point character -- either "-", "+" or "*": 

 * a bullet using "*"

 - list using "-"

 + yet another list

Results in:

These elements are connected (HTML only). * bulleted list always will be circle, - will be disc and + will be square.

In UTF-8 it is possible to use unicode BULLET characters:

To make nicely looking text documents, however all of them will be treated in output as -.

Embedding of lists

Enumerated and bulleted lists can contain many elements and can be nested. This code will be rendered: 

 1. This is description how to make lists embeddable
    one into other.

        - start one list
        - insert blank line and bigger indentation
        - start another list
        - insert blank line before next element

 2. It is possible to embed paragraphs into list (and blockquotes)
    also.

    Paragraphs and blockquotes have to be separated by blank line and
    start where list begins: indentation of list "leader" plus
    "leader", punctuation sign and space.

         That is memorable quote.

     Those features are not implemented for other types of elements.
     Only: plain paragraphs, blockquotes, ordered lists, bulleted
     lists.

     Indentation level is *very* important. One space can break
     things.

Results in:

  1. This is description how to make lists embeddable one into other.

  2. It is possible to embed paragraphs into list (and blockquotes) also.

    Paragraphs and blockquotes have to be separated by blank line and start where list begins: indentation of list "leader" plus "leader", punctuation sign and space.

    That is memorable quote.

    Those features are not implemented for other types of elements. Only: plain paragraphs, blockquotes, ordered lists, bulleted lists.

    Indentation level is very important. One space can break things.

Definition lists

Unlike the other two, the definition lists consist of a term, and the definition of that term. The format of a definition list is: 

 what
     Definition lists associate a term with a definition.

 *how*
     The term is a one-line phrase, and the definition are body elements,
     indented relative to the term.  Blank lines are not allowed between
     term and first line of definition.

 list
     1. First element of definition
     2. don't have to be
     3. plain paragraph.

Results in:

what

Definition lists associate a term with a definition.

how

The term is a one-line phrase, and the definition are body elements, indented relative to the term. Blank lines are not allowed between term and first line of definition.

list

  1. First element of definition

  2. don't have to be

  3. plain paragraph.

Field list

Special kind of list designed for headers of files or highlighting important information. Paragraph in form: 

 :Author: Mikolaj Machowski
 :Something: Somewhere

Results in:

Author: Mikolaj Machowski
Something: Somewhere

Vim recognizes some names of field list as special and places them in meta info of created documents:

By default date is displayed in LaTeX documents. User can suppress it by using keyword NONE: 

 :Date: NONE

This line will be removed from output and there will be no info about date in exported document.

Option list

Vim reStructured Text recognizes also special type of lists: option lists. It is designed for listing of command options and Vim commands.

It is possible to create list from various types of command line options: 

  -a                  Short form of an option
  --all-name          Long form of an option
  -a, --all-name      Combined listing of option
  +option             Old style options
  /VMS                VMS and DOS style options
  :Vim command        And Vim command -- not available in reST
  --multi-struct      It is possible to use structure elements in
                      option lists::

                           To present examples of use

                      1. Or possible
                      2. uses
                      3. Or any other structure element.

 --in-case-of-very-long-option
                      definition may begin in next line, no trailing space
                      after option name allowed.

Option (command) have to be separated from description by at least two spaces. Above example results in:

-a

Short form of an option

--all-name

Long form of an option

-a, --all-name

Combined listing of option

+option

Old style options

/VMS

VMS and DOS style options

:Vim command

And Vim command -- not available in reST

--multi-struct

It is possible to use structure elements in option lists:

 To present examples of use

  1. Or possible

  2. uses

  3. Or any other structure element.

--in-case-of-very-long-option

definition may begin in next line, no trailing space after option name allowed.

Line blocks

Useful for presenting poetry or some preformatted text but not in monospace font like addresses: 

 | This is *first* line
 |      This is indented **second** line
 |   This is indented slightly less then second
             line, third (long) line
 | And last, :small:`fourth` line

Will result in:

 This is first line
      This is indented second line
   This is indented slightly less then second line, third (long) line
 And last, fourth line

As you see, you can use markup inside of line block paragraphs. Line without "| " starting sequence will be treated as continuation of previous line.

To use | at the beginning of paragraph but without intention of line block creation, escape it with backslash.

Tip

Indentation provided by output writers is visually much smaller than presented in monospace font. Make correction for that.

Preformatting

To just include a chunk of preformatted, text, finish the prior paragraph with "::". The preformatted block is finished when the text falls back to the same indentation level as a paragraph prior to the preformatted block. For example: 

 An example::

       Whitespace, newlines, blank lines, and all kinds of markup
         (like *this* or \this) is preserved by literal blocks.
     Lookie here, I've dropped an indentation level
     (but not far enough)

 no more example

Results in:

An example: 

   Whitespace, newlines, blank lines, and all kinds of markup
     (like *this* or \this) is preserved by literal blocks.
 Lookie here, I've dropped an indentation level
 (but not far enough)

no more example

Note that if a paragraph consists only of "::", then it's removed from the output: 

 ::

     This is preformatted text, and the
     last "::" paragraph is removed

Results in: 

 This is preformatted text, and the
 last "::" paragraph is removed

Quoted literal blocks

Quoted literal blocks are unindented blocks of text where each line begins with the same character: 

 ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~

And previous paragraph ends with ::.

Blank line ends quoted literal block. Quoting characters are preserved. Example: 

 You wrote::

 >> Thanks for your work
 >
 > Glad you appreciate it

 Ha!

Results in:

You wrote: 

 >> Thanks for your work
 >
 > Glad you appreciate it

Ha!

Doctest

Special case of preformatted text are doctest blocks. First line have to begin with ">>>" and can contain only one paragraph of text (without blank lines): 

 >>> print 'Python-specific usage examples; begun with ">>>"'
 Python-specific usage examples; begun with ">>>"
 >>> print '(cut and pasted from interactive Python sessions)'
 (cut and pasted from interactive Python sessions)

Sections

To break longer text up into sections, you use section headers. These are a single line of text (one or more words) with adornment: an underline, in dashes "-----", equals "======", tildes "~~~~~~" or any of the non-alphanumeric characters = - ~ ^ ` * + # that you feel comfortable with (full list of chars is in quoted literal blocks section). The underline must be at least as long as the title text. Be consistent, since all sections marked with the same adornment style are deemed to be at the same level: 

 Chapter 1 Title
 ===============

 Section 1.1 Title
 -----------------

 Subsection 1.1.1 Title
 ~~~~~~~~~~~~~~~~~~~~~~

 Section 1.2 Title
 -----------------

 Chapter 2 Title
 ===============

To make some section titles more outstanding you can use double style headers, with adornments below and above of title. These special lines must be equal, both in characters and length. However, these two titles: 

 =================
 Document title
 =================

 Section title
 =============

Will be treated as two different levels.

In HTML export sections will be numbered thanks to content property. Alas, only small number of WWW browsers are supporting this feature (Konqueror, Opera, Firefox 1.5).

Section headers don't have to be separated with blank line from next paragraph but it is recommended. Simple paragraphs not separated from section header will be treated as subtitles, rest will be treated normally, only directives and special markup explicit blocks are forbidden.

Subtitles

It is possible to provide subtitles for section headers. It should be one, short paragraph placed directly under ornament which will be rendered slightly bigger than normal text. Example: 

 Directives
 ----------
 Or how to place special elements in text

Check rendering of Directives section header.

Links are important part of modern document. Vim reStructured Text allows to create external and internal links. All names declarations are case insensitive. It means both examples will be working: 

 start_

 _start: http://www.vim.org

 `Starting point`_

 .. _starting point: http://www.vim.org

Jump to tables (which is section with title "Tables").

Starting point

Starting point looks like this: 

 We explained `starting point`_ somewhere else

 The same for start_

Note: when start is single entity made from [:alnum:], ., -, _ characters it may not be enclosed in backticks, also if word is constructed from iskeyword characters.

Definition of external target: 

 .. _starting point: http://www.vim.org

 .. _start: http://skawina.eu.org/mikolaj

Note: lack of backticks around titles, even when there is more than one word. Links can be split for several lines: 

 .. _very, very long link description:
        http://this.is.address.com/of/this/description

Definition of internal target can be done in two ways.

First is to put definition in text: 

 some text about _`starting point` explaining this term

Backticks are obligatory.

Second way is anonymous target: 

 .. _starting point:

Very similar to external target just pointing nowhere.

Links can be put directly into text when written explicitly in text: 

 This link to http://skawina.eu.org/mikolaj page by
 mailto:mikmach@wp.pl.

Results in:

This link to http://skawina.eu.org/mikolaj page by mikmach@wp.pl.

Supported protocols: http, https, ftp, mailto.

Definitions of links are boring. For creation of fast links use anonymous hyperlinks. Example: 

 This is link__ to external document. I don't have time to write__ full
 definition.

 __ http://link.to.some.external.doc

 .. __: http://second.link.to.external.doc

As you can see order of links and definitions is important. Should be used only for fast and dirty work.

Links definitions can be starting points defined elsewhere. Example: 

 .. _my wonderful page: start_

 .. _start: http://skawina.eu.org/mikolaj

Should point to my wonderful page.

This can be also used in anonymous links: 

 __ start_

User can even create multi element chains: 

 .. _first elem: secondelem_

 .. _secondelem: thirdelem_

 .. _thirdelem: http://skawina.eu.org/mikolaj

Here is first elem link.

Embedded URIs

A hyperlink reference may directly embed a target URI inline, within angle brackets ("<...>") as follows: 

 See the `Vim-online page <http://www.vim.org>`_ for info.

This is exactly equivalent to: 

 See the `Vim-online page`_ for info.

 .. _Vim-online page: http://www.vim.org

The bracketed URI must be preceded by whitespace and be the last text before the end string. With a single trailing underscore, the reference is named and the same target URI may be referred to again.

With two trailing underscores, the reference and target are both anonymous, and the target cannot be referred to again. These are "one-off" hyperlinks in form: 

 This is `embedded URI <examples.html>`__
 This is `John Smith's mail <mailto:john@smith.info>`__

Note double underscore at the end and declaration of mailto: with e-mail.

There is also possible ultimate compact form: 

 This is link to `<vst-changelog.html>`__.

Results in:

This is link to vst-changelog.html.

It is often boring to write long link texts. Shortening of them is very handy. Vim reStructured Text can do that with: 

 This is |vrest|_.

 .. |vrest| replace:: reST implementation for Vim, **the best** editor of Earth

 .. _vrest: http://skawina.eu.org/mikolaj/vst.html

Results in:

This is reST implementation for Vim, the best editor of Earth.

This also a way to use inline markup inside of links.

Transitions

It is a nice touch to separate some paragraphs and parts of text visually. In some old-fashioned books it is done with small graphics, in newer with eg. row of asterisks * * *.

In Vim reStructured Text you can do this with line of letters, preferred are characters used for sections underscoring: 

 ================================================

 ------------------------------------------------

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 ************************************************

etc. It have to be separated from other elements with blank lines. In exported file they will look like straight line:

Attribution

When quoting text it is nice to add mention about author of quote. Special element of text looks like: 

 This is memorable quote.

         -- John Smith, Esq.

Results in:

This is memorable quote.

— John Smith, Esq.

Some things which may not be visible:

Tables

Vim reStructured Text provides support for two types of tables. With border: 

 +---------------------+----------------+------------------+
 | Cells are           | by bar with    | <Space>|<Space>  |
 | separated           | spaces around  |                  |
 +---------------------+----------------+------------------+
 | *You* may use       | markup,        | included.        |
 | **inline**          | links_         |                  |
 +---------------------+----------------+------------------+
 | You can use various | - like lists   | |VST| will       |
 | types of structure  |                | interpret them.  |
 | elements::          |    + various   |                  |
 |                     |                | Even paragraphs. |
 |  Welcome to world   | - embedded     |                  |
 |  of preformatted    | - one into     | 1. And           |
 |  text.              |   other        | 2. not           |
 |                     |                | 3. only          |
 +---------------------+----------------+------------------+
 | Text may span across several         |                  |
 | columns. Cell can be also empty ->   |                  |
 +---------------------+----------------+------------------+

This is result of table:

Cells are separated

by bar with spaces around

<Space>|<Space>

You may use inline

markup, links

included.

You can use various types of structure elements: 

 Welcome to world  
 of preformatted   
 text.

  • like lists

    • various

  • embedded

  • one into other

Vim reStructured Text will interpret them.

Even paragraphs.

  1. And

  2. not

  3. only

Text may span across several columns. Cell can be also empty ->

For tables containing bigger chunks of structured text it may be better to use border less tables. They are looking almost the same as regular tables with exception of first line which is created with from equal sign: 

 +======================================================================+
 |     This is converted fragment of ChangeLog_                         |
 +============+=========================================================+
 | 5 Apr 2005 | - FIX: [HTML] properly indent preformatted              |
 |            |   text when first line has bigger                       |
 |            |   indentation than next ones                            |
 |            | - CHG: [LaTeX] improve displaying                       |
 |            |   of field lists                                        |
 +------------+---------------------------------------------------------+
 | 6 Apr 2005 | - ADD: Rawlatex  directive                              |
 |            | - ADD: [HTML] use counters in CSS for                   |
 |            |   numbering of `table of contents`_                     |
 |            |   and sections_ in text. At the moment                  |
 |            |   this numbering can be seen only in                    |
 |            |   Konqueror_ 3.4 and Opera_ ver. ?                      |
 +------------+---------------------------------------------------------+

Result of above example:

This is converted fragment of ChangeLog

5 Apr 2005

  • FIX: [HTML] properly indent preformatted text when first line has bigger indentation than next ones

  • CHG: [LaTeX] improve displaying of field lists

6 Apr 2005

Row separator from = will create head of table. Second such row will create foot of table (only in HTML export).

Simple tables

Full tables are hard to correct and in most cases not necessary. Simple tables are much simpler to write and maintain. They have also less features. The most important difference is lack of support for spanning columns. Fragment of changelog rewritten as simple table: 

 ============  ========================================================
 Date          This is converted fragment of ChangeLog_
 ============  ========================================================
 5 Apr 2005    - FIX: [HTML] properly indent preformatted              
                 text when first line has bigger                       
                 indentation than next ones                            
               - CHG: [LaTeX] improve displaying                       
                 of field lists                                        
 6 Apr 2005    - ADD: Rawlatex  directive                              
               - ADD: [HTML] use counters in CSS for                   
                 numbering of `table of contents`_                     
                 and sections_ in text. At the moment                  
                 this numbering can be seen only in                    
                 Konqueror_ 3.4 and Opera_ ver. ?                      
 ============  ========================================================

Results in:

Date

This is converted fragment of ChangeLog

5 Apr 2005

  • FIX: [HTML] properly indent preformatted text when first line has bigger indentation than next ones

  • CHG: [LaTeX] improve displaying of field lists

6 Apr 2005

Another nice example is output of cal program with slight modifications: 

 == == == == == == ==
 su mo tu we th fr sa 
 == == == == == == ==
                   1
 2  3  4  5  6  7  8
 9  10 11 12 13 14 15
 16 17 18 19 20 21 22
 23 24 25 26 27 28 29
 30 31
 == == == == == == ==

Will be shown as:

su

mo

tu

we

th

fr

sa

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

Comments

To comment fragment of text it should be prepended with two dots: 

 .. This text will be commented.

    This text also will be commented.

 But this not.

To make commenting easier dots can be in previous line: 

 ..
     This line will be commented.

 And this not.

However, when line with two dots (and only two dots, eventually spaces) will be followed by blank line even indented lines won't be commented out.

Comments may be useful to place in output code useful things like Vim modelines: 

 .. vim:set tw=72:

or folding markers: 

 .. {{{

 .. }}}

These lines will be in exported format, just not visible.

Footnotes

You can include in text special links to fragments which don't match into current paragraph, and place those fragments wherever you want in document. Vim reStructured Text supports three types of footnotes: numbered, labeled and auto-numbered.

It is possible to use many structure elements in footnotes. They have to be indented up to ``[`` opening footnote declaration.

Text of footnotes cannot be placed inside of tables.

Numbered footnotes

The simplest one. Number is manually assigned to footnote. Example: 

 This doesn't belong here[1]_.

 .. [1] I will describe it here.

Results in:

This doesn't belong here[1].

[1]

I will describe it here.

There are numbered footnotes, try to keep them in order to not disorientate readers. Vim reStructured Text will not warn about duplicate footnotes.

Auto-numbered footnotes

In this type footnotes are declared by author only with [#]_. Text of footnote will look like: 

 .. [#] Footnote text.

Order of # signs is very important. First [#]_ will be connected with first .. [#], second [#]_ with second .. [#] and so on.

Labeled footnotes

Marking footnotes with [#]_ is fast but user can easily lost orientation. Solution can be use of labeled footnotes. Example: 

 This is labeled[#lfoot]_ footnote.

 .. [#lfoot] Labeled footnote looks similar to auto numbered but # is
    followed by short alphanumeric description.

Mixing of footnotes

User can mix types of footnotes but results can be unexpected (and for sure they will be different from reST).

First numbers will be assigned to numbered footnotes, labeled footnotes will follow with first number bigger then maximum number of numbered footnotes. Numbers to labels will be assigned in order of use of labels in text. The last ones will be auto-numbered footnotes.

Note

Numbering of footnotes in LaTeX will strictly follow order of footnotes. With mixed types is high probability numbers of footnotes in two types of export will be different.

Citations

Special case of footnotes are citations. In form: 

 This is citation [Smith1995]_

 .. [Smith1995] John Smith, *Something about nothing*, Kein Press, 1995.

Will create footnote-like paragraph and link to this paragraph.

Directives

Or how to place special elements in text

You can achieve special treating of some paragraphs by using directives. They have always a form of: 

 .. directive::

Some directives can contain many various elements of text like lists, preformatted text, even other directives.

Unknown directives will be displayed in red frame and in monospace font.

Images

To include an image in your document, you use the image directive. For example: 

 .. image:: test.png

Spaces in filename should be avoided (or encoded as %20, but can work properly on standard settings.

Image examples

You can supply additional information about image with options: 

 .. image:: test.png
    :width: 200
    :height: 100
    :alt: Alternative text
    :title: Title of image

Results in:

Alternative text

Getting info about image dimensions is boring. You can use special option :identify: which uses program from ImageMagick suite of programs (available on most OS where Vim is available): 

 .. image:: test.png
    :identify:
    :alt: Alternative text
    :title: Title of image

identify: can handle argument which will serve as scale factor. 100 is scale 1:1, scale will decrease size of image only in document. Real size of image will not change: 

 .. image:: test.png
    :identify: 50
    :alt: Alternative text
    :title: Title of image

Similar effect can be achieved with option :scale:. Note that :identify: argument and :scale: will accumulate. If you declare 50 in both image will have only 25% of linear size.

It is possible to make image a link with option :target:: 

 .. image:: test.png
    :target: http://www.vst.info/test.png

It will make image a link to other image. When you are scaling image view it is a good idea to make it clickable and point to full scale version -- possible with special argument self (note limited usability in LaTeX export): 

 .. image:: test.png
    :identify: 50
    :target: self
    :alt: Alternative text
    :title: Title of image

Results in:

Alternative text

Figures

Figure is special construction which creates image with following text elements will be placed in separate frame with possible text flowing around (HTML only): 

 .. figure:: test.png
    :identify:

    This is description of this figure.

    1. Can use 
    2. Different elements

Spaces in filename should be avoided (or encoded as %20, but can work properly on standard settings.

Topic

A topic is like a block quote with a title, or a self-contained section with no subsections. Use the "topic" directive to indicate a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur.

The directive's sole argument is interpreted as the topic title; the next line must be blank. All subsequent lines make up the topic body, interpreted as body elements. Example: 

 .. topic:: Header of topic

      These lines are topic content interpreted
      as body elements.

A sidebar is like a block quote with a title (also can be subtitle). Use the "sidebar" directive to indicate a self-contained idea that is separate from the flow of the document.

The directive's sole argument is interpreted as the sidebar title; the next line must be blank. All subsequent lines make up the sidebar body, interpreted as body elements. Example: 

 .. sidebar:: Header of subtitle
    :subtitle: Why this is important

      These lines are sidebar content interpreted
      as body elements.

Table of contents

For longer text it is good idea to put in document table of contents. In Vim reStructured Text you can place table of contents at desired position with directive: 

 .. contents::

In exported document it will be replaced by unordered list with elements indented to present structure of document.

When contents directive is used sections headers will become links to corresponding entries in table of contents.

In HTML export table of contents will be numbered thanks to content property. Alas, only small number of WWW browsers are supporting this feature (Konqueror, Opera, Firefox1.5).

Replacement

This is an exception from general format of directive: 

 .. |from| replace:: into

It consists of four parts: leading commas; source part enclosed in bars; name of directive -- replace::; and the rest of line which will replace source in file (without leading space). Beware: from and into elements are processed through substitute() Vim function and have to be proper Vim regexps. Three characters will be escaped automatically: \ & ~.

Inline images

Special type of replacement, designed for placement of images inline and in tables.

In text you can use it as normal replacement but declaration is different: 

 .. |from| image::image.jpg
    :width: 20 
    :height: 20 
    :target: URL

All options of Images directive are supported.

Result looks like that: test.png.

Unicode

Not all characters can be shown in localized encodings. For the rest it is possible to use Unicode (U+ followed by hexadecimal number): 

 .. |from| unicode:: U+2211 .. Sigma sign

This text will replace marker into unicode sigma sign. Encoding of output document, regardless of current Vim encoding will be set to utf-8. Text after two dots will be ignored.

User can put longer text in replacement: 

 .. |200E| unicode:: 200 U+20AC .. 200 euro

Spaces will be removed from output.

Unicode directive accepts one of three options:

:ltrim:

Will remove space from the left side of sign.

:trim:

Will remove space from left and right side of sign.

:rtrim:

Will remove space from right side of sign.

Warning

Date

Inserting of date is tedious. To make it simpler use date replacement directive: 

 .. |date| date::

 .. |time| date:: %H:%M

Without arguments placeholder will be replaced with date in ISO format YYYY-MM-DD. Arguments are following strftime() syntax. This function isn't available on all systems, in such case placeholder will be replaced with seconds from epoch :)

Including commands

With bigger sets of documents some parts can be repeated. In such case it is good idea to put them in external file and only include it in proper place. Also it gives profits when making changes. User have to only make correction in one file, not in whole collection. Vim reStructured Text provides three directives. All are making the same thing -- include text file -- written in VST before any other activity.

  1. This command will include file in given place: 

     .. header:: {filename}

    Regardless of placement of this directive file will be put in the beginning of exported file.

  2. This command will include file in given place: 

     .. include:: {filename}

  3. This command will include file in given place: 

     .. footer:: {filename}

    Regardless of placement of this directive file will be put at the end of exported file.

Note

To avoid endless loops level of recursiveness is equal to Vim's option 'maxfuncdepth'/2 (default: 50).

Tip

This directive can contain many various elements: 

 .. tip:: First paragraph.

     1. List element
     2. List element

     Second paragraph

Above example results in:

Tip

First paragraph.

  1. List element

  2. List element

Second paragraph

All elements must have bigger indentation than directive. These elements will be placed in green frame and with title 'Tip'.

Note

This directive can contain many various elements: 

 .. Note:: First paragraph.

        Remember these noble words.

    Second paragraph

Above example results in:

Note

First paragraph.

Remember these noble words.

Second paragraph

All elements must have bigger indentation than directive. These elements will be placed in black frame and with title 'Note'.

Warning

This directive can contain many various elements: 

 .. Warning:: First paragraph.

     - List element
     - List element

     Second paragraph

Above example results in:

Warning

First paragraph.

Second paragraph

All elements must have bigger indentation than directive. These elements will be placed in red frame and with title 'Warning'.

Admonition

General form of multi element message directive (MEMD). Have form: 

 .. admonition:: <title>
    :class: <class>

    Text of admonition (many elements).

Directive can be used as i18n version of any other MEMD.

Pull-quote

Semantically similar to blockquote but in addition to being indented text will be displayed with bigger font to attract attention: 

 .. pull-quote:: 

    This is time of our lives!

Results in:

This is time of our lives!

Container

General block directive: 

 .. container:: classname

HTML output: 

 <div class="classname"> content of container </div>

LaTeX output: 

 \vstclassname{ content of container }

Note vst prefix to avoid possible conflicts with built-in (La)TeX commands. In preamble will be inserted simple template to allow compilation of document without stopping on unknown commands: 

 \newcommand{\vstclassname}[1]{#1}

It will be inserted before declaration of extension of preamble by external file. If user wants to declare there these new commands he should use renewcommand LaTeX command.

Compound

Similar to container but designed to distinguish text rather semantically, not visually:

Class

This directive allows to apply arbitrary class name to most block elements (HTML only): 

 .. class:: name

There is an exception: Class directive will be ignored for directives which has :class: option.

If next element has the same level of indentation class will be applied only to that alement. But if next elements has bigger indentation class will be applied to all of them: 

  .. class:: name

     First paragraph

     Second paragraph

 Third paragraph

name class will be applied to first and second paragraph but to to third.

Note

name class style will be added to default style, not replace it.

Default role

This role sets default text role used for interpreted tex without declared role. For example, after setting: 

 .. default-role:: newstyle

Text enclosed in backticks will be presented with help of newstyle class. Default role for Vim reStructured Text is title reference.

Meta

This directive can be useful when providing meta data which user don't want to be visible in form of field list: 

 .. meta::
    :author: Mikolaj Machowski
    :subject: Vim reStructured Text
    :http-equiv=Content-Type: text/html; charset=iso-8859-2
    :description lang=en: Special text formatting

In HTML export this list will be included into meta tags of header. In LaTeX four keywords will be recognized and put into PDF info: author, title, subject, keywords.

Title

Title directive may be used to place your own text in title tag of HTML export or in PDF info fields. This title will not be visible in document itself: 

 .. title:: VST documentation

Rubric

This directive shows line as header but without semantic meaning of header: 

 .. rubric:: This may be of interest for readers

Raw

Raw latex

HTML and pure text are often not enough to present some mathematical concepts. You can use then raw LaTeX directive: 

 .. raw:: latex

 .. raw:: tex

Content of this directive will not be visible in HTML export and in LaTeX literally. This directive must be a one paragraph of Vim reStructured Text -- without blank lines. But you can make it multi paragraph LaTeX content with \par command: 

 .. raw:: latex

             This is first par with special $\pi$ content.
     \par
             This is second par with special $\alpha$ content.
     \par
             \emph{Indentation} doesn't have special meaning but it is
             good for visual separation of \texttt{paragraphs}.

Results in:

Content of this directive (and above example) will not be visible in HTML export. This directive must be a one paragraph of Vim reStructured Text -- without blank lines.

Raw latex replaces latexonly directive which is considered deprecated.

Raw html

 .. raw:: html

 .. raw:: html

       <p>CO<sub>2</sub></p>

Results in:

CO2

Content of this directive (and above example) will not be visible in LaTeX export. This directive must be a one paragraph of Vim reStructured Text -- without blank lines.

Raw html replaces htmlonly directive which is considered deprecated.

Both

Directive will accept also two arguments (HTML and LaTeX), it will be passed without any modifications in two exports: 

 .. raw:: html latex

Order is not significant.

2html

Note

Not available in reST. Colors in HTML only.

Directive designed to make use from 2html.vim script for syntax highlighting of code: 

 .. 2html:: [{filetype}]

 .. 2html:: filetype [{colorscheme}]

2html directive is extended declaration of empty double colon. Following paragraphs have to be separated by blank line and must have bigger indentation.

Tip

Not all colorschemes look good when exported to HTML. It is wise idea to check result before official presentation. Especially default is hard to read on white background -- and this is default combination when doing export from non-GUI version of Vim. It is a good idea to set g:colors_name somewhere because it will be used in such case. When you try to export this document on your system check example below with manxome colorscheme which is not included in default Vim distribution.

2html examples

Fragment of vst.vim in blue colorscheme: 

 .. 2html:: vim blue

     if exists('depth') && depth != ''
         let hdepth = strpart(g:ptype[j], '1')
         if hdepth > depth
             let j += 1
             continue
         endif
     endif

Result: 

 if exists('depth') && depth != ''
     let hdepth = strpart(g:ptype[j], '1')
     if hdepth > depth
         let j += 1
         continue
     endif
 endif

The same fragment in manxome: 

 if exists('depth') && depth != ''
     let hdepth = strpart(g:ptype[j], '1')
     if hdepth > depth
         let j += 1
         continue
     endif
 endif

And fragment of Vim itself -- ex_cmds.c by murphy. Declaration: 

 .. 2html:: c murphy

 if (fp_out != NULL)
 {
 (void)mch_setperm(tempname,
           (long)((st_old.st_mode & 0777) | 0600));
 /* this only works for root: */
 (void)chown((char *)tempname, st_old.st_uid, st_old.st_gid);
 }

Macros

Not everything can be done with VST syntax. Here are coming macros. Macro is keyword with optional value after colon like: 

 {macroname:argument}

They are not codified. To show what can be achieved with them to distribution is added myhtmlvst.vim file with examples of two macros: 

  1.  {read:file}

    First macro read file and put it inside of pre tag (it is like Vim :read command). 

  2.  {readpython:file}

    Second macro interpret contents of file and put it also in pre tag (like Vim :read! command).

    This command is smart. It can catch name of program between read and : and call it later. Thus it can become {readperl}, {readruby}, {readbash}, etc. Program name has to match \w\+ regexp.

    readbang has special value -- it will execute shell command.

    Warning

    This macro can have serious security consequences!!!

These two macros are line wise and must be kept in separate lines with nothing around them.

Macro file is executed with help of g:vst_html_post variable.

Thanks

I'd like to say thanks to:

FAQ