This is the WikklyText user documentation (version 1.3.4-WIP).

You can generate this help file by placing <<help>> inside any wiki text.

Formatting

Bold

Markup	'' ... ''
Example	here is ''bold text''
Result	here is bold text

Italic

Markup	// ... //
Example	here is //italic text//
Result	here is italic text

Strikethrough

Markup	-- ... --
Example	here is --strikethrough text--
Result	here is strikethrough text

Underlined

Markup	__ ... __
Example	here is __underlined text__
Result	here is underlined text

Superscript

Markup	^^ ... ^^
Example	here is ^^superscript text^^
Result	here is ^{superscript text}

Subscript

Markup	~~ ... ~~
Example	here is ~~subscript text~~
Result	here is _{subscript text}

Comments

Markup	/% ... %/
Example	/% A comment produces no output %/
Result
Caveats	Comments are not allowed to nest.

Markup	/* ... */
Example	/* The comment markers are removed. Inner text ''is'' //processed// __normally__. */
Result	The comment markers are removed. Inner text is processed normally.
Caveats	Comments are not allowed to nest.

Markup	<!--- ... --->
Example	<!--- The comment markers are removed. Inner text ''is'' //processed// __normally__. --->
Result	The comment markers are removed. Inner text is processed normally.
Caveats	Comments are not allowed to nest.

Highlighted

Markup	@@ ... @@
Example	Here is @@highlighted text@@
Result	Here is highlighted text

Applying CSS classes

Markup	{{class{ ... }}}
Example	Here is {{grayout{grayed-out text}}} with CSS
Result	Here is grayed-out text with CSS

More on Classes

Classes are flowed down into inner elements by appending them after any classes applied previously. This is especially useful when you want to override implicit styling:

A link using implicit styling:
* http://wikklytext.com

A link using my styling to override:
* {{test_overline{http://wikklytext.com}}}

Result:

A link using implicit styling:

http://wikklytext.com

A link using my styling to override:

http://wikklytext.com

Inline CSS styles (with @@style; ...)

Markup	@@styles; ...
Example	@@color: green; font-style: italic; hello world@@
Result	hello world
Caveats	Not available in Safe Mode

Inline styling (with old-style color() statement)

Markup	@@color(color): ... @@
Example	testing @@color(green): green text@@
Result	testing green text
Caveats	Not available in Safe Mode

Inline-styling (with old-style bgcolor() statement)

Markup	@@bgcolor(color): ... @@
Example	testing @@bgcolor(yellow): yellow background@@
Caveats	Not available in Safe Mode
Result	testing yellow background

Link

Markup	[[Link Text\|URL]]
Example	Here is a [[link to wikklytext.com\|http://wikklytext.com]]
Result	Here is a link to wikklytext.com

Image (no link)

Markup	[img[file]]
Example	[img[css/img_link_www.png]]
Result

Bare URLs are turned into links as well:

Markup	http:// ..., file:/// ..., ftp:// ..., etc.
Example	http://boodebr.org/python, mailto:nobody@nowhere.com
Result	http://boodebr.org/python, mailto:nobody@nowhere.com

Image (with link)

Markup	[img[file][URL]]
Example	[img[css/img_link_www.png][http://wikklytext.com]]
Result

Raw HTML

Markup	<html> ... </html>
Example	<html>Raw <b>HTML</b>, all <i>wiki markup</i> {{{ is }}} ignored}}</html>
Result	Raw HTML, all wiki markup {{{ is }}} ignored}}
Caveats	HTML blocks are not allowed to nest. This markup is not available in Safe Mode.

NoWiki

Markup	<nowiki> ... </nowiki>
Example	<nowiki><nowiki>, ignores <b>all</b>   //markup//</nowiki>
Result	<nowiki>, ignores <b>all</b>   //markup//
Caveats	nowiki blocks are not allowed to nest.

Line-break

Markup	<br> or <br/>
Example	Here is a<br>break and<br/>another break
Result	Here is a break and another break

Dash

Markup	--
Example	And then -- eureka!
Result	And then — eureka!

Separator

Markup	---- (On a line by itself.)
Example	----
Result

HTML Entities

Markup	&ENTITY;, &NNN;, &#xHH
Example	Π <br> 1 + 2 = 3
Result	Π 1 + 2 = 3

NULL-dot

Markup	. (On a line by itself.)
Example	.
Result

This is a WikklyText extension. The NULL-dot allows you to spread your text out for readability without causing blank lines to be inserted.

NOP

Markup
Example	Hello World
Result	Hello World

This is a WikklyText extension. The NOP sequence is always removed from the final markup. It allows you to break-up sequences that would otherwise be identified as markup, where no other escaping methods work.

Inline code

Markup	{{{ ... }}}
Example	Here is an {{{inline code}}} sample
Result	Here is an inline code sample
Caveats	Code blocks are not allowed to nest.

Code Blocks

Markup	{{{ ... ... }}}
Example	{{{ for i in range(20): print i print i*10 }}}
Result	for i in range(20): print i print i*10
Caveats	Code blocks are not allowed to nest.

Markup	/{{{/ ... ... /}}}/
Example	/{{{/ Here is a block of code. /}}}/
Result	Here is a block of code.
Caveats	Code blocks are not allowed to nest.

Markup	//{{{ ... ... //}}}
Example	//{{{ Here is a block of code. //}}}
Result	Here is a block of code.
Caveats	Code blocks are not allowed to nest.

Markup	<!--{{{--> ... ... <!--}}}-->
Example	<!--{{{--> Here is a block of code. <!--}}}-->
Result	Here is a block of code.
Caveats	Code blocks are not allowed to nest.

Block-Indent

Markup	<<< ... <<<
Example	<<< A block-ident indents the inner wiki text, preserving all other formatting. For example, here is a list: * One * Two Two.A Two.B * Three <<<
Result	A block-ident indents the inner wiki text, preserving all other formatting. For example, here is a list: One Two Two.A Two.B Three

Line-Indent

Markup	> ... >> ... >>> ... > ...
Example	> Level one<br> > here >> Level two<br> >> here >>> Level three<br> >>> here > Level one<br> > here
Result	Level one here Level two here Level three here Level one here

Numbered list

Markup	# ... 1st level ... ## ... 2nd level ... ### ... 3rd level ...
Example	/% Leading spaces are optional %/ # Item One ## Item Two ### Item three # Item Four
Result	Item One Item Two Item three Item Four

Unnumbered list

Markup	* ... 1st level ... ... 2nd level ... * ... 3rd level ...
Example	/% Leading spaces are optional %/ * Item One Item Two * Item three * Item Four
Result	Item One Item Two Item three Item Four

Headings

Markup	!1st level !!2nd level !!!3rd level
Example	!Heading, level 1 !!Heading, level 2 !!!Heading, level 3 !!!!Heading, level 4 !!!!!Heading, level 5 !!!!!!Heading, level 6
Result	Heading, level 1 Heading, level 2 Heading, level 3 Heading, level 4 Heading, level 5 Heading, level 6

Markup

!1st level
!!2nd level
!!!3rd level

Example

!Heading, level 1

!!Heading, level 2

!!!Heading, level 3

!!!!Heading, level 4

!!!!!Heading, level 5

!!!!!!Heading, level 6

Result

Heading, level 1

Heading, level 2

Heading, level 3

Heading, level 4

Heading, level 5

Heading, level 6

Definition List

Markup	;Term :Definition
Example	;Term 1 :This is the definition of Term 1 ;Term 2 :This is the definition of Term 2
Result	Term 1 This is the definition of Term 1 Term 2 This is the definition of Term 2

Tables

Use | to separate columns and ! to mark header cells.

|!a|!b|!c|
|!d|e|f|
|!g|h|i|

a	b	c
d	e	f
g	h	i

For column spans, put > in the skipped columns:

|!a|!b|!c|
|!d|>|colspan=2|
|!g|h|i|

a	b	c
d	colspan=2
g	h	i

For row spans, put ~ in the skipped rows:

|!a|!b|!c|
|!d|rowspan=3|f|
|!g|~|i|
|!j|~|l|

a	b	c
d	rowspan=3	f
g		i
j		l

You can add a caption by adding a row like this (note there is no trailing '|'):

|A Table Caption|c

Example:

|!aaaaaaaa|!bbbbbbbb|!ccccccccc|
|!d|e|f|
|!g|h|i|
|A Table Caption|c

Result:

A Table Caption
aaaaaaaa	bbbbbbbb	ccccccccc
d	e	f
g	h	i

Coloring cells with bgcolor():

|a|b|c|
|bgcolor(yellow):yellow here|>|bgcolor(#ff0000):red here|
|>|>|bgcolor(green): @@color: white; font-weight: bold;bold white on green by mixing styles@@ |

a	b	c
yellow here	red here
bold white on green by mixing styles

Text Justification in Table Cells

Text justification follows TiddlyWiki's rules on leading/trailing spaces:

Leading spaces: Right justify
Trailing spaces: Left justify
Leading and trailing spaces: Center justify
No spaces:
- Header cell: Center justify
- Normal cell: Left justify
Leading spaces on bgcolor(), if used: No effect on calculation

Example

Result

left header	center header
aaaaaaaaaaaaaaaaaaa	bbbbbbbbbbbbbbbbb	cccccccccccccccccccc
right header	center header
left text	center text	right text
left text
left text	center text	right text
left text

Unicode and Multibyte character sets

WikklyText fully supports multilingual content using both traditional multibyte character sets as well as Unicode. See multilanguage examples for details.

Macros

Calling a Macro

Markup	<<macroname arg1 arg2 ...>>
Example	<<echos aaa "bbb" 'ccc' """ddd""" '''eee''' <quote>"fff"</quote>>>
Result	aaa bbb ccc ddd eee "fff"

Writing Macros

See coremacros.py in the WikklyText distribution for complete examples of macros.

You can also define macros inside your wikitexts like this:

<?py
def mytable(context, width, height):
    # args are Elements - convert .text part
    width = int(width.text)
    height = int(height.text)
    txt = 'A %d by %d table\n' % (width,height)

    for i in range(height):
        # row
        for j in range(width):
            txt += '|%d' % (i*width + j + 1)

        txt += '|\n'

    return txt
?>
/% call it ... %/
<<mytable 4 10>>

Inside a macro, the following globals are always available:

Element, SubElement	From ElementTree
Text	Convenience to make a <Text> node. Usage: Text("some text")
WikError	If you need to raise an Exception, use this type.
FS_CWD	The (physical) location of your wikitext. If you need to open a file relative to your wikitext location, do: open(os.path.join(FS_CWD,filename), ...)

When writing inline code, <?py and ?> must be the first and last things on a line (although the code can span multiple lines).

Differences between TiddlyWiki & WikklyText

There are probably more differences than I've listed here, these are just the ones I've noted to date. Most are due to personal preference in situations where I don't like something TiddlyWiki does. See the footnotes for details, if you are interested.

Item	TiddlyWiki	WikklyText
Allows leading spaces in listitems * # ; :	NO	YES¹
Allows leading spaces in separators ----	NO	YES¹
Allows leading spaces in bgcolor()	NO	YES²
Allow extra spaces inside @@ .. @@	NO	YES²
Allows full markup in links	NO	YES
Effect of a single linebreak character	Breaks paragraph	Paragraph continues flowing until double linebreak³ Use <<set $REFLOW 0>> to get TiddlyWiki behavior
Maximum header depth	5; extra "!" chars are shown	6; extra "!" chars are hidden⁴
WikiWords are automatic links	YES	YES
Anchors within document	NO	YES⁵
Output Formats	TiddlyWiki All-in-one self-contained wiki	XML, HTML, Drupal plugin, or standalone Wiki Modular library useful in any number of situations, plus a wiki server.
Image float left/right	YES	NO⁹
In tables: Classes, THEAD, TFOOT	YES	NO⁹ Use {{class{ to set styles for tables and elements.
Macros
Macro language	Javascript	Python
How macros work ...	Create DOM elements directly in wiki	Return etree.Elements or strings (that are reparsed for wiki content)
Arg quoting	unquoted, ', "	unquoted, ', ", ''', """, <quote> .. </quote>⁶
Arg: "aaa"bbb'ccc'	Two args (aaa and bbb'ccc')	One arg (aaabbbccc) Auto-concatenation of adjacent strings⁷
Nested macro calls?	PARTIAL¹⁰	YES⁸
Thread-safe storage for data persistence across macro calls?	NO	YES
Python/C style escapes in argument strings?	NO	YES

Footnotes:

I like my wiki source texts to be indented the same as they will render in HTML. Also, many editors (like jEdit) auto-indent by default, and it is harder to delete the indents than leave them in.
No particular reason, just to be lenient.
This could be argued either way - TiddlyWiki's way is more WYSIWYG, but I prefer to be able to write a long paragraph without having to put it all on one line.
6 levels are supported because that is what HTML defines as the maximum.
You can create document anchors like this:
- Create anchor: [[#anchor_name]]
- Link to anchor: [[Link text|#anchor_name]]
I say, the more quoting methods the better, and this was inspired by Python's triple-quoted strings. The extension <quote> ... </quote> comes in handy especially when you are quoting Python code in a macro call that already contains the other quote types.
NOTE: Unlike Python, Single-vs-Triple strings are not special. They are both allowed to contain embedded newlines, etc.
Similar to Python and the C-preprocessor, cramming strings together works.
The only time they cause a problem is if a macro returns text containing << that is then parsed as another macro call. This limitation will be corrected in WikklyText 2.x
Will likely be added to WikklyText at some point.
As I understand it, TiddlyWiki somewhat supports nested macros with an extended call syntax, but WikklyText supports nesting like this:
<<one <<two <<three>> >> >>
... where <<two gets the returned value from <<three>> as an input arg.

Built-in Macros

closeAll
codebox
debug (Full Mode only)
div (Full Mode only)
echo
echos
get
help
if_full_mode
if_safe_mode
include (Full Mode only)
include_code (Full Mode only)
include_pyfunc (Full Mode only)
include_pymod (Full Mode only)
indent
info
infobox
note
py_add_path (Full Mode only)
set
span (Full Mode only)
version
warn
warnbox

closeAll

Usage	<<closeAll>>
Description	This only exists for compatibility with TiddlyWiki texts. It does not do anything.
Example	<<closeAll>>
Result

codebox

Usage	<<codebox title arg [arg ...]>>
Description	Like a regular code box, except with a title.
Example	<<codebox "A Title" ''' for i in range(10): print i'''>>
Result	A Title for i in range(10): print i

debug (Full Mode only)

Usage	<<debug arg arg ...>>
Description	Prints arguments to stdout - does not become part of document.
Example	No example, to prevent console noise.
Result

div (Full Mode only)

Usage	<<div class style id text>>
Description	Create a block element (like <div>).
Example	<<div "foo" "color:green; border: 1px solid red;" "baz" "I am //italic// here">>
Result	I am italic here
Notes	Generally speaking, this is meant to be used to create empty elements that are subsequently populated via Javascript. However, the text argument will be evaluated as wikitext so you can insert content directly, if desired. Use an empty string to leave an attribute undefined.

echo

Usage	<<echo arg arg ...>>
Description	Echo back input arguments. Arguments are wikified just as if they were inline.
Example	<<echo "//Hello//-" world '''-__macro__'''>>
Result	Hello-world-macro

echos

Usage	<<echos arg arg ...>>
Description	Like echo but adds a space between arguments.
Example	<<echos "AAA" BBB '''CCC'''>>
Result	AAA BBB CCC

get

Usage	<<get name>>
Description	Get the wikitext stored in the named variable (from an earlier call to <<set>>).
Example	<<set TestVar "Some __text__ ''here''">> <<get TestVar>>
Result	Some text here

help

Usage	<<help>>
Description	Generates this help text.
Example	<<help>>
Result	You're looking at it!

if_full_mode

Usage	<<if_full_mode arg arg ...>>
Description	If running in Full Mode, return wikified args, else return nothing.
Example	<<if_full_mode "Hello ''Full Mode''">>
Result	Hello Full Mode

if_safe_mode

Usage	<<if_safe_mode arg arg ...>>
Description	If running in Safe Mode, return wikified args, else return nothing.
Example	<<if_safe_mode "Hello ''Safe Mode''">>
Result

include (Full Mode only)

Usage	<<include filename>>
Description	Include the entire contents of a file (contents will be parsed as wiki text). The included file is allowed to have a different text encoding than the current file.
Example	''An ASCII encoded file:'' <<include "doc/mbsamples/english.txt">> ''An ISO-8859-7 (Greek) encoded file:'' <<include "doc/mbsamples/greek.txt">>
Result	An ASCII encoded file: English (ASCII): Hello world! An ISO-8859-7 (Greek) encoded file: Greek (ISO-8859-7): Γεια σου, κόσμε!

include_code (Full Mode only)

Usage	<<include_pyfunc filename title>>
Description	Include a file as a block of code (as if it were included inside {{{ .. }}}). Searches in sys.path and '.' if absolute path not given. title is the title for the box. If not given it defaults to filename.
Example	<<include_code doc/sample.py>>
Result	ERROR - No such file or resource "doc/sample.py"

include_pyfunc (Full Mode only)

Usage	<<include_pyfunc modulename funcname title>>
Description	Include the source code for a single Python function from the named module. Module must be in sys.path or '.'. title is the title for the box. If not given it defaults to modulename.funcname().
Example	<<include_pyfunc atexit register>>
Result	atexit.register() def register(func, targs, *kargs): """register a function to be executed upon normal program termination func - function to be called at exit targs - optional arguments to pass to func kargs - optional keyword arguments to pass to func """ _exithandlers.append((func, targs, kargs))

include_pymod (Full Mode only)

Usage	<<include_pymod modulename title>>
Description	Include the source code for a Python module. Module must be in sys.path or '.'. title is the title for the box. If not given it defaults to modulename.
Example	<<include_pymod statvfs "A Title">>
Result	A Title """Constants for interpreting the results of os.statvfs() and os.fstatvfs().""" # Indices for statvfs struct members in the tuple returned by # os.statvfs() and os.fstatvfs(). F_BSIZE = 0 # Preferred file system block size F_FRSIZE = 1 # Fundamental file system block size F_BLOCKS = 2 # Total number of file system blocks (FRSIZE) F_BFREE = 3 # Total number of free blocks F_BAVAIL = 4 # Free blocks available to non-superuser F_FILES = 5 # Total number of file nodes F_FFREE = 6 # Total number of free file nodes F_FAVAIL = 7 # Free nodes available to non-superuser F_FLAG = 8 # Flags (see your local statvfs man page) F_NAMEMAX = 9 # Maximum file name length

indent

Usage	<<indent arg arg ...>>
Description	Do a block indent, preserving all other formatting. Functionally, this is the same as: {{indent{ ... }}} ... but sometimes a macro is more convenient.
Example	Next line<br><<indent 'is indented'>>
Result	Next line is indented

info

This is an alias for <<infobox>>.

Example	<<info "Hello title" Hello " " content>>
Result	Hello title Hello content

infobox

Usage	<<infobox title content [...]>> <<infobox content>>
Description	First form: Create an information box with a title. Second form: Create a box with no title.
Example	<<infobox "A Title" AA BB CC " and //italic text//">> <<infobox "This box has no title and uses a ''different'' __style__.">>
Result	A Title AABBCC and italic text This box has no title and uses a different style.

note

Usage	<<note text>>
Description	Create a simple note box without a title.
Example	<<note "Here is a note with //italic text// and ''bold text''.">>
Result	Here is a note with italic text and bold text.

py_add_path (Full Mode only)

Usage	<<py_add_path path>>
Description	Add the given path to sys.path. This is useful when you want to use include_code, include_pyfunc or include_pymod on a module in an arbitrary location.
Example	<<set TestVar "Some __text__ ''here''">>
Result	No return value.

set

Usage	<<set name arg arg ... >>
Description	Create a named variable containing the given wiki text. The text is evaluated (just as if it was inline) and stored. It can be retrieved later with get(). NOTE: Names beginning with $ are reserved for system use.
Example	<<set TestVar "Some __text__ ''here''">>
Result	No return value.

span (Full Mode only)

Usage	<<span class style id text>>
Description	Create an inline element (like <span>).
Example	<<span "foo" "color:red; font-weight: bold;" "baz" "I am //italic// here">>
Result	I am italic here
Notes	Generally speaking, this is meant to be used to create empty elements that are subsequently populated via Javascript. However, the text argument will be evaluated as wikitext so you can insert content directly, if desired. Use an empty string to leave an attribute undefined.

version

Usage	<<version>>
Description	Get the WikklyText version number.
Example	<<version>>
Result	1.3.4-WIP

warn

This is an alias for <<warnbox>>.

Example	<<warn "Hello title" Hello " " content>>
Result	Hello title Hello content

warnbox

Usage	<<warnbox title content [...]>> <<warnbox content>>
Description	First form: Create an warning box with a title. Second form: Create a box with no title.
Example	<<warnbox "A Title" AA BB CC " and //italic text//">> <<warnbox "This box has no title and uses a ''different'' __style__.">>
Result	A Title AABBCC and italic text This box has no title and uses a different style.

Contents