Butterfly Markup

auto-generated on 2011-05-31 23:59:27Z

Butterfly is a semantic markup syntax created and developed by Tommy Montgomery. It is similar to many wiki syntaxes (such as MediaWiki). It's goal is to be familiar, easy to read, and simple to use.

This document serves as both a test of the markup itself and documentation on how to use it. This document was automatically generated by a unit test using Butterfly itself to generate everything inside the <body> tag.

Output Formats

Butterfly uses an Analyzer to transform markup to an output format. The default is HTML, but you can implement your own analyzer by injecting a custom implementation of ButterflyNet.Parser.ButterflyAnalyzer into a ButterflyNet.Parser.ButterflyParser instance.

Text Formatting

Style	Markup	Output
Bold	`this text is __bold__`	this text is bold
Emphasis	`this text is ''emphasized''`	this text is emphasized
Teletype	`this text is ==reminiscient of a typewriter==`	this text is `reminiscient of a typewriter`
Underline	`this text is --important--`	this text is important
Strike-through	`this text is ---deleted---`	this text is ~~deleted~~
Big	`this text is (+big and (+huge+)+)`	this text is big and huge
Small	`this text is (-small and (-tiny-)-)`	this text is small and tiny

Links

Hyperlinks are surrounded by brackets. You can specify the text by separating it from the URL with a |.

Markup	Output
`[link]`	link
`[link\|totally ''awesome'' link, brah!]`	totally awesome link, brah!
`[http://example.com/]`	http://example.com/
`[http://example.com/\|external link]`	external link
`[link.html\|link text with [bracket]]]`	link text with [bracket]

You can change the base URL of local links by modifying the ButterflyParser.LocalLinkBaseUrl property.

Headers

Headers start with a variable number of ! at the beginning of a line.

!Header level 1
!!Header level 2
!!! !Header that starts with an exclamation point!

Header level 1

Header level 2

!Header that starts with an exclamation point!

Lists

Bullet Lists

Bulleted lists are opened by a * (unordered) or a # (ordered) at the start of a line. To increase the nesting level, add more asterisks or hashes. You cannot mix list types at the same depth.

The following markup:

* Countries
*# United States
*#* West Coast
*#** Washington
*#** Oregon
*#** California
*#* East Coast
*#** Florida
*#** Maryland
*#** Georgia
*#** Massachusetts
*# Canada
*# Mexico
* See also
** Wikipedia: [http://en.wikipedia.org/wiki/List_of_sovereign_states]

Gets transformed into:

Countries
1. United States
  - West Coast
    - Washington
    - Oregon
    - California
  - East Coast
    - Florida
    - Maryland
    - Georgia
    - Massachusetts
2. Canada
3. Mexico
See also
- Wikipedia: http://en.wikipedia.org/wiki/List_of_sovereign_states

Definition Lists

Definition terms are opened by a ; at the start of a line. Definitions of those terms are opened by a : at the start of the subsequent line.

e.g.

;Elephant
:Big grey animals that have superstitiously accurate memories
;Baby elephant
:Baby elephants are called ''calves'', apparently

transforms into

Elephant: Big grey animals that have superstitiously accurate memories
Baby elephant: Baby elephants are called calves, apparently

Preformatted Text

Single-line

For single line snippets of preformatted text, start a line with a space.

Not preformatted
 preformatted

Not preformatted

preformatted

Multi-line

For multiline preformatted text, surround with {{{ and }}}. Note that markup is allowed inside these blocks.

{{{
this is
preformatted
text and line breaks
and             whitespace
are preserved (and so is __markup__)
}}}

this is
preformatted
text and line breaks
and             whitespace
are preserved (and so is markup)

Preformatted Code

For chunks of code, surround with {{{{ and }}}}. All this does is disable formatting.

{{{{
this is
preformatted
text and line breaks
and             whitespace
are preserved (and so is __markup__)
}}}}

this is
preformatted
text and line breaks
and             whitespace
are preserved (and so is __markup__)

Specifying a programming language with syntax highlighting

You can specify a programming language immediately after the opening {{{ or {{{{. By default, Butterfly uses Sunlight for syntax highlighting, but it also supports Prettify, Highlight.jsand Syntax Highlighter.

{{{csharp
public class MyClass : ICloneable {
	public string GetSomething(int i) {
		if (i < 0) {
			return string.Empty;
		}

		return string.Format("i: {0}", i);
	}
}
}}}

becomes

public class MyClass : ICloneable {
	public string GetSomething(int i) {
		if (i < 0) {
			return string.Empty;
		}

		return string.Format("i: {0}", i);
	}
}

Blockquotes

Blockquotes are opened with << at the beginning of a line, and closed with >>.

<<this is a blockquote>>

<<
so is this
>>

<<
you can have

* markup
* as well as __textual styles__
** inside a blockquote
>>

this is a blockquote

so is this

you can have

markup

as well as textual styles

inside a blockquote

Horizontal Ruler

You can insert a horizontal ruler by creating a line consisting of four dashes ----.

this is some text
----
here is more text

this is some text

here is more text

Modules

Modules are extensions to the parser that allow for injecting user-defined functionality in the form of function calls. Each module has a unique name, and can be passed arguments.

Images

In Butterfly, images are implemented as modules.

Markup	Output
`[:image\|url=butterfly.png]`
`[:image\|url=butterfly.png\|title=A pretty butterfly\|width=100\|height=150]`
`[:image\|url=nonexistent.png\|alt=[an image]]]`

You can change the base URL of local images by modifying the ButterflyParser.LocalImageBaseUrl property.

HTML Entities

Since Butterfly escapes all output (when it transforms to HTML), you can't render an HTML entity (the & gets encoded to &). To get around this you can use the HTML entity module to render an HTML entity.

Markup	Output
`[:entity\|value=copy]`	©
`[:entity\|value=#169]`	©
`[:entity\|value=#xa9]`	©

Unicode

Butterfly is unicode-safe, so you can just use straight-up Unicode and it will render as Unicode (unencoded). Make sure that you are rendering your page in UTF-8.

Один главный процесс и несколько рабочих, рабочие процессы работают под непривилегированным пользователем

Forced Line Breaks

To force a line break, use %%%.

this text will
be on the same line

but this text %%% has a line break

this text will be on the same line

but this text
has a line break

Tables

To render a table, start a line with |. Each cell is separated by a |. Use |! to render a table header instead of a table cell.

|! cell 1 |! cell 2 |
| row 2 cell 1 | row 2 cell 2|
| row 3 cell 1 | row 3 cell 2| row 3 cell 3 |

becomes

cell 1	cell 2
row 2 cell 1	row 2 cell 2
row 3 cell 1	row 3 cell 2	row 3 cell 3

Table rows are separated by linefeeds. If you need more complicated markup inside a table row, you can open a multiline table row with |{ and close it with }|.

|! header |! header2 |
|{ this is a multiline row 
You can have all kinds of markup in here.

* like a list
** and even a nested list!

| cells are still separated by a [!|] 

<<I'm sexy

[:entity|value=mdash] [http://tommymontgomery.com/|Tommy Montgomery]
>>
}|

becomes

header	header2
this is a multiline row You can have all kinds of markup in here. like a list and even a nested list!	cells are still separated by a \| I'm sexy — Tommy Montgomery

Unparsed Text

Surround text with [! and ] to make the parser ignore it.

[! this will __not__ be parsed
* not a list

| not a table |
]

becomes

this will __not__ be parsed * not a list | not a table |

Note that newlines are ignored as well, so a chunk of text inside [!] will always be one single paragraph.

Macros

Macros are another extensibility point. Macros are similar to modules, except that they are completely deterministic, whereas a module can render (or not render at all) in a variety of ways depending on context. A macro evaluates to a hard value.

Macros are surrounded by [:: and ].

Current Timestamp

The timestamp macro prints the current timestamp in a variety of formats designated by the .NET date formats. If no format is given, it defaults to the Universal Sortable format.

Markup	Output
`[::timestamp]`	2011-05-31 23:59:27Z
`[::timestamp\|format=dddd, MMMM dd yyyy]`	Tuesday, May 31 2011

Markup	Output
`[:image\|url=butterfly.png]`
`[:image\|url=butterfly.png\|title=A pretty butterfly\|width=100\|height=150]`
`[:image\|url=nonexistent.png\|alt=[an image]]]`