Markup Guide for blog.stuffbytammy.ca

Blog Post Formatting

Blog posts should be a regular text file placed in one of the category folders below content. Post files must be uniquely named within the category and should generally be named after the title of the post, e.g., this_is_my_post.txt although longer titles may be specified in the post file.

Posts files should be formatted like the example below. Explanations are located after <-- and are not meant to be part of the file.

First line is always title of the blog post but perhaps longer        <-- File should be named title_of_my_blog_post.txt
meta-author: Tammy                                                    <-- Can be your name or the name of a guest author
meta-markup: textile2                                                 <-- Include this line only if you need enhanced markup below

First line of the blog post goes here. Paragraphs will be automatically wrapped so do not hit enter unless you want a line to break somewhere specific.

Paragraphs are also separated by blank lines so this line is a new paragraph.

Markup Table of Contents

Blocks

Text::Textile processes text in units of blocks and lines. A block might also be considered a paragraph, since blocks are separated from one another by a blank line. Blocks can begin with a signature that helps identify the rest of the block content. Block signatures include:

p

A paragraph block. This is the default signature if no signature is explicitly given. Paragraphs are formatted with all the inline rules (see inline formatting) and each line receives the appropriate markup rules for the flavor of HTML in use. For example, newlines for XHTML content receive a <br /> tag at the end of the line (with the exception of the last line in the paragraph). Paragraph blocks are enclosed in a <p> tag.

pre

A pre-formatted block of text. Textile will not add any HTML tags for individual lines. Whitespace is also preserved.

Note that within a "pre" block, < and > are translated into HTML entities automatically.

bc

A "bc" signature is short for "block code", which implies a preformatted section like the "pre" block, but it also gets a <code> tag (or for XHTML 2, a <blockcode> tag is used instead).

Note that within a "bc" block, < and > are translated into HTML entities automatically.

table

For composing HTML tables. See the "TABLES" section for more information.

bq

A "bq" signature is short for "block quote". Paragraph text formatting is applied to these blocks and they are enclosed in a <blockquote> tag as well as <p> tags within.

h1, h2, h3, h4, h5, h6

Headline signatures that produce <h1>, etc. tags. You can adjust the relative output of these using the head_offset attribute.

clear

A "clear" signature is simply used to indicate that the next block should emit a CSS style attribute that clears any floating elements. The default behavior is to clear "both", but you can use the left (<) or right (>) alignment characters to indicate which side to clear.

dl

A "dl" signature is short for "definition list". See the "LISTS" section for more information.

fn

A "fn" signature is short for "footnote". You add a number following the "fn" keyword to number the footnote. Footnotes are output as paragraph tags but are given a special CSS class name which can be used to style them as you see fit.

Extended Blocks

Normally, a block ends with the first blank line encountered. However, there are situations where you may want a block to continue for multiple paragraphs of text. To cause a given block signature to stay active, use two periods in your signature instead of one. This will tell Textile to keep processing using that signature until it hits the next signature is found.

For example:

bq.. This is paragraph one of a block quote.
This is paragraph two of a block quote.
p. Now we're back to a regular paragraph.

You can apply this technique to any signature (although for some it doesn't make sense, like "h1" for example). This is especially useful for "bc" blocks where your code may have many blank lines scattered through it.

Escaping

Sometimes you want Textile to just get out of the way and let you put some regular HTML markup in your document. You can disable Textile formatting for a given block using the "==" escape mechanism:

p. Regular paragraph

==
Escaped portion -- will not be formatted
by Textile at all
==

p. Back to normal.

You can also use this technique within a Textile block, temporarily disabling the inline formatting functions:

p. This is ==*a test*== of escaping.

Inline Formatting

Formatting within a block of text is covered by the "inline" formatting rules. These operators must be placed up against text/punctuation to be recognized. These include:

*strong*

Translates into <strong>strong</strong>.

_emphasis_

Translates into <em>emphasis</em>.

**bold**

Translates into <b>bold</b>.

__italics__

Translates into <i>italics</i>.

++bigger++

Translates into <big>bigger</big>.

--smaller--

Translates into: <small>smaller</small>.

-deleted text-

Translates into <del>deleted text</del>.

+inserted text+

Translates into <ins>inserted text</ins>.

^superscript^

Translates into <sup>superscript</sup>.

~subscript~

Translates into <sub>subscript</sub>.

%span%

Translates into <span>span</span>.

@code@

Translates into <code>code</code>. Note that within a "@...@" section, < and > are translated into HTML entities automatically.

Links

Textile defines a shorthand for formatting hyperlinks. The format looks like this:

"Text to display":http://example.com

In addition to this, you can add "title" text to your link:

"Text to display (Title text)":http://example.com

The URL portion of the link supports relative paths as well as other protocols like ftp, mailto, news, telnet, etc.

"E-mail me please":mailto:someone@example.com

You can also use single quotes instead of double-quotes if you prefer. As with the inline formatting rules, a hyperlink must be surrounded by whitespace to be recognized (an exception to this is common punctuation which can reside at the end of the URL). If you have to place a URL next to some other text, use the bracket or brace trick to do that:

You["gotta":http://example.com]seethis!

Textile supports an alternate way to compose links. You can optionally create a lookup list of links and refer to them separately. To do this, place one or more links in a block of it's own (it can be anywhere within your document):

[excom]http://example.com
[exorg]http://example.org

For a list like this, the text in the square brackets is used to uniquely identify the link given. To refer to that link, you would specify it like this:

"Text to display":excom

Once you've defined your link lookup table, you can use the identifiers any number of times.

Lists

Textile also supports ordered and unordered lists. You simply place an asterisk or pound sign, followed with a space at the start of your lines.

Simple lists:

* one
* two
* three

Multi-level lists:

* one
** one A
** one B
*** one B1
* two
** two A
** two B
* three

Ordered lists:

# one
# two
# three

Definition lists:

dl. textile:a cloth, especially one manufactured by weaving or knitting; a fabric
format:the arrangement of data for storage or display.

Note that there is no space between the term and definition. The term must be at the start of the line (or following the "dl" signature as shown above).

Tables

Textile supports tables. Tables must be in their own block and must have pipe characters delimiting the columns. An optional block signature of "table" may be used, usually for applying style, class, id or other options to the table element itself.

From the simple:

|a|b|c|
|1|2|3|

Images

Images are identified by the following pattern:

!/path/to/image!

Image attributes may also be specified:

!/path/to/image 10x20!

Which will render an image 10 pixels wide and 20 pixels high. Another way to indicate width and height:

!/path/to/image 10w 20h!

You may also redimension the image using a percentage.

!/path/to/image 20%x40%!

Which will render the image at 20% of it's regular width and 40% of it's regular height.

Or specify one percentage to resize proprotionately:

!/path/to/image 20%!

Alt text can be given as well:

!/path/to/image (Alt text)!

The path of the image may refer to a locally hosted image or can be a full URL.

You can also use the following modifiers after the opening "!" character:

<

Align the image to the left (causes the image to float if CSS options are enabled).

>

Align the image to the right (causes the image to float if CSS options are enabled).

- (dash)

Aligns the image to the middle.

^

Aligns the image to the top.

~ (tilde)

Aligns the image to the bottom.

{style rule}

Applies a CSS style rule to the image.

(class) or (#id) or (class#id)

Applies a CSS class and/or id to the image.

( (one or more)

Pads 1em on the left for each "(" character.

) (one or more)

Pads 1em on the right for each ")" character.