Documents and comments on this site can be created using structured text (or STX), a simple mark up language that will be rendered as HTML. Structured text is also used in Plone wikis. If this primer is overwhelming, start with the basic intro instead.

• Basic text formatting
• Headers and paragraphs
• Images
• Lists
• Links
• Blocking STX Formatting
• Misc: Making dashes, Creating clean text blocks, On-page TOC, Relative URLs in Plone

Basic text formatting

back to the top

• Italicized text

Enter this :

  *italics*

to get this:

italics

• Underlined text

Enter this :

  _underline_

to get this:

underline

• Boldfaced text

Enter this :

  **boldface**

to get this:

boldface

Headers and paragraphs

back to the top

• Text headers

Enter this:

  My header

    If you enter a single line paragraph (e.g. like
  the one above and then indent the first line of
  the next paragraph, the text in the one-line 
  paragraph will be transformed into a header.

    Note that the second paragraph in the section
  also has its first line indented.

    Be sure to leave a blank line between paragraphs.
  This paragraph's first line is indented, too.

To get this:

My header

If you enter a single line paragraph (e.g. like the one above and then indent the first line of the next paragraph, the text in the one-line paragraph will be transformed into a header.

Note that the second paragraph in the section also has its first line indented.

Be sure to leave a blank line between paragraphs. This paragraph's first line is indented, too.

• Inlined preformatted text

Enter this:

  Some ordinary text here.  Some 'preformatted
  text here'.
  More ordinary text.

to get this:

Some ordinary text here. Some preformatted text here. More ordinary text.

Lists

back to the top

• Bulleted lists

Enter this:

  - First item

  - Second item.  Note that there is a blank line 
  between each list item.

  - Make lists within lists by using extra
  indentation 

  - Second indented item.

  - Third item in the main list.

to get this:

• First item
• Second item. Note that there is a blank line between each list item.
• Make lists within lists by using extra indentation
• Second indented item.
• Third item in the main list.
• Numbered lists

Enter this:

  1 First item

  2 Second item.  Again, note that there is a
blank line between each list item.

  3 Third item in the main list.

Or even this (to prevent having to renumber your points):

  1 First item

  1 Second item.  Again, note that there is a
blank line between each list item.

  1 Third item in the main list.

to get this:

1. First item
2. Second item. Again, note that there is a blank line between each list item.
3. Third item in the main list.

Note that numbered lists cannot be embedded in bulleted lists.

• Definition lists

Enter this:

  First item -- More information about the first item.

  Second item -- More information about the second item.

  Third item -- More information about the third item.

to get this:

First item

More information about the first item.

Second item

More information about the second item.

Third item

More information about the third item.

See also Blocking STX Formatting, below.

Links

back to the top

• Links

Enter this:

  "A link to CNN":http://www.cnn.com

to get this:

A link to CNN

• Email addresses

Enter this:

  "address@example.com":mailto:address@example.com

to get this:

address@example.com

• References

Enter this:

  I am going to refer to a footnote here [1].

  Later in the text I will have a footnotes
  section.

  .. [1] My footnote.

to get this:

I am going to refer to a footnote here [1].

Later in the text I will have a footnotes section.

[1] My footnote.

Note that the footnote must be placed all the way flush left.

See also Blocking STX Formatting and Misc, below.

Images

back to the top

• Images

Enter this:

  "default user alt text":img:defaultUser.gif

to get this:

Centering images is not trivial. You need to wrap the img tag in a <p> tag with the following style: style="text-align:center;display:block;"

Enter this:

  <p style="text-align:center;display:block;">
     "alt text":img:defaultUser.gif
  </p>

To get this

You can use an arbitrary URL for the image, e.g.:

  "plone logo":img:http://www.plone.org/logo.jpg

to get this:

Note image names should be one word, with no spaces, and that using "_" or "-" in the name will break the mark up.

For example, using "image_name" will not work because the "_" is reserved for underlining.

Tables

• Tables (not recommended - just use standard html tables instead)

Enter this:

        |------------------------------------|
        | Fruit     | Nut        | Mammal    |
        |====================================|
        | Apple     | Peanut     | Squirrel  |
        |------------------------------------|
        | Orange    | Macadamia  | Woodchuck |
        |------------------------------------|
        | Banana    | Walnut     | Dolphin   |
        |------------------------------------|
        | This spans 2 columns!  | Cat       |
        |------------------------------------|
        | Pear      | This spans 2 columns!  |
        |------------------------------------|
        | This spans 3 columns!              |
        |------------------------------------|

to get this:

Note that, in Plone Documents and News Items, tables made with the above STX mark up will look nicer than they do here on a wiki page, thanks to the magic of Custom Style Sheets (CSS).

Blocking STX Formatting

back to the top

To prevent text being processed as structured text:

• Use single quotes (not always effective, especially for long passages)
• In a wiki, to prevent a word with mixed upper and lowercase being rendered as a WikiName, place an exclamation point directly in front of it
• For code snippets:

    Lead into a freestanding block of text with a double
  colon *and*, after a line space, 
  start the code block with a space or indent::
  
    This is *italics* in STX.
  

Here in Plone, this puts the code inside a blue box, and changes the font face. The above passage looks like this:

Lead into a freestanding block of text with a double colon and, after a line space, start the code block with a space or indent:

  This is *italics* in STX.

Each new line of code must be preceeded by a white space. Close the code block by starting a new paragraph flush left.

Misc

back to the top

• Double hyphens (dashes)

Because a double hyphen, with a space on either side, is used to make definition lists, be careful when making a dash! If you want to use the double hypen for a dash, you must place it--like this--directly next to the surrounding words, without any spaces. But, that makes for awkward line breaks in HTML pages.

Because of this, many people use a single hyphen, which is OK. Or, use — — the HTML code for an m-dash (preferred).

• Creating clean text blocks

When working in STX, you can let the text autowrap. But STX is very fussy about indenting, since much of the formatting is based on indenting. It's not called structured text for nothing! =}

Creating clean text blocks with hard returns, and indenting on the right and left, helps clarify the hierarchical structure of the page. It makes it easier to see where you are within the page hierarchy when writing and editing.

Use an external text editor designed for writing code, such as BBEdit (Mac), to assist. They support hierarchical indenting, prefixing/suffixing lines with text or white space, and hard wrapping to specified widths. (A character width of about 55 works well.) Then copy/paste back into the STX editing window.

• On-page TOC

A TOC is a "table of contents" or, informally on a web page,a linked list of section headings.

The footnotes mark up can be used for making on-page TOC, as long as you don't mind your section headings being inside brackets. Because the linked-to reference (anchor name or id) must be placed flush left, this can only be used for linking to top level section headings.

• Relative URLs in Plone

To link to a page within the plonerangers site, you can use relative URLs only in the following way:

• For links to items inside the same folder (same level or below in the site hierarchy): start with item name, or the path down from current folder:

    "View the Structured Text used to create this
  page":
  

• For name anchors (links within the same page), you must include the current page name in link to the name anchor.
• Otherwise, you must use the full path name starting from the site root: /plonerangers/ down to the item.

Adapted from plone.org, UsingStructuredText (revised on September 20, 2005).
http://plone.org/documentation/howto/UsingStructuredText