Martin Kenny .com

Overview

Structured text is a mechanism to convert plain text that's written to follow a few simple rules, into other representations, notably HTML and XHTML.

At a bare minimum, text that's individual lines, or groups of lines, separated by blank lines will be converted to individual paragraphs.

Any nesting structure, like nested lists and multiple levels of heading are achieved through indenting of lines in the plain text source.

The Rules

Paragraphs

One or more lines of text, with no intervening blank lines are treated as one paragraph. One-or-more blank lines separates paragraphs. So the following text:

This is one
paragraph. Which has a second sentence in it.

And this is another paragraph.

Would render as:

Unordered and Ordered Lists

An unordered list item is just like a paragraph, but introduced by a hypen "-", while an ordered list item is introduced by a hash sign "#". So the following text:

- List item 1

- List item 2

- List item 3

would render as:

and

# List item 1

# List item 2

# List item 3

would render as:

Nested lists are produced by nested indenting, so

- List item 1

  - List item 1.1

  - List item 1.2

- List item 2

- List item 3

would render as:

Block Quotes

Block quotes, are produced by enclosing the quoted paragraphs inside special directives, so:

Fred blogs said:

:quote
This is a quote.

And some more text in another paragraph of the quote.
:endquote

would render as:

Links

Links are produced by enclosing the link text and the URL in square brackets, so the following text:

Some links are simply bare URLs, for example [http://w3.org/],
while others need some link text,
e.g. [World Wide Web Consortium|http://w3.org/].

would render as:

Inline formatting

Structured text allows you to specify several different types of inline formatting; strong, emphasis, citations and code; by surrounding individual words or phrases with punctuation marks, so:

This is **very** important, and this is *emphasized*.
This is =computer code= (fixed pitch font), and this
is the "Name of Something".

would render as:

Images

You can include references to images that are either inline with the text, or floated to the left or right of the main body of text. The next example floats a picture to the right of the first paragraph of text:

imgright:"/images/sample.jpg":"Photo of a Gazania flower" The Gazania
to the right can be found in my garden.

Gazanias prefer full sun, are very hardy, and can tolerate salty conditions,
although this one is at least five miles from the sea.

and would render as:

The Fine Print

Although Structured Text tries to do the "Right Thing", sometimes it may make the wrong guesses about what you intended it to do. Feel free to ask the author how to achieve a particular effect.

Escaping Special Characters

Structured text uses the "*", "=", "[", "]" and "\" for special purposes; when it's necessary to include one of these characters in your text, you must escape the character, by prefixing it with a backslash "\".

So to write 4 * 5 = 20, you would use the following text:

4 \* 5 \= 20