A group of snippets and commands to facilitate writing restructuredText with Sublime text editor. This plugin will hopefully evolve to make Sublime a useful documentation toolkit.
The easiest way to install is via Sublime Package Control . Just look for "Restructured Text (RST) Snippets"
Otherwise you can:
Clone the repository into your packages folder:
git clone [email protected]:dbousamra/sublime-rst-completion.git
Or download the .zip file and unzip it into your ST2 packages directory.
Optionally, to use the preview rendering feature, you need to install at least one of
Pandoc, docutils or rst2pdf and they should be accesibles in your PATH
.
In debian/ubuntu you can install them via apt-get
:
$ sudo apt-get install pandoc docutils rst2pdf
Simple snippets work as tab-triggered shortcuts: type the shortcut and press <TAB>
to
replace it with the snippet. If the snippet has placeholders, you can jump between them
using tab.
shortcut | result | key binding |
---|---|---|
h1 |
Header level 1 | see Header completion |
h2 |
Header level 2 | |
h3 |
Header level 3 | |
e |
emphasis | ctrl+i |
se |
strong emphasis (bold) | ctrl+b |
lit or literal |
literal text (inline code) | control+k |
list |
unordered list | see Smart Lists |
listn |
ordered list | |
listan |
auto ordered list | |
def |
term definition | |
code |
code-block directive (sphinx) | |
source |
preformatted (:: block) |
|
img |
image | |
fig |
figure | |
table |
simple table | ctrl+t see Magic
Tables |
link |
refered hyperlink | |
linki |
embeded hyperlink | |
fn or cite |
autonumbered footnote or cite | alt+shift+f see
Magic Footnotes |
quote |
Quotation (epigraph directive) |
Also standard admonitions are expanded:
shortcut |
---|
attention |
caution |
danger |
error |
hint |
important |
note |
tip |
warning |
You can preview your document in different formats converted with different tools
pressing ctrl+shift+r
.
The Quick Window will offer the format and tool and the result will be automatically open after the conversion.
By the moment, it can use Pandoc, rst2pdf, or rst2*.py
tools (included with
docutils) to produce html
, pdf
, odt
or docx
output formats.
Each time you select a format + tool
option, it turns the default the following times.
Note
The original code is from the SublimePandoc project.
There is a particular magic expansion for tables. Here is how it works:
Create some kind of table outline, separating column with two or more spaces:
This is paragraph text *before* the table. Column 1 Column 2 Foo Put two (or more) spaces as a field separator. Bar Even very very long lines like these are fine, as long as you do not put in line endings here. This is paragraph text *after* the table.
Put your cursor somewhere in the content to convert as table.
Press
ctrl+t, enter
(Linux or Windows) orsuper+shift+t, enter
(Mac). The output will look something like this:This is paragraph text *before* the table. +----------+---------------------------------------------------------+ | Column 1 | Column 2 | +==========+=========================================================+ | Foo | Put two (or more) spaces as a field separator. | +----------+---------------------------------------------------------+ | Bar | Even very very long lines like these are fine, as long | | | as you do not put in line endings here. | +----------+---------------------------------------------------------+ This is paragraph text *after* the table.
Now suppose you add some text in a cell:
+----------+---------------------------------------------------------+ | Column 1 | Column 2 | +==========+=========================================================+ | Foo is longer now | Put two (or more) spaces as a field separator. | +----------+---------------------------------------------------------+ | Bar | Even very very long lines like these are fine, as long | | | as you do not put in line endings here. | +----------+---------------------------------------------------------+
Press the same trigger: magically, the structure will be fixed:
+-------------------+--------------------------------------------------------+ | Column 1 | Column 2 | +===================+========================================================+ | Foo is longer now | Put two (or more) spaces as a field separator. | +-------------------+--------------------------------------------------------+ | Bar | Even very very long lines like these are fine, as long | | | as you do not put in line endings here. | +-------------------+--------------------------------------------------------+
In addition, if you would like to keep the column width fixed, you could reflow the table pressing ctrl+t, r
(super+shift+t, enter
in Mac). The result would be this:
+----------+---------------------------------------------------------+ | Column 1 | Column 2 | +==========+=========================================================+ | Foo is | Put two (or more) spaces as a field separator. | | longer | | | now | | +----------+---------------------------------------------------------+ | Bar | Even very very long lines like these are fine, as long | | | as you do not put in line endings here. | +----------+---------------------------------------------------------+
With the base trigger combination and the cursors you can merge simple cells. For example, suppose you have this table:
+----+----+ | h1 | h2 | +====+====+ | 11 | 12 | +----+----+ | 21 | 22 | +----+----+
Move the cursor to the cell 12
and press ctrl+t, down
. You'll get this:
+----+----+ | h1 | h2 | +====+====+ | 11 | 12 | +----+ | | 21 | 22 | +----+----+
Note
The original code of this feature was taken from Vincent Driessen's vim-rst-tables :
Ordered or unordered lists patterns are automatically detected. When you type something like this:
1. Some item 2. Another|
When press enter
the newline will prepended with a logical next item:
... 2. Another 3. |
If you press enter
when the item is empty, the markup is erased keeping
the same indent as the previous line, in order to allow multilines items.
Also note that orderer list works with an alphabetic pattern or roman numbers pattern
(a. b. c. ...
, A. B. C. ...
, i. ii. iii. iv. ...
, X. XI. XII. ...
).
Tip
The very same feature works for line blocks starting a line with |
.
Note
This feature was proudly stolen from Muchenxuan Tongh's SmartMarkdown
You can autocomplete standard headers (over/)underlines with TAB.
For example try this:
**********<TAB> A longer main title *******
Or this:
A subtitle ---<TAB>
You'll get:
******************* A longer main title ******************* A subtitle ----------
respectively.
This is the smarter way to add footnotes, grouping them (and keepping count) in a common region at the bottom of the document.
When you want to add a new note, press alt+shift+f
(super+shift+f
in Mac).
This will happen:
- A new
n+1
(wheren
is the current footnotes count) note reference will be added in the current cursor position - The corresponding reference definition will be added at the bottom of the footnotes region
- The cursor will be moved to write the note
After write the note you can go back to the reference with shift+up
. Also, if
the cursor is over a reference (i.e: around something like [XX]_
) you can jump to its
definition with shift+down
[1].
This feature is based on the code by J. Nicholas Geist for MarkdownEditing
- Most features added by Martín Gaitán (mgaitan)
- Original idea by Dominic Bou-Samra (dbousamra)
- An few gentle contributors
Tip
Pull requests and bug reports are welcome!
License: Seriously? It's a text editing plugin.
[1] | in fact, you can also jump forward and back between notes with
the general alt+shift+f |