Skip to content
This repository

Restructured Text snippets and code completion hotkeys for Sublime Text 2 and 3

branch: master
Octocat-spinner-32 img image folding June 23, 2013
Octocat-spinner-32 .gitignore ignore metadata May 10, 2013
Octocat-spinner-32 Comments.tmPreferences Added comments support March 15, 2014
Octocat-spinner-32 Default (Linux).sublime-keymap Merge pull request #70 from Kronuz/list-indent March 16, 2014
Octocat-spinner-32 Default (OSX).sublime-keymap Merge pull request #70 from Kronuz/list-indent March 16, 2014
Octocat-spinner-32 Default (Windows).sublime-keymap Merge pull request #70 from Kronuz/list-indent March 16, 2014
Octocat-spinner-32 LICENSE demo and license August 21, 2013
Octocat-spinner-32 Main.sublime-menu Add a preferences menu and a settings file. December 13, 2013
Octocat-spinner-32 README.rst Header level adjustment in OS X using alt + plus and alt + minus February 23, 2014
Octocat-spinner-32 RestructuredText.sublime-completions Added new header levels March 27, 2014
Octocat-spinner-32 footnotes.py is_enabled() in Sublime Text 3 needs to return a boolean February 22, 2014
Octocat-spinner-32 headers.py Merge pull request #65 from Kronuz/level-adjustment February 26, 2014
Octocat-spinner-32 helpers.py Fix BaseBlockCommand to work with block at the boundaries of the view February 26, 2014
Octocat-spinner-32 indent_list_item.py Match whole line so it works for all levels March 16, 2014
Octocat-spinner-32 lists.py merge 26_middle_list_item. Fix #26 August 01, 2013
Octocat-spinner-32 render.py Read command_path from settings and add it to current PATH environmen… December 13, 2013
Octocat-spinner-32 simpleformat.py Merge pull request #59 from Kronuz/better-surround February 22, 2014
Octocat-spinner-32 sublime-rst-completion.sublime-settings Add a preferences menu and a settings file. December 13, 2013
Octocat-spinner-32 tables.py naming refactor: simpler/better module names July 23, 2013
README.rst

Sublime Text Restructured Text Code Completion (rst)

A group of snippets and commands to facilitate writing restructuredText with Sublime Text 2 (and, experimentally, 3). This plugin will hopefully evolve to make Sublime a useful documentation toolkit.

Demo

http://img.youtube.com/vi/otM_tjIi_vY/0.jpg

Install

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 git@github.com:dbousamra/sublime-rst-completion.git
    
  • Or download the .zip file and unzip it into your ST2/ST3 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

Usage

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+alt+i (super+shift+i on Mac)
se strong emphasis (bold) ctrl+alt+b (super+shift+b on Mac)
lit or literal literal text (inline code) ctrl+alt+k (super+shift+k on Mac)
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

Render preview

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.

Magic Tables

There is a particular magic expansion for tables. Here is how it works:

  1. 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.
    
  2. Put your cursor somewhere in the content to convert as table.

  3. Press ctrl+t, enter (Linux or Windows) or super+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 :

Smart lists

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 suffixed with a period (a. b. c. ..., A. B. C. ..., i. ii. iii. iv. ..., X. XI. XII. ..., #.); surrounded by parentheses ((a) (b) (c) ..., (A) (B) (C) ..., (i) (ii) (iii) (iv) ..., (X) (XI) (XII) ..., (#)); or suffixed with a right-parenthesis. (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

Headers

Autocompletion

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.

Folding/unfolding

If you put the cursor in a completed header and press shift + TAB (alt + TAB in Mac), the section under it will be folded/unfolded.

For example:

Folding/unfolding
+++++++++++++++++<TAB>

If you put the cursor in a completed header and press ``shift + TAB``,
(``alt + TAB`` in Mac) the section under it will be folded/unfolded.

Navigation
++++++++++

...

Result in:

https://raw.github.com/dbousamra/sublime-rst-completion/11_foldable_headers/img/folding.png

Nested sections under a header are included.

Navigation

Also, it's possible to jump between headers. alt+down and alt+up move the cursor position to the closer next or previous header respectively.

alt+shift+down and alt+shift+up to the same, but only between headers with the same or higher level (i.e. ignore childrens)

The header level is detected automatically.

Adjust header level

With the cursor in a header, press ctrl + + (plus key) and ctrl + - (minus key) (alt + + and alt + -, in Mac) will increase and decrease the header level respectively. The adornment decoration (underline / overline) are autodetected from the document and uses Sphinx's conventions as default.

For example, you have the cursor in:

Magic Footnotes|
---------------

Which is a header level 2 and want to convert to a level 3, press ctrl + - to get:

Magic Footnotes
+++++++++++++++
|

Magic Footnotes

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. This will happen:

  • A new n+1 (where n 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 just after a reference (i.e: the caret is next to the underscore like this [XX]_| ) you can jump to its definition with shift+down [1].

This feature is based on the code by J. Nicholas Geist for MarkdownEditing

Authors

Tip

Pull requests and bug reports are welcome!

License

It's under a BSD license .

[1] in fact, you can also jump forward and back between notes with the general alt+shift+f
Something went wrong with that request. Please try again.