Guide to rst-mode

Emacs loads rst-mode whenever you open a file it registers as reStructuredText. In addition to enabling syntax highlighting, it enables the following functions. In the event that it does not, you can enable it from the prompt: M-x rst-mode. You can also extend the list of extensions that Emacs reads as containing reStructuredText by adding the following lines to your init.el configuration file:

;; reStructuredText
(setq auto-mode-alist (append
             '( ("\\.txt\\'" . rst-mode)
                ("\\.rst\\'" . rst-mode)
                ("\\.rest\\'" . rst-mode))
             auto-mode-alist))

From version 24.3, Emacs contains rst-mode by default. You don’t need to install any additional packages unless you would like a more current release.

See also

For more information on rst-mode, see Emacs Support for reStructuredText.

Commands

Command Macro Description
rst-adjust C-c C-= Adjust section title adornment, cycle forwards.
  C-- C-= Adjust section title adornment, cycle backwards.
rst-backward-section C-M-a Move back to previous section title.
rst-bullet-region C-c C-l C-b Converts region to bullet list.
rst-compile C-c C-c C-c Run primary RST compiler.
rst-compile-alt-toolset C-c C-c C-a Run secondary RST compiler.
rst-compile-preview C-c C-c C-p Compile to PDF and open viewer.
rst-compile-pseudo-region C-c C-c C-x Compile to pseudo XML and open into a new buffer.
rst-compile-slides-preview C-c C-c C-s Compile to S5 slides and open into a web browser.
rst-enumerate-region C-c C-l C-e Converts region to enumerated list.
rst-forward-section C-M-e Move forward to next section title.
rst-line-block-region C-c C-r C-l Convert region to line block.
rst-mark-section C-M-h Select section.
rst-straighten-bullets-region C-c C-l C-s Replaces bullets in active region, so that it uses - for top-level and * for second-level.
rst-toc C-C C-t C-t Open Table of Contents navigation window.
rst-toc-insert C-c C-t C-i Insert table of contents text.
rst-toc-update C-c C-t C-u Update table of contents inserted in a comment block under the contents directive.

Table of Contents

When you add a new section title in reStructuredText, it registers during builds as part of the table of contents. Each entry in the table is section title, indented to the appropriate level.

You can access and navigate this table, by using the rst-toc function, callable with C-C C-t C-t. This opens a minibuffer that you can move the cursor through to the point you want to view, then click Enter to move to that point in the buffer. The Table of Contents buffer supports the following commands:

Key Mouse Description
f or RET button1 Open to selection and quit buffer.
  button2 Open to selection, leave buffer open.
q   Quit buffer.
z   Zap buffer, leave split.

Inserting a Table of Contents

In some situations, you may want to maintain a local table of contents, to appear at the top of the document that provides the structure of the document with links down to headings on the page.

While this is easy enough to do in Sphinx with the contents directive, it’s somewhat more complicated in the event that you would like to maintain a local instance in the source code. In Emacs, rst-mode provides you with a solution.

To insert a table of contents, use the rst-toc-insert function, which you can call with the command C-c C-t C-i. The recommended method of doing this is is to first create a contents directive, the add a comment line, creating the new table of contents within the comment. This ensures that you get links in the output and text in the file.

For instance, running it on this document produces the following results:

.. contents::
..
   1  Table of Contents
     1.1  Inserting a Table of Contents
   2  Section Headings
     2.1  Adjusting Adornments
     2.2  Adornment Hierarchy
     2.3  Adornment Customization
   3  List Operators
     3.1  Converting Regions
     3.2  Adjusting Bullet Hierarchy
   4  Miscellaneous Blocks
     4.1  Line Blocks
     4.2  Comment Blocks
   5  Compile Support
     5.1  Previews
   6  Customization

You can adjust the output for this command using the rst-toc-indent, rst-toc-insert-style and rst-toc-insert-maxlevel variables.

As time goes on and you continue to edit and expand the document, you’re likely to add a number of new sections along the way. When the table of contents is done properly, (that is, in a commented section preceded by the contents directive for output), you can update it by running the rst-toc-update command, called with C-c C-t C-u.

Section Headings

In reStructuredText, section headings are marked by a series of punctuation marks above and below or just below the title that you want to use. Usually, a marker is set just below this to create the identifier reference in links. For instance,

================================
Writing reStructureText in Emacs
================================
.. _`write-rst-emacs`:

By default, loading rst-mode provides you with the appropriate syntax highlighting for this text, which may prove useful in skimming to particular sections in the file. In addition, rst-mode also provides functions that you may find useful in manipulating section titles.

You can navigate between sections using the rst-backward-section and rst-forward-section. To select an entire section, use rst-mark-section.

Adjusting Adornments

Section adornment can prove tedious when handling them manually. When using the above and below format, both must have the same length. While they can be longer than the containing text, Sphinx throws an errors when they’re shorter. Moreover, changing them requires that you delete the line and type it out again.

The rst-adjust function is a general purpose call for dealing with problems like this. That is, it operates on the current line, cycling through common tasks until you find the one that you want.

  • When the adornment is incomplete, that is if it’s shorter or longer than the containing text or otherwise inconsistent, this corrects the adornment to match the appropriate standard.
  • When there is no adornment on the current line, it adds the appropriate section title adornment. By default, it chooses the same adornment level as you used on the last section title. To adjust this behavior, see Adornment Customization below.
  • When you already have the correct section title adornment, it cycles through the adornment levels. The cycle is limited to those instances in the current file.

When you use the command C-c C-=, the function cycles through this list from top to bottom. When you use the command C-- C-=, it cycles from bottom to top.

Note

You can also adjust section title adornments globally using rst-straighten-adornments. By default, this is called with the macro: C-c C-a C-s. Use it in the event that youw ant to change all section title adornments in the given file.

Adornment Hierarchy

By default, when you cycle through the available section title adornments, rst-mode limits itself to = and any others available in the file. You can view the current file hierarchy by issuing the rst-display-adornments-hierarchy command, callable through the macros C-c C-a C-d. This opens a minibuffer that names each section with the relevant section title adornment set around it.

Adornment Customization

In the event that you spend a lot of time working with reStructuredText, you may find the default adjustment behavior insufficient. That is for any level below =, you have to still have to enter the first few characters manually. By default, oly on the = level can you set section title adornment using a macro.

Using the rst-preferred-adornments variable in your init.el configuration file, you can adjust the section title adornments available to you. For instance, to set the adornments recommended by Sphinx, you might use something like this,

(setq rst-preferred-adornments
      '((35 over-and-under 0) ; ?# For parts
        (42 over-and-under 0) ; ?* For chapters
        (61 simple 0)         ; ?= For sections
        (45 simple 0)         ; ?- For subsections
        (94 simple 0)         ; ?^ For subsubsections
        (34 simple 0))        ; ?" For paragraphs
      )

Bear in mind that when Sphinx renders a files into HTML pages, it adjusts this count to match the local page. When it renders a project into LaTeX, it makes a similar adjustment to match the global hierarchy. Your markup does not have to match these terms exactly in order for them to correctly render into the output format.

List Operators

In reStructuredText there are two types of lists: enumerated and bullet. This is comparable to the ordered and unordered lists in HTML, respectively. While lists are intentionally simple in reStructuredText, rst-mode does provide you with some operators to help make it even easier to work with them.

Converting Regions

It is relatively simple to create a list in reStructuredText. You add a basic markup to the start of the line to initialize a list item, then indent any paragraphs over two (bullet) or three (enumerated) spaces to include them in that list item. For instance,

#. First Enumerated List Item,
   with text in same paragraph.

#. Second Enumerated List Item.

While you may not have any trouble with this while writing a list, it can make things easier when editing sections of text that you need to convert into a list. This is especially the case when you have several lines that require the appropriate indentation to group them within individual list items.

To convert a region to a list, highlight it and then use rst-enumerate-region or rst-bullet-region.

Note

rst-enumerate-region renders the markup as the numerals, followed by a period. When working with Sphinx, you may find it more convenient to write hash period, as this does not alter the output and is easier to maintain over the long term.

Adjusting Bullet Hierarchy

When programs like Sphinx sort through bullet lists, they register both the - and * characters as identical in registering a list item. However, you may find it convenient to use both in order to visual distinguish the first and second levels of a bullet list.

When you select a bullet list region and run rst-straighten-bullets-region, it converts the starting characters, using the dash for the top level and the asterisk for the second.

Miscellaneous Blocks

In addition to blocks, rst-mode also provides functions for line blocks and comments.

Line Blocks

When Sphinx processes reStructuredText, it converts line blocks into block quotes in HTML. That is, a small block set aside from the usual paragraphing. You can render the markup using the pipe character. For instance, say you wanted to quote the opening lines of the epic Beowulf, in Anglo-Saxon:

| Hwæt, we gar-dena in geardagum,
| þeodcyninga þrym gefrunon,
| hu ða æþelingas ellen fremedon!

Similar to the list operations above, rst-mode provides you with a function to add and remove the pipe character. You may find this useful when putting a large body of text into a line block.

To add the region to a line block, select it at run the rst-line-block-region command, or C-c C-r C-l. To remove the region from a line block, select it and run the same command with a prefix argument.

Comment Blocks

In reStructuredText comments are rendered by prefixing a line with two periods, (“..”). Lines below this point that receive the appropriate level of indentation are also considered as part of the comment. For example,

Text in visible paragraph.

.. Comment Title

   Text in commented paragraph.

Text in visible paragraph

In Emacs, the way to convert a line or region into a commented section is to use the function comment-dwim, which you can call using the command M-;. The way to remove a comment is to call it again with a prefix argument.

Note

Only indented comments have proper support. That is, comment-dwim only works on regions.

Compile Support

The advantage of working in reStructuredText lies in document conversion. That is, while you can write in plain text using simple markup conventions, using external utilities you can then compile your project into a presentation format, such as HTML or LaTeX. rst-mode provides functions and commands for this conversion.

When you call rst-compile, Emacs constructs a compile command based on its primary tool-set, which is rst2html.py by default. When you call rst-compile-alt-toolset, it does the same using its secondary tool-set, which is rst2latex.py by default. When you call rst-compile-pseudo-region, it does the same for the active region using rst2psuedoxml.py and shows the results in a new buffer.

You can adjust the configuration for rst2html.py and rst2latex.py by writing a docutils.conf file and placing it in the parent directory. To customize or define the commands Emacs uses to compile ReStructuredText, set rst-compile-primary-toolset and rst-compile-secondary-toolset.

Previews

On occasion, you may want to view the results of your builds immediately. You can do so using the preview commands. rst-compile-pdf-preview runs the LaTeX build, then generates and opens a PDF in the viewer. rst-compile-slides-preview does the same with S5 slides.

Note

In Fedora, the Atril Document Viewer updates automatically when the source PDF receives an update. This is different from many other PDF document viewers, such as Preview.app on Mac OS X. You may find it more convenient to work with than having Emacs open a viewers on every compile.

To install Atril, use DNF:

# dnf install atril

Customization

You can customize certain features of how rst-mode handles and formats certain features. You can enable these features permanently by adding them to your init.el configuration file or you can turn them on for the current session.

To view all customization options available, run M-x customization-group then enter rst. If you are using Emacs in a graphical environment, you can also go through the menu.

Customization Variable Description
rst-default-indent Defines indentation for over-and-under adornment when toggled from simple` adornment.
rst-indent-comment Defines indentation for comment blocks.
rst-indent-field Defines indentation for field content. When set to 0 it always indents to content after field label.
rst-indent-literal-minimized Defines indentation following a literal directive when the directive contains text.
rst-indent-literal-normal Defines indentation following a literal directive when the directive contains no text.
rst-indent-width Defines the default indentation to use.
rst-preferred-adornments Determines the levels for section title adornment.

Additionally, there is the rst-faces customization group, which you can use in font-locking.

< Prev Next >