contents

The contents directive is one of the easiest directives to use. By clicking on the plain text link for this page, you can see it's been used in the line just above this one. Here's how to make it work:

.. contents:: (optional label for TOC list)
       NOTE: if you do not provide a label, the label will simply read "contents"

As you build the page, each item that you underline (using the - key not the _) is automatically included in the table of contents.

sidebar

A side bar is very useful to pull out information from the body of the text and into its own right-hand justified box. An example of a sidebar is shown above with the "Each directive has three parts" box. Here's how to make it work:

.. sidebar:: Title for sidebar box (required)

   Text that will appear in the side bar box. **Note this text
   is indented.** To signify the end of the sidebar box content,
   simply don't indent the next paragraph of content.

This content will not appear in the sidebar box above.

line-block

The line block directive is very handy when the spacing of a list counts (like with addresses or with poetry). Here's how to make it work:

.. line-block::

   Here's my address
   123 Main St
   Los Alamos, NM 87544

Note that the text that you are line blocking must be indented. The above directive looks like this when it's published:

Here's my address
123 Main St
Los Alamos, NM 87544

Contrast the above with how one would normally have to do a series of lines on top of each other:

Here's my address

123 Main St

Los Alamos, NM 87544

Quite the handy directive, no?

image

When it comes right down to it, inserting an image in a page is just using the image directive.:

.. image :: (URL for your picture)

See Picture Display How-to for info on more advanced use.

on-include

This directive copies the contents of a worksheet to the document you are working in. This is particularly useful if you the same text to be referred to in several places. This is how it is done.:

.. on-include :: worksheet name

Please notice that you use the worksheet name (with any spaces it might have) NOT the URL. This form only works if the worksheet is in the group that you are posting in. If it is in another groups's workspace, you must include the other group in the address.

Please look at o-map.:

.. on-include ::  /community-general/o-map

This code will look like this:

admonition

This directive allows you to put a box with information in the middle of a post. It is particularly useful to emphasize a point. If you are wandering around the help pages you will see this one a lot.:

.. admonition :: Did you know?

   To return to the page you were just viewing, just click the "back" button on your Web browser.

And this is what it yields:

Again, the text that will appear in the box is indented.

RAW

This directive will allow you to enter straight HTML code so that the Colophone doesn't parse it into it's own language. I find this particularly good for doing tables as I am very comfortable doing tables in HTML.:

.. RAW :: HTML

  <TABLE>
  <TR><TD>Col 1</TD><TD>Col 2</TD></TR>
  <TR><TD>Name 1</TD><TD>Phone 1</TD></TR>
  </TABLE>

Note, yet again, that the HTML code must be indented after EVERY enter, even for a blank line. This little snippet yields:

Techies Take Note:

We have used reStructuredText (RST) as our markup language. If you're inclined to understand technical documentation, the full listing of RST directives can be found here at reStructuredText