blox plugin Markup Guide

Welcome

To properly display this page, you must be using the blox plugin, version 0.99 or higher, with the configurable variables $markup_active and $break_singles set to 1. If all is set well, the next sentence will be split across two lines and will show some styling.
This should be a separate line, and
these six words should be bold.

blox markup notation is mainly inspired by Brian Ingerson's Kwiki module (the "official" blosxom wiki). There is no grand philosophy behind the markup; it's simply meant to save you typing time while being easy to remember and not interfering with existing html tags.

Skip To Contents

About the Markup

Markup for most "inline" tags (styling, links, images) can begin before any word; markup that results in html "block" tags (heads, blockquotes, lists, rules), along with anchors and reference links, must begin at the start of a line. Any markup can be ignored ("escaped") by preceding with an exclamation mark (!). The notation consists of:

About the Guide

Each description begins with a definition of the markup, perhaps a note or two, and then samples and examples of successful and failed usage. Examples of 'what to type' are presented in comments as code. (Excepting a couple of hand-coded tables and <PRE> blocks, this whole guide is produced by blox markup, making the entry file itself an excellent reference ;-)

To view this page without any style sheet, click here; to view the raw entry file, click here.

CONTENTS

Inline

Bold (<b> tag)

Enclose single-line words with "*". Escape by preceding with "!".
Type it like this: make *bold* text

  1. This is a test of bold. <-- one word...
  2. This is a 6-word test of bold. <-- ...or several: *a 6-word test of bold*
  3. This is a t*est of bo*ld. <-- fails; words not enclosed: a t*est of bo*ld
  4. This is a* test of* bold. <-- fails; words not enclosed: a* test of* bold
  5. "bold within plain double quotes" <-- "*bold within plain double quotes*"

Escaping bold
This is a *test* of UNbolding. <-- escaping; type it like this: !*test*

contents

Italic (<i> tag)

Enclose single-line words with "/". Escape by preceding with "!".
Type it like this: make /italic/ text

  1. This is a test of italic.
  2. This is a test of italic. <-- This /is a test of/ italic.
  3. This /is a test o/f italic. <-- fails; words not enclosed: /is a test o/f
  4. 'Italic within single quotes' <-- '/Italic within single quotes/'

Escaping italic
This is a /test/ of UNitalicizing. <-- escaping; type it like this: !/test/

contents

Bold-Italic ...

  1. This is a test of bold-italic. <-- */test/*
  2. This is a test of bold-italic. <-- */This is a test/*
  3. This is a test of bold-italic. <-- *This /is a test/*
  4. This is a test of bold-italic. <-- this works: *This /is a test*/
  5. This is a test of bold-italic. <-- this works, too: *This /is a test* of/
  6. Th*is i/s a test/* of bold-italic. <-- fails; words not enclosed: Th*is i/s a test/*
  7. This i*s a test* of bold-italic. <-- fails poorly; words not enclosed: i*/s a test/*

Escaping bold-italic
*Ignore /bold-italic*/ <-- escaping; type it like this: !*Ignore !/bold-italic*!/
(The final "!" is just to be safe against further "/" in the line ;-)

contents

...and Italic-Bold

  1. This is a test of italic-bold. <-- /*test*/
  2. This is a test of italic-bold. <-- /*This is a test*/
  3. This is a test of italic-bold. <-- /This *is a test of*/
  4. This is a test of italic-bold. <-- this works: /This *is a test of/*
  5. This is a test of italic-bold. <-- this works, too: /This *is a test/ of*
  6. Th/is i*s a test*/ of italic-bold. <-- fails; words not enclosed: Th/is i*s a test*/
  7. This i/s a test/ of italic-bold. <-- fails poorly; words not enclosed: i/*s a test*/

Escaping italic-bold
/Ignore *italic-bold/* <-- escaping; type it like this: !/Ignore !*italic-bold/!*
(The final "!" is just to be safe against further "*" in the line ;-)

contents

Underline (<u> tag)

Enclose single-line words with "_". Escape by preceding with "!".
Type it like this: make _underlined_ text

  1. This is a test of underline. <-- _a test of_
  2. This is a test of _under_line. <-- fails; words not enclosed: _under_line
  3. This test underlines an under_score word.. <-- _underlines an under_score word_
  4. This is a bold slant on underline. <-- *_bold /slant/ on underline_*

Escaping underline
This is a _test_ of UN_under_lining. <-- escaping; type it like this: !_test_
*/_Ignore/ compound* styles_ <-- type it like this: !*!/!_Ignore/ compound* styles_

contents

Code (<code> tag)

Enclose any text with "[=" and "]"; multi-line works, so make sure you close it! Escape by preceding with "!". (There's just about no way coding can fail, so be careful ;-)
Type it like this: make [=coded] text

  1. This is a test of coding. <-- [=test of coding]
  2. This is a test of coding. <-- [=This is a test of coding]
  3. This is a test of coding. <-- a te[=st of coding]
  4. Coding contained by styled text. <-- _contained by [=styled]_
  5. Coding that contains styled text. <-- [=that contains _styled_]
  6. This is a multi-line test of coding:
    This is line 2...

    This is line 4, the final line.     <-- it's not the final line of code until you close it!
  7. (This bit is really arcane; most users can ignore.)
    Because I want maximum compatibility with kwiki markup, code closes with an "ambiguous" character (]) instead of something unique like =]. Because of that, trying to convey escaped code markup or escaped link markup within code markup can be tricky. You'll either have to "code twice," or use entities:
    [=[![img /images/link.gif]][= http://example.org]] <-- "code," twice
    [=![img /images/top.gif&#93; ##top] <-- entities: &#91; for "[" and &#93; for "]".
  8. The last ] in a series of ]s is used to close code:
    Typing [=[huh]]]]] yields [huh]]]], not [huh]]]]]

Escaping code
Th[=is is a t]est [=of UNco]ding. <-- escaping; type it like this: Th![=is is a t]est ![=of UNco]ding.

contents

Images (<img> tag)

Enclose single-line image information with "[" and "]". Escape by preceding with "!". Image information format is: required relative URL, (space) optional width and height as w,h, (space) optional attribute text. Type it like this: [img /images/top.gif], which codes as:

<img src="/images/top.gif">

  1. [img /images/top.gif 22,13] <-- codes as:
    <img src="/images/top.gif" width="22" height="13">
  2. [img /images/top.gif alt="Top"] Top <-- codes as:
    <img src="/images/top.gif" alt="Top">
  3. [img /images/top.gif 22,13 alt="Top" title="TOP"] Top <-- codes as:
    <img src="/images/top.gif" width="22" height="13" alt="Top" title="TOP">
  4. The next line succeeds poorly, by treating the improper w,h as attribute text
    <-- [img /images/top.gif 44 , 26] codes as:
    <img src="/images/top.gif" 44 , 26>
  5. The next line fails; words not enclosed
    inter[img /images/top.gif]ruption

Escaping images
No picture [img /images/top.gif] here. <-- escaping; type it like this: ![img /images/top.gif]

contents

Links

Links (<a> tag)

Enclose single-line link information with [ and ]; link information format is: optional link name (space), required URL, (space) optional attribute text. Escape by preceding with "!".
Type it like this: [link name http://example.com title="test"]

Names (link text) can be one or more words, and should not include "http://", "ftp://", "irc://", nor ":/", nor "//", nor "[" and "]". Image markup can be used in place of a name. Names are optional; with no name, the URL becomes the link text.

URLs can be absolute, relative-to-root, or relative-to-blog. URLs are required.

Attributes should be typed exactly as they would be in an html tag. Attributes are optional.
[Open in New Window //about.html target="_blank"] codes as: 

<a href="/about.html" target="_blank">Open in New Window</a>
and displays as:
Open in New Window

Escaping links
No link [http://example.net] here. <-- escaping; type it like this: ![http://example.net]

contents

Absolute Links (<a> tag)

Absolute URLs must begin with either http://, ftp://, or irc://. Names and attributes are optional; with no name, the URL becomes the link text. Escape by preceding with "!".
Type it like this: [http://example.com]

  1. Absolute "raw" (unnamed) link: http://example.com. <-- [http://example.com]
  2. Absolute "named" link: Example.com. <-- [Example.com http://www.example.com]
  3. [ http://example.com]. <-- fails; space after [: [ http://example.com]
  4. Style within a link http://www.example.com. <-- fails; cute, but goes nowhere: [http://www.*example*.com]
  5. Styled absolute links
    • Bold raw link http://www.example.com. <-- "*" enclosing link markup:
      *[http://www.example.com]*
    • Italic raw link http://www.example.com. <-- "/" enclosing link markup:
      /[http://www.example.com]/
    • Bold named link Click Here. <-- "*" enclosing link markup:
      *[Click Here http://www.example.com]*
    • Underlined named link Click Me. <-- "_" enclosing link name:
      [_Click Me_ http://www.example.com]
  6. http://example.com/a <-- succeeds poorly when there's a space in URL; [http://example.com/a space/index.html]
contents

Relative Links (<a> tag)

Relative-to-web-root URLs must begin with //. Names and attributes are optional; with no name, the URL becomes the link text. Escape by preceding with "!".
Type it like this: [//about.html]

  1. Relative "raw" (unnamed) link: /download.html. <-- [//download.html]
  2. Relative "named" link: Downloads. <-- [Downloads //download.html]
  3. [ //about.html]. <-- fails; space after [: [ //about.html]
  4. Styled relative links
    • Bold relative raw link /download.html. <-- "*" enclosing link markup:
      *[//download.html]*
    • Italic relative raw link /download.html. <-- "/" enclosing link markup:
      /[//download.html]/
    • Bold relative named link Downloads. <-- "*" enclosing link markup:
      *[Downloads //download.html]*
    • Underlined relative named link Linky. <-- "_" enclosing link name:
      [_Linky_ //download.html]
  5. [Bad [Name] //about.html] <-- fails with [] in name; [Bad [Name] //about.html]
contents

Blog Links (<a> tag)

Relative-to-blog-root URLs must begin with :/. Names and attributes are optional; with no name, the URL becomes the link text. Escape by preceding with "!".
Type it like this: [:/]

  1. Blog "raw" (unnamed) link: /docs/tech/notes. <-- [:/docs/tech/notes]
  2. Blog "named" link: My Blog. <-- [My Blog :/]
  3. [ :/nowhere]. <-- fails; space after [: [ :/nowhere]
  4. Styled blog links
    • Bold blog raw link /index.html. <-- "*" enclosing link markup: *[:/index.html]*
    • Italic blog raw link /docs/plato. <-- "/" enclosing link markup: /[:/docs/plato]/
    • Bold blog named link Texas people. <-- "*" enclosing link markup: *[Texas people :/docs/people/texas]*
    • Underlined blog named link blox. <-- "_" enclosing link name:
      [_blox_ :/dltext/blox.dl]
  5. Named relative blog link with attributes: blox guide <-- type it like this: [*blox* markup guide :/dltext/blox.dl class="yellow" title="blox guide" target="_blank"]
  6. /docs/tech/notes <-- succeeds with extra leading "/"; [://docs/tech/notes] (this may change if it causes problems with other markup)
contents

Anchors (<a name="anchor"></a>)

Alone on a line, enclose one "#" and a single-word anchor name with "[" and "]". Escape by preceding with "!". Type it like this: [#anchor_name], which codes as:

<a class="bloxanchor" name="anchor_name"></a>
(The bloxanchor class is added to all anchors so that you can control appearance and behavior via CSS.)

  1. The next line does not set an anchor:
    [#not_an_anchor] <-- fails because anchor markup is not alone on a line
  2. The next line does not set an anchor; fails with more than one word:
    [#too many words]
  3. The next line does not set an anchor; only alphanumerics allowed:
    [#no_styles_allowed]

Escaping anchors
![#escaped_anchor] <-- preceed with !

contents

Anchor Links (<a href="#anchor">go to anchor</a>)

Enclose single-line link name, a space, two "#", and a same-page anchor name with "[" and "]". Attributes are optional. Escape by preceding with "!".
Type it like this: [link text ##anchor_name]

  1. Here's an anchor link: Go to Anchors <-- [Go to Anchors ##anchors]
  2. Styled anchor link: Go to Anchors <-- [Go to *Anchors* ##anchors]
  3. Anchor link with attributes: [[Anchors] ##anchors title="Go to Anchors"] <-- [Anchors ##anchors title="Go to Anchors"]

Escaping anchor links
![No Link ##nowhere] <-- preceed with !

contents

Image Links

In place of a link name, use image markup in absolute, relative, blog, and anchor links. Escape by preceding image only, or both link and image, with "!".

  1. absolute link: <-- [[img /images/link.gif] http://example.org]
  2. relative link: <-- [[img /images/link.gif] //about.html]
  3. blog link: <-- [[img /images/link.gif] :/index.html]
  4. anchor link: <-- [[img /images/top.gif] ##top]

Escaping image links

contents

Reference Links

Create a reference anywhere by enclosing one or more digits or a single letter with [ and ]. Then, alone on a line, enclose the same digit(s) or letter, a space, an absolute URL, and optionally a space and attribute text within "[" and "]". Attributes are optional. Escape by preceding with "!".

With a reference[1] in the story,
type this: [1 http://example.org] alone on a line
to produce a reference link.
[1]: http://example.org

  1. Each reference ID can be linked a number of times[1]. For example, using [1 http://www.example.net] below will produce another "1" reference link.
    [1]: http://www.example.net
  2. Protect named links (e.g. [24 http://example.tv) by escaping references with the same "name" (e.g. "![24]"): 24
  3. Attributes in a reference link[2]; using [2 http://example.org target="_blank"] below will open the reference link in a new window.
    [2]: http://example.org
  4. Nothing but "attributes"[B] are also O.K.! Type it like this: [B In other words, you can use reference link markup sans URL ;-)]
    [B]: In other words, you can use reference link markup sans URL ;-)

Escaping reference links

contents

Blocks

Paragraphs & linebreaks

Paragraphs in blox are not optional; the only way to turn them off is to not use the plugin. This section on paragraph "markup" describes how (easily) it interacts with the optional markup system.

To recap blox paragraph formatting: Blocks of text separated by blank lines are wrapped in user-specified "paragraph" tags. If such a block begins or ends with an html tag (i.e. < or >), you must add a single space character before or after the tag to get blox to add its open or close block tag.

This text:
[blank line]
A block of text.
[blank line]
becomes:

TEST:
[blank line]
[]
A block of text.
[blank line]
becomes: 

 
<p>
A block of text.
</p>

But this:
[blank line]
<b>A bold</b> beginning.
[blank line]
only becomes: 

<b>A bold</b> beginning.
</p>

To get the opening paragraph tag, add a space before the leading html tag:
[blank line]
 <b>A bold</b> beginning.
[blank line]
for: 

 
<p>
<b>A bold</b> beginning.
</p>

NOTE that you do not have to worry about adding leading and trailing spaces for html tags that blox produces from your markup; adding spaces is only for tags that you put in your entry files.

The paragraph model is extended to the optional markup that creates other html "blocks" (blockquotes, rules, heads, lists, etc.) — to have a block stand alone, surround it with blank lines; to contain a block, surround it with text.

For instance, this markup:
First line in paragraph
{= A blockquote =}
Third line in paragraph.
yields this html: 

<p>
First line in paragraph
<blockquote>
A blockquote
</blockquote>
Third line in paragraph.
</p>

While this:
First line in paragraph

{= A blockquote =}

First line in paragraph.
codes as this: 

<p>
First line in paragraph
</p>

<blockquote>
A blockquote
</blockquote>

<p>
First line in paragraph.
</p>

And this:
{= A blockquote =}
First line in paragraph.
codes as: 

<p>
<blockquote>
A blockquote
</blockquote>
First line in paragraph.
</p>
contents

Heads (<h1..6> tags)

Alone on a line, put 1 to 6 "=", then a space, then head text. Optionally, put a space and matching number of "=" after head text. Escape by preceding with "!". To make a head "stand alone" (not contained by a paragraph), surround it with blank lines.
== Head Text == <-- type it like this, or
== Head Text <-- type it like this

1. The next head is styled; type it like this: == /_Styled H3_/

Styled H3


2. The next head includes equals signs; type it like this:
(note the trailing space): "===== == Equals Signs in Heads == " (no quotes)
== Equals Signs in Heads ==

3. The next head fails; there is no space between "=" and the head text
==Not an H2

4. The next head fails; too many spaces between "=" and the head text: "==    Not an H2"
== Not an H2

5. The next head fails; "=" must be first character on line:
This is == not an H2

Escaping _heads
=== Ignore Markup <-- escaping; type it like this: !=== Ignore Markup
==== Ignore Markup ==== <-- escaping; type it like this: !==== Ignore Markup ====

contents

Blockquotes (<blockquote> tag)

Start a line with "{=" to open a blockquote; end a line with "=}" to close it. Blockquotes are multi-paragraph, so make sure you close them! All markup can be used inside a blockquote, except for another blockquote. Escape by preceding with "!". If you need to use "=}" within a blockquote, escape it as !=}. To make a blockquote "stand alone" (not contained by a paragraph), surround it with blank lines.
{= Blockquote Text =} <-- type it like this

1. Here comes a blockquote; type it like this:
{= Hey! I'm a blockquote! =}

Hey! I'm a blockquote!

2. The next line fails; {= must begin the line:
This is {= not a blockquote. =}

3. Here's a multi-paragraph blockquote; type it like this:
{=Here's the first paragraph. . .

Here's the second paragraph. . .=}

Here's the first paragraph of a two-paragraph blockquote, lovingly wrapped in paragraph tags by blox.

Here's the second paragraph of a two-paragraph blockquote., lovingly wrapped in paragraph tags by blox.

4. Empty blockquote are possible: ({==})

5. You can do anything inside a blockquote that you can do in a paragraph (except use a blockquote ;-)

Here's a blockquote with
a linebreak, and

a separate paragraph, and

some styling, and a link or two, and

  • list
  • items
and so on....

Escaping Blockquotes
{=Ignore blockquote=} <-- type it like this: !{=Ignore blockquote=}

contents

Lists (<ol> and <ul> tags)

A line starting with one or more "list marks" and a space, followed by text creates a list item; the number of list marks determines the nested level of the list. Consecutive list items are contained in the same list. List items can be mulit-line, provided no line starts with a space. Escape by preceding with "!". To make a list "stand alone" (not contained by a paragraph), surround it with blank lines.

Type it like this:
* list item 1
* list item 2

  1. The first mark in a list sets the type of list:
    * ul item is first
    0 ol item
    0 ol item
    • ul item is first
    • ol item
    • ol item
  2. List items can be multi-line, provided no line starts with a space. A <br> tag is automatically added to multi-lines (regardless of the $break_singles setting); the tag automatically adjusts to the $use_xhtml_tags setting.
    * Item 1 line 1
    item 1 line2
    * Item 2
    • Item 1 line 1
      Item 1 line 2
    • Item 2
  3. Lists can be nested:
    * Outer list 1
    00 Inner list 1
    00 Inner list 2
    *** Inner inner list 1
    * Outer list 2
    • Outer list 1
      1. Inner list 1
      2. Inner list 2
        • Inner inner list 1
    • Outer list 2
  4. Fails because 0 is not first character in line:
    '  0 Failed list'

    0 Failed list
  5. List items can be styled:
    * *bold* item
    * /italics/ item
    * _underlined_ item
    • bold item
    • italics item
    • underlined item
  6. The following list markup is valid:
    1. 1 item 1
    2. 2) item 2
    3. 3: item 3
    4. 4> item 4
      • ++ item 5
      • -- item 6
        • *-* item 7

Escaping Lists
UNlist items by preceeding with a !:
!** Escaped inner item
!3 Escaped OL item
** Escaped inner item
3 Escaped OL item

contents

Rules (<hr> tag)

Alone on a line, put four "-" and nothing else. Escape by preceding with "!". To make a rule "stand alone" (not contained by a paragraph), surround it with blank lines.
Type it like this:
----

1. The next line fails due a leading space " ----":
----

2. The next line fails due a trailing space "---- ":
----

3. Rules can be contained in other blocks. This entry text:
[blank line]
First line...
----
...Last line.
[blank line]

produces this HTML: 

<P>
First line...
<HR>
...last line.
</P>

Escaping rules
The next line is an escape; type it like this: !----
----

contents

More Info

<PRE> blocks

blox doesn't do anything to text that's wrapped in <PRE> tags...and that's exactly the point. Whatever you put in a <PRE> block will be left completely as-is.

This text:
<PRE>
*No bold* inside a PRE

[no links either http://www.exxample.com]
</PRE>

Becomes this HTML: 

<PRE>
*No bold* inside a PRE

[no links either http://www.exxample.com]
</PRE>
contents

XHTML 1.0 & strict HTML 4.01

Set the $use_xhtml_tags config var to 1 for the following:

blox markup conforms to "loose" HTML 4.01; specifically, list items are not normally closed, and anchors contain no text. Two config vars are available to increase conformance:

contents

Undocumented

aligned DIVs
I just threw these in for the right-aligned contents links in this guide ;-) They could disappear at any moment. Use <br> tags for multi-line. >>>>[contents ##contents] codes as: 

<div align="right"><a href="#contents">contents</a></div>

1. For a right-aligned single-line DIV, type this:
>>>>_Far Right text_

Far Right text

2. For a center-aligned single-line DIV; type this:
>><<_Centered text_

Centered text

3. For a left-aligned single-line DIV; type this:
<<<<_Far Left text_

Far Left text

Escaping aligned DIVs
>>>>     <-- escaping; type it like this: !>>>>

<big> and <small>
This markup seems really clunky; these will p'bly die of embarrassment. Use <br> tags for multi-line.

  1. One key makes you taller <-- One key +++makes you taller+++
  2. And one key makes you small <-- And one key ---makes you small---
  3. Preceding with "!" makes +++nothing+++ at ---all--- <-- !+++nothing+++ at !---all---
contents

Not "Bugs" — anomalies ;-)

This markup always does what it should; it's just not very bright.

Of course, if you do find a bug in this markup system, let me know by writing to the blosxom list, or by posting at http://groups.yahoo.com/group/blosxom/messages/.

contents

Can't do/To do...

contents

Hints

  1. Wherever possible, the format model is visual. So if a head is immediately followed by a block of text, they will both be wrappped in a paragraph tag. To have the head "stand alone," separate it from other text with blank lines. Ditto for rules and blockquotes and lists.
  2. Don't forget the power of leading/trailing spaces...
  3. ...but don't obsess; you do not have to add any spaces to compensate for the effects of the markup.
  4. Italic markup is very aggressive. Link markup is protected against /, but escaped links are not. To represent plain old paths, escaping the leading / (if any) is usually enough: !/root/dir/file.txt. When in doubt, escape everything ;-)
  5. "Attributes" include event handlers, so yeah -- you can do js rollovers.
  6. You can tell blox to disable markup in an entry file by adding the comment:
    <!--nobloxmarkup-->
    to the story text, alone on a line.

contents

Versions

For some folks, markup is just plain overkill. For them, a re-mastered blox v0.98 is available here. This new v0.98 contains all of the fixes of v0.99, but none of the markup. The new v0.98 is identified as: 2004-10-30 (v0.98). All users should update to either v0.99 or the new v0.98r; v0.97 should be abandoned.

Though I've tested blox v0.99 quite extensively, there's nothing like release to prompt a change ;-) While the markup stabilizes, v0.99 changes will be indicated by a letter; the initial release is v0.99e. You can p'bly get blox in a couple of forms; see the blox download page.

Version History: blox_markup_guide.txt

2004-10-24 (v0.99e)- release for blox 99
2004-09-24 (v0.97d)- 1st release for blox 97

Version History: blox

2004-10-30 (v0.99e)- blox with markup; based on 2004-09-24 (0.98-11e)
2004-10-30 (v0.98r)- blox with no markup; based on 2004-09-24 (0.98-11e)
2004-09-24 (v0.98e)- markup
2004-09-22 (v0.97d)- named character classes dropped for perl <=5.006;
several settings are config'able; cleanup
2004-08-24 (v0.97a)- normal tagged links were being mangled; fixed
2004-07-22 (v0.97) - cleanup; add un-ignore, linebreaking, styles, graceful
PREs; convert line-ends in noblox file
2003-09-14 (v0.96) - better line-end conversion
2003-09-09 (v0.95) - LOL! put Win line-end chars in correct order ;-)
2003-08-31 (v0.94) - add Mac and Windows line-ending conversion
2003-08-30 (v0.93) - wip
2003-08-04 (v0.92) - add mechanisms to ignore specified entries
2003-07-31 (v0.9 ) - half-fast workaround for <PRE> tags
2003-07-20 (v0.8 ) - it's alive

contents

Hope You Enjoy!

- S2