Home of
info@simplewiki.org
- comments
- suggestions

join the forum

The Markup Language

posted November 21, 2009; updated December 27, 2013

The markup language specification has six parts:

Special Character patterns All special character patterns used to markup text - basic shortcuts
Link and Image URI formats Network protocol, symbolic link, and anchor formats of reference to links and images - shortcuts
Decorators The special inline decorator and block decorator markup, and selectors available - shortcuts for decoration arguments: classes, attributes, and styles
Tag Declarations The special tag declarations, and selectors available - other html formats
Decoration argument formats The standard decoration argument formats used to pass data to underlying html elements through decorators and declarations
Macros General markup available for client-defined macro procedures. The language specification does not define any macros

Specification

Marking up content so that it will look good involves using a few special characters (like forward slashes //emphasis// for emphasis, and a lot of decorators. Decorators are sequences of characters that provide detailed style information to the markup engine. The core of the language is creole 1.0. Decorators and Declarations (and a few other things) are extensions.

SimpleWiki Special Character Patterns

Character Pattern Usage Description
Basic markup - common shortcuts
= heading equals signs, 1 to 6 of them, start of line
paragraph blank line above text
// ... // emphasis (italic) 2 forward slash pairs, open and close
** ... ** strong (bold) 2 asterisk pairs, open and close
---- horizontal rule four dashes, alone on line
Basic markup - occasional shortcuts
\\ line break 2 inline backslashes
~ escape character tilde; the following character will be parsed as literal
`` line continuation 2 backticks start of line, to make the source more readable - these are stripped out during parsing
```comment... comment 3 backticks end of line to place comment in the source - comments are stripped out during parsing
Links and Images shortcuts
[[...|...|...]] link; caption and title optional opening and closing double square brackets; optional one or two vertical bars
[[#...|...|...]] anchor link; caption required, title optional opening double square brackets and hash mark, closing double square brackets; optional one or two vertical bars
[[#...]] anchor target opening double square brackets and hash mark, closing double square brackets
{{...|...|...}} image; caption and title optional opening and closing double braces; optional one or two vertical bars
Lists and Tables shortcuts
*
**
unordered list asterisk - one at start of first line; one or more, nested, on following lines[1]
#
##
ordered list hash mark - one at start of first line; one or more, nested, on following lines
: ... :: ...
:: ... :: ...
definition list colon - one at start of first line; one or more, nested, on following lines; the embedded double colon denotes the end of the term and the start of the description, and is optional. Without the double colon the text is the description.
|...|...|...| etc.
|...|...|...| etc.
quick table row vertical bars - beginning at start of line, plus one for each additional cell, plus closing vertical bar; multiple lines
|= heading cell (th) "=" following vertical bar in table row
Decorators - shortcuts for classes, styles, and attributes
% ... % inline decorator opening and closing percent sign, containing selector and decoration arguments, inline
%% end-of-span-decoration two percent signs, inline usage: %s ...%...%%
|: ... :| block decorator opening and closing mirrored vertical bar and colon, containing selector and decoration arguments, start of line
Advanced - tag declarations for other html shortcuts
[\t\x20]*(:? ... :)
...
[\t\x20]*(:?end:)
block tag declaration opening tag at start of a line, containing tagname and decoration arguments; closing tag alone on a later line; ?=tag name; [\t\x20]*=tab/space-chars (optional) for nesting and must match as to count of characters; end signifies closing tag
%=? ... % ... %=% inline tag declaration opening %= anywhere in the line, containing tagname and decoration arguments; closing markup %=% (optional) before the end of the line if only part of the line is to be marked; ? = tagname
[\t\x20]*(::? ... :) void block tag declaration - opening tag only; no content opening tag at start of a line, containing tagname and decoration arguments; ?=tag name;[\t\x20]*=tab/space-chars (optional)
%==? ... % void inline tag declaration - opening tag only; no content opening %== anywhere in the line, containing tagname and decoration arguments; ? = tagname
Advanced - other specialized markup
<< ... | ... >> macro, text optional opening and closing angle brackets, containing macro name and decoration arguments, optional vertical bar followed by parsed inline text
{{{...}}} inline preformatted text opening and closing triple braces, containing performatted text
{{{
...
}}}
preformatted block opening triple braces alone on a line, closing triple braces alone on later line; preformatted text in between
```## metadata 3 backticks followed by two hash marks - first line, followed by arguments interpreted by client software; obtained with
$dataobject = $wiki->get_metadata();
{{##? ... ##}} marker ?=name. Markers are extracted and marker objects are listed in an array that can be obtained with $wiki->markerdata() after $wiki->prepare(). Each marker object contains the marker name, its offset, and its decoration.
` symlink version marker (backtick) after a symlink selector for either an image or a link Symlink:selector`version, a backtick followed by a name can be used by a registered symlink handler to find a version of a file. Useful for image sizes for example.

Note that ordered and unordered lists can be nested within each other.

The first cell of Link and Image markups consist of a url to the link or image. For links the format can be any one of the three; for images the format can be protocol or symbolic.

Format Name Format Structure Notes
Network Protocol Format protocol://address standard url format: http, https, ftp, nntp, news, mailto, telnet, file, irc
Symbolic Link Format Symlink:selector symbolic links registered by client software; special link Local: is registered by SimpleWiki by default for relative directory addressing; Anchor: is also a default; first character of Symlink must be capitalized
Anchor Format #selector key symbolic link 'Anchor' can be registered to deal with html base issues if needed; set target element id attribute to selector
Raw link format selector When none of the above are recognized, the raw link is available to be passed to a client-registered raw link handler for interpretation

The special symbolic links Local: and Anchor: are registered by default by the SimpleWiki module. Local is intended to allow relative directory addressing for local references. Anchor is intended to allow on-page links.

See the Module section for details on registering symbolic links, symbolic link handlers, and raw link handlers with SimpleWiki.

In addition, free standing http, https, and mailto addresses will automatically have link markup [[ ... ]] wrapped around them. Other protocols (such as ftp) must escape the forward slashes in the format (like ftp:~//someaddress), or the forward slashes will be interpreted as emphasis markup.

Decorators

Decorators provide a uniform way of applying style classes, style-rules, and attributes to the objects created by the basic markup. They provide a thin (and simplified) veneer over HTML.

There are two kinds of decorators: inline decorators, and block decorators. Inline decorators begin and end with a percent sign %inlinedecorator%, and block decorators begin and end with a mirrored pair of characters (the vertical bar and colon) like this |:blockdecorator:|. All decorators have to be placed right in front of the opening markup for the objects they decorate.

Within their delimiters, inline and block decorators have identical markup structures:

%selector decoration_arguments%
|:selector decoration_arguments:|

The selector tells the markup engine what object type the decoration is applied to, and the decoration arguments convey the information about what to apply.

Inline Decorators

There are only four types of inline decorators:

SimpleWiki Inline Decorators
Selector Target object Notes Example
s span in front of a sequence of words, closed with %% %s underline%...%%
l link (l=lower case "L") in front of [[link]] %l newwin%[[...
i image in front of {{image}} %i rframe%{{...
c code in front of preformatted text {{{text}}} %c html%{{{...

Note that the closing markup of two percent signs %% closes the scope of the span (%s ...%) decoration.

Block Decorators

There are quite a few block decorators:

SimpleWiki Block Decorators
Selector Target object Example
Paragraph
p paragraph |:p font-weight:bold:|...
Dividers
h heading |:h section-divider-high:|===...
b empty block (divider)[2] |:b spacer dots:|
Lists
ul unordered list |:ul list-style-type:square:|* ...
ol ordered list |:ol list-style-type:upper-roman start="10":|# ...
li list item |:li font-style:italic:|# ...
|:ul list-style-type:square:||:li font-style:italic:|* ...
dl definition list |:dl ... :|: ...
dt definition term |:dt ... :|: ...
dd definition description |:dd ... :|: ...
|:dl ... :||:dt ... :||:dd ... :|: ...
Tables
table table |:table border="1":||...|...|...
tr table row |:tr background-color:yellow:||...|...|...
|:table border="1":||:tr background-color:yellow:||...|...|...
th table heading cell color green applied to second from left cell:
|=...|:th color:green:||=...|=...
three decorators applied to the same line:
|:table border="1":||:tr background-color:yellow:|
``|:th color:green:||=...|=...|=...
td table data cell |...|:td color:green:||...|...
td decorator usage is identical to th decorator usage
Preformatted Text
pre preformatted text block |:pre html:|{{{
...

Block decorators must be placed immediately in front of the objects that they decorate. Block dividers are placed on a line by themselves (the block object for block dividers is implicit).

When more than one block decorator is placed in front of an object (like |:table... and |:tr... in front of the same vertical bar), they must be placed in order, from outer object to inner object (for example table block decorator before table row block decorator).

Tag Declarations

The markup supports four kinds of tag declarations: block, void block, inline and void inline. "void" means an opening tag only, with no content. The markup summary is:

(:selector decoration_arguments:) content // block element
   more content
(:selectorend:)
(::selector decoration_arguments:) // void block element
%=selector decoration_arguments% content %=% // inline element
%==selector decoration_arguments% // void inline element

This markup not only avoids limitations for the sophisticated author, but also supports brevity and consistency of markup.

See Tag Def Extensions for ways of getting and setting the set of tags that your client software can control.

Block Tag Declarations

block declarations
Markup Tag Meaning HTML Tag
content blocks
div generic division div
blockquote indented block of content blockquote
table
table table table
caption caption caption
thead table head thead
tbody table body tbody
tfoot table footer tfoot
tr table row tr
td table data cell td
th column header cell th
colgroup column group colgroup
col column (but use void version instead) col
lists
ul unordered list ul
ol ordered list ol
li list item li
dl definition list dl
dt definition term dt
dd definition description dd
dlml (website - deprecated)
dlwidget dlml widget dl:widget
dlsettings dlml settings dl:settings
dlmodule dlml module dl:module
dlmarker dlml marker (reserved) dl:marker

For advanced page layout design, the markup provides block declarations. These are a thin veneer over html. The general syntax for block declarations is

<tab-or-space-char>*(:tagname decoration_arguments:)
...
<tab-or-space-char>*(:tagnameend:)


The tagname is required, and must be one of the tagnames listed in the tables at the right or below. Both opening and closing tags must be at the start of the line. Closing tags must be alone on a line. Opening tags can have content following on the same line to avoid generation of a paragraph block.

The <tab-or-space-char>'s are optional, but are available to allow nesting of blocks, like this:

(:div background-color:red:)
   some content
   (:div margin:20px bacground-color:green:)
      some more content
   (:divend:)
(:divend:)

... where the indents are matching numbers of tab or space characters.

The blocks can be nested in any combination to any (logical) depth. This allows, for example, complex tables inside table cells.

The decoration arguments are optional, but are available to set style classes, style rules, or attributes of the underlying HTML element. Action classes are also available (see below).

Each declared block (and nested declared block) is parsed as a block of content, and so can contain any of the markup structures made available, like quick tables, lists, etc.

The tags available for block declarations are listed at the right and below.

more block declarations
Markup Tag = HTML Tag Meaning Markup Tag = HTML Tag Meaning
HTML 5 semantic tags media tags
figure embedded figure map
figcaption figure caption object also allowed as inline tag
article self-contained content audio
address content author address video
aside related sidebar canvas
footer page footer form tags
section document section form
header page header output
hgroup header group datalist
nav navigation section muster widget tags
main main content reserved
details a disclosure widget mw-module
dialog popup dialog mw-widget
summary summary of details mw-settings
HTML 5 ruby tags mw-marker
ruby ruby annotation (East Indian languages) muster widgets is a javascript library planned by the author of this markup
rt explanation of ruby characters
rp ruby base text

Inline Tag Declarations

Inline tag declarations are markup for inline tags:

some content %=tagname decoration_arguments%some content%=% <- closing markup for inline tags

The following tags are supported (natively). Tags are filtered at compile time according to this list. If a tag is used that is not supported, the raw markup is output instead.

inline tag declarations
Markup Tag = HTML Tag Meaning Markup Tag = HTML Tag Meaning
appearance specialized
b bold a anchor
i italic img image
big q quote
small span
ins button
del progress
abbr meter
cite time
sub subscript object embedded
sup superscript bdi bi-directional isolation
mark bdo bi-directional over-ride
phrase elements form
code select
dfn definition option for select
em emphasis label
strong textarea
kbd keyboard misc
samp sample code command command button html5
var variable

Void Block Tag Declarations

Void tag declarations allow void tags (single tag - no content) markup.

(::tagname decoration_arguments:)
hr horizontal rule
area for map
param for object
source for audio
track for video
col col spec for colgroup

Void Inline Tag Declarations

Void tag declarations allow void tags (single tag - no content) markup.

%==tagname decoration_arguments%
br line break
wbr word break (html5)
img image
input form
keygen form
embed container for external application

Decorator and Tag Declaration Decoration Argument Formats

Decoration arguments are the data values that are passed from the Decorators and Tag Declarations to the target objects (meaning the underlying HTML elements). The decoration arguments for all decorators and tag declarations have the same structure. There are exactly three formats of argument available in all cases:

Argument Format Description Target
textvalue
(class name)
discreet textual value single name containing a character, followed by characters, numerals, underscore (_), or dash(-) HTML element class attribute
property
(style rule)
colon-separated rulename:
rulevalue
rulename follows classname rules; rulevalue always separated by colon (:); rulevalue can be surrounded by single or double quotes HTML element style attribute
attribute equals-separated attributename=
attributevalue
attributename follows classname rules; attribute value always separated by an equals sign; attributevalue can be surrounded by single or double quotes HTML element named attribute

There can be zero to many instances of each format of decoration argument, but for Decorators (not for Tag Declarations) there must be at least one decoration argument.

  • Classnames (unless they are registered action classes -- see below) are passed directly to the target object's (underlying HTML element) class attribute. When classnames are directly passed through like this they are called style classes.
  • Style rules (unless they are registered action properties are passed directly to the target object's style attribute.
  • Attributes are passed directly to the underlying target objects as is. Note that the attributes value delimiter that is written by the author is preserved in html generation. This allows JSON arguments to be used for custom attributes.

In this way, SimpleWiki can be viewed as a thin (simplifying) skin over the HTML layer of the web page.

Style classes are any classes defined in css (cascading style sheet) files that are created for the website. Style classes are named collections of style rules.

Action classes are any classnames (registerd as methods by the client application using SimpleWiki) that perform software-based operations on the underlying HTML elements. SimpleWiki contains a number of native action classes. Action classes serve as automation shortcuts to achieve desired effects. Action properties are analagous to action classes (propertymethod:methodarguments) except their format allows passing of arguments to the methods. Property methods are also registered by client software, and should be unset as html properties during processing to prevent them from being interpreted natively as styles.

Style rules can be any valid CSS style rules.

Attributes can be any valid attributes for the target's underlying HTML element.

It is a generally accepted best practice to rely on logically named style classes as much as possible, to allow for centralized revision of style schemes. The corollary is to avoid explicit style rules as much as possible. In most cases, styling options available through attributes are better implemented using css style rules.

Macros

Macros are registered by client software, and interpreted by callback functions. Macro syntax allows for the macroname, arguments in standard formats, and parsed inline markup to the right of a vertical bar. How these resources are used is up to the callback function. See the Module section for details.

The SimpleWiki module registers one macro by default: quicktoc. This macro uses any markup title as the quick table of contents header, if present (otherwise uses the string "Table of contents").


Footnotes:
  • ^[1] The first list item in a list must have only one star or hashmark. This is to avoid conflict with the two-star strong markup
  • ^[2] The b decorator is for an empty block, and must be alone on a line. To create a div use |:p div:| ("change paragraph into div") instead, or use the (:div...:) block declaration
digital ocean version