Controls: show

Document

Comments:

[log in] or [register] to leave a comment for this document.


Go to: all documents

Options: show

Contact:

mail@musterdb.net

Website:

[home] [about] [help]

Subsites:
Members:

[profiles] [forum]

Document

Mastering Muster Markup

16-Nov-2012 Toronto [29]

• Levels: basic markup, decorators, declarations, embedded html

Part of Documentation

The Muster Wiki Markup

Each content record in Muster Wiki (see Creating and Maintaining Content) has one field (and only one) that can take (possibly lengthy) content decorated using wiki markup. Wiki markup is sometimes called "What You See Is What You Mean" (WYSISYM - ie. you see the decoration instructions) rather than the more common "What You See Is What You Get" (WYSIWYG).

Depending on the record type, this wiki markup field may be called Body, About, Cover Page, or Commentary.

Muster Wiki uses wiki markup because it is simple, reliable, and flexible. The specific markup used, Simplewiki, was developed in conjunction with the Muster Wiki project to include the simplicity of basic wiki markup without limitations for advanced formatting.

Because this wiki markup allows advanced markup, Muster Wiki authors should be trusted.

You can gradually move through the levels of markup with practice. What many groups do is appoint volunteers for the more advanced levels. Then authors can write or paste in their basic content, and have the more advanced markup editors contribute more elaborate decoration.

Level 1: Basic Markup

Simple Markup Character Patterns

Basic markup consists of inserting simple character markup patterns (like "//") in your text. These markup patterns are interpreted to create decorated output.

-- basic markup --
=====Heading=====

This is a paragraph with //italic//,\\ 
**bold**, and **//both//**.

----
(horizontal rule)

line\\break

comments follow three backticks,\\
and are invisible: ``` comment

line extensions (2 backticks)
`` are removed\\
(useful for formatting markup)

The tilde makes the next character a
literal eg. for the double~\\backslash\\
(instead of a line break)
Heading

This is a paragraph with italic,
bold, and both.


(horizontal rule)

line
break

comments follow three backticks,
and are invisible:

line extensions (2 backticks) are removed
(useful for formatting markup)

The tilde makes the next character a
literal eg. for the double\\backslash
(instead of a line break)

--
Markup Helper Buttons

In Muster Wiki there are markup helper buttons in edit mode for heading, bold, and italic, and this makes it even easier. Highlight the text you want to decorate, and hit the button that you want to decorate the text for you. (For headings hit the button one to six times for the correct depth of heading that you want).

Lists and Links

Markup for lists and links (shown below), and pictures and widgets (not shown) is also pretty simple.

-- lists and links markup --
*a list item
*another list item
*yet another list item

#first list item
#second list item
#third list item

:definition list::is a list
:radish::is a plant
:goat::is an animal




```internal link to 'creating content'...
[[Node:17| + | + ]]\\
(using a record number for the link)

```external link in new window...
%l newwin%[[http://simplewiki.org|Simplewiki]]
  • a list item
  • another list item
  • yet another list item
  1. first list item
  2. second list item
  3. third list item
definition list
is a list
radish
is a plant
goat
is an animal

Creating and Maintaining Content
(using a record number for the link)

Simplewiki

--

There are buttons in edit mode to help with most of this markup. Also, note that the Node link automatically looks up the Title (and Caption for a float-over title if there is one) with the '+' instruction.

Use Record Numbers for Internal Links, Pictures, and Widgets

For internal links, pictures, and widgets, just find the right record number for the item, paste it in your markup code, highlight the record number, and hit the correct markup helper button, which will surround the record number with the correct markup.

Quick Table

Now here's an example of a quick table:

-- quick table markup --
|=column 1|=column 2|=column 3|
|a|b|c|
|1|2|3|
column 1 column 2 column 3
a b c
1 2 3
--
Markup Helper Table

In addition to markup helper buttons, there's also a (popup) markup helper table in edit mode to insert more advanced markup for you (see the link beside the helper buttons).

Level 2: Decorators

Decorators provide a uniform way of applying style-classes, style-rules, and attributes to the objects created by simplewiki's 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, decorators have identical markup structures:

%selector arguments%
|:selector arguments:|

The selector tells the markup engine what object type the decoration is applied to, and the arguments convey the information about what to apply. Discreet text values are interpreted as classes, colon-separated values are interpreted as style rules, and equals-sign-separated values are interpreted as attributes.

For example, the quick table markup above can now be modified as follows:

-- quick table markup with decorators--
|:table id=quicktable standard width:100%:|
``|=column 1|=column 2|=column 3|
|:tr background-color:#ddd:|
``|a|b|c|
|:td background-color:red color:yellow:|
``|1
``|:td background-color:blue color:white:|
``|2|3|
column 1 column 2 column 3
a b c
1 2 3
--

Here's an example of an inline span decorator:

-- a span decorator--
This is an example of 
``%s font-variant:small-caps%application
`` of small caps%% to part of a sentence.

This is an example of application of small caps to part of a sentence.

--

Note that the scope of span decorators is closed with two percent signs ("%%").

Simplewiki also allows classes and style-rules (as properties) to be extended with custom behaviours. An example is the newwin class commonly used to get links to open in new windows (like the above example %l newwin%[[http://simplewiki.org|Simplewiki]]), or the footnote span decorator (%s footnote%This is a footnote%%).

For details, read about Simplewiki decorators, and active classes and properties.

This obviously opens up a vast array of possibilities for decorating content. The catch is, the markup editor has to know or learn about the local CSS classes that are available (in Muster Wiki, mainly contained in the common/css/content.css file, and some in common/simplewiki/SimpleWiki.css, on the server), and generic css and html style-rules and attributes that are available (and when to use them). Markup editors with a good working knowledge of css and html will have an advantage here.

Muster Wiki Extensions of Simplewiki

Muster Wiki extends native Simplewiki markup in the following ways.

Symlinks

Symlinks ("symbolic links") are expanded within link and image markup to the location of the resource being requested.

Below is the list of Symlink expansions registered by Muster Wiki. base is the directory or subdirectory to which Muster Wiki was installed; common is the subdirectory containing Muster Wiki common code.

Symlink Expanded Notes
-- registered symlinks --
Uploads base + 'public/uploads/'
Local base
Images base + common + 'images/' system images and icons
Profiles base + 'public/profiles/'
Node base + dynamically resolved '+' fetches the node Title
'+|+' fetches both the Title and the Caption
specific record types
Document base + 'documents/'
Topic base + 'topics/'
Blog base + 'blogs/'
Post base + 'blogs/entry/'
Picture base + 'library/pictures/' '+' fetches the picture Title
'+|+' fetches both the Title and the Caption
Widget base + 'library/widgets/' '+' fetches the widget Title
'+|+' fetches both the Title and the Caption
File base + 'library/docfiles/'
Extract base + 'library/docextracts/'
Link base + 'library/links/'
Folder base + 'library/folders/'
Page base + 'pages/'
--

The specific record type symlinks can be used for link markup, or in the case of Picture and Widget, they can also be used for image markup.

Examples:

[[Node:<link>| + | + ]] ``` links to any record type
[[Document:<link>|My Document]] ```links to document
{{Picture:<link>`medium|+|+}} ``` displays picture
{{Widget:<link>|+|+}} ``` displays widget
[[Picture:<link>|+|+]] ```links to picture record
[[Widget:<link>|+|+]] ``` links to widget record

<link> is the record number. The text value after the backtick ("`") for Picture is the version of the picture to display. Choices are: small, smaller, smallest, medium, large, larger, largest, thumbnail, or original.

Class behaviours

Also registered by Muster Wiki are a few class behaviours:

  • for images: lframe, rframe, frame (these put frames - left, right, full-width - around images, with titles etc., like %i lframe%{{Picture:...)
  • for blockdef: condition, notcondition (options are true, false, loggedin - logical fail causes the block to be removed, like (:div condition:false:)...). This is useful for hiding blocks of markup.

See also Simplewiki native active classes.

Level 3: Declarations

For more complex layouts, for example requiring tables within table cells, simplwiki provides block declarations for basic blocks (div, blockquote), tables, and lists. These declarations can be nested by way of matching indentation:

-- nested blocks--
(:div background-color:green padding:10px:)
  (:div background-color:red:)
     |:p nop:|inner
  (:divend:)
(:divend:)
inner
--

Decoration arguments are placed in the leading tags of the declarations, instead of separate decorators. (The |:p nop:| prevents paragraph html markup from being formed around the word "inner".)

Level 4: Embedded HTML

If all else fails, authors can write html inside preformatted blocks marked as html:

block:

|:pre html:|{{{ 

html

}}}

inline:

%c html%{{{ html }}}