General Information
LibWiki provides facilities to easily build, display and navigate Wiki-like pages.
It provides convenient PageContainer and Navigator objects which together are used to push/pop pages and navigate forward/backward like in a typical browser. (Browser not included...) It was developed together with ApiBrowser as the content displaying framework.
The provided PageBuilder can construct structured pages from the following primitives with very little code:
- Header 1
- A single line header of a certain size and style (h1)
- Header 2
- A single line header of a certain size and style (h2)
- Paragraph
- A simple text paragraph
- Table of Contents
- A list of links arranged in a grid-like fashion
- Function Signature
- The function signatures and parameter/result types in a useful overview, parsed from the result of Inspect.Documentation
- Key-Value-Table
- The keys and values of a Lua table in a table layout.
If it is popular enough support for more primitives will be added. It recognizes some basic markup (besides Rift's HTML processing capabilities) for realizing hyperlinks between pages. To see it in action try out ApiBrowser where all the capabilities of LibWiki are used. You can also find a very extensive documentation of LibWiki inside ApiBrowser.
Markup
Here is a short explanation for the hyperlink markup:
The usual suspects for wiki link markups are either [[xxx]] or {{xxx}} but since both can appear in common Lua snippets ApiBrowser uses <<xxx>> instead as both << and >> are invalid Lua syntax. Most PageBuilder:Build* methods search the inputs for this markup text if HTML processing is enabled.
You have to escape < and > in normal text with < and >.
Remember the following rules:
- Due to limitations in Lua's regex patterns the colon after << must(!) be included otherwise the link is not recognized.
- Do not use the colon character ":" in module names (it's OK in paths).
- Do not use the pipe character "|" in either module or path names (this also breaks Rift's HTML parser, so seriously, don't do it).
- Link titles may contain HTML markup. In cases where the title ends with a ">" append a semicolon ";" to resolve the ambiguity (e.g. "
<<Path|<b>Bold Title</b>;>>"). The semicolon is not displayed.
Complete syntax
<<:path>>- Link to a page with the given path in the same module. The link text equals the path.
<<:path|title>>- Link to a page with the given path in the same module. The link text equals title.
<<module:path>>- Link to a page with the given path in the given module. The link text equals the path.
<<module:path|title>>- Link to a page with the given path in the given module. The link text equals title.
Commands
Some hyperlinks are not meant to simply navigate to a different page but instead exectue a command. This is implemented using module names in the link with special meaning. All these special module names begin with "#!" and cannot be used as ordinary module names.
Currently there is only the copy command:
#!copy- Display a small dialog with the given text in a preselected textfield so it can be copied to the clipboard by the user.
- The text to be copied cannot contain the pipe "|" character!
- Example:
<<#!copy:http://www.example.de|copy this>>