IntroductionToStructuredText

See StructuredText for more documentation.

The ultimate aim is to support crafting of text that is readable and attractive in both the formatted and the raw form.

With StructuredText pages, you indicate everything, including the structure of a document - its sections and the nesting of subsections, its formatting, links, and stuff like that - using plain-text formatting conventions. (Structured text can include raw HTML, in case there's some elaborate HTML formatting you must do beyond what StructuredText text offers. The less HTML you use, the easier the job will be for editors - yourself included!)

The source of existing pages can provide good examples of the conventions - the text of this page, in particular, presents many central examples. If you are logged in, click the "Edit" or "View" tab on the page to see.

Style Formatting

• Emphasis: *italic* => italic
• Bold: **bold** => bold
• Underlined: _underlined_ => underlined
• Code: 'code' => code

Headers and paragraphs

Paragraphs

Leave a blank line between paragraphs:

        This is some text in
        paragraph one.

        This is different
        text in paragraph two.

Will be rendered as:

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.  Note that you don't have to
        indent the whole paragraph (as is done here for clarity),
        just the first line of the parapgraph.

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

         Subheading 1

          Use additional indentation to generate subheaders.
        Notice that the subheading's level of indenting is
        the same as the level for the previous paragraph,
        but that *this* paragraph is further indented.
        It's the extra indenting of *this* paragraph that
        creates the subheading.

          Subheading 2

           Get smaller subheadings by indenting even more.

           Subheading 3

            Get even smaller subheadings by indenting even more.

To get this:

Preformatted Text

Block of preformatted text

Enter this:

        The next block of text will be formatted exactly the way I
        have typed it::

            This is all preformatted.

              Your formatting will be used until...
                 ... you stop indenting text.
              None of the *structured text* **commands** _work_ here.

            This is still indented.

        This is no longer preformatted.

To get this:

    This is all preformatted.

      Your formatting will be used until...
         ... you stop indenting text.
      None of the *structured text* **commands** _work_ here.

    This is still indented.

Note: You can also use the HTML <pre> and </pre> tags to achieve the same effect. Similarly paragraphs which end in either the word, example or examples will cause the next section to be treated as an unformatted block.

Inlined preformatted text

Enter this:

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

to get this:

Lists

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:

You can use any either * or - or o for the marker for your bulleted list items.

Numbered lists

Enter this:

        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:

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:

Links

Making Links

• Links

  Enter this:

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

  to get this:

  A link to CNN

  Another form:

          "mail me", mailto:address@example.org
  

  to get this:

  mail me

• URLs

  Anything that's obviously a URL will be made into a link. For example:

          http://www.zope.org/
  

  will produce:

  http://www.zope.org/

• Email addresses

  Enter this:

          mailto:address@example.com
  

  to get this:

  address@example.com

• WikiWord (Wiki specific)

  Wiki links are made of two or more run-together capitalized words naming the target page. (In ZWiki, numbers can be use where capital letters would be, except at the beginning of the word, and ~ (tildes) can be used as lowercase letters.) When the target page is there, the wiki ref is rendered as a link to it. Easy!

  Wiki refs also serve to create new pages - when the target page is absent, then the WikiWord itself is not a link, but it has an appended question mark, which is a link to a page for creating authoring and creating the target.

  Some examples:

          StructuredText, WikiWikiWeb, StructuredTextRules
  

  to get this:

  StructuredText, WikiWikiWeb, StructuredTextRules?

• Square brackets (Wiki specific)

  Use square brackets to turn pretty much anything into a wiki link - but beware, spaces and other forced characters make for unobvious links. Use sparingly - its wise to avoid this technique where possible.

  Example:

          [a linked page]
  

  to get this:

  [a linked page]?

• RemoteWikiURL (Wiki specific)

  Enter this:

          ZWiki:RemoteWikiURL
  

  to get this:

  ZWiki:RemoteWikiURL

  RemoteWikiURLs? require another page in the local wiki describing the remote wiki server. The page must contain the RemoteWikiURL keyword followed by the URL on the same line.

• 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.  Note that its two periods at the
          start of a line, '..', followed by a space and then link
          in square brackets.
  

  to get this:

Preventing Links

• Put the expression in ' (single-quote) code-fragment form: ZWiki
• Put the expression in an "::" example block:

          StructuredText, http://www.zope.org, <strong>nope!<strong>
  

• Prefix the WikiWord or '[]' square brackets with an exclamation point: StructuredText, [meta comment]

Images

Enter this:

        "Text shown when the browser does not load the
        image":img:logo.jpg

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 that ZWiki differs from StructuredText documents here as ZWiki will render the text and not the image, and a StructuredText document will render the image. If you really need a graphic in a ZWiki page, use an HTML img link.

Tables

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:

Be careful about numbers in cells being interpreted as list items! Each cell will be treated as if it started a new line.