TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on
RecipeFiles,
TiddlerFiles and
TiddlyWikiFiles.
Usage:
node tiddlywiki.js <options>
-The command line options are processed sequentially from left to right. Processing pauses during long operations, like loading a
recipe file and all the subrecipes and
tiddlers that it references, and then resumes with the next command line option in sequence. The following options are available:
--recipe <filepath> | Loads a specfied .recipe file |
--load <filepath> | Load additional tiddlers from 2.x.x TiddlyWiki files (.html), .tiddler, .tid, .json or other files |
--savewiki <dirpath> | Saves all the loaded tiddlers as a single file TiddlyWiki called index.html and an RSS feed called index.xml in a new directory of the specified name |
--savetiddler <title> <filename> [<type>] | Save an individual tiddler as a specified MIME type, defaults to text/html |
--savetiddlers <outdir> | Saves all the loaded tiddlers as .tid files in the specified directory |
--savehtml <outdir> | Saves all the loaded tiddlers as static, unstyled .html files in the specified directory |
--servewiki <port> | Serve the cooked TiddlyWiki over HTTP at / |
--servetiddlers <port> | Serve individual tiddlers over HTTP at /tiddlertitle |
--wikitest <dir> | Run wikification tests against the tiddlers in the given directory |
--dumpstore | Dump the TiddlyWiki store in JSON format |
--dumprecipe | Dump the current recipe in JSON format |
--verbose | verbose output, useful for debugging |
Examples
This example loads the tiddlers from a
TiddlyWiki HTML file and makes them available over HTTP:
+The command line options are processed sequentially from left to right. Processing pauses during long operations, like loading a
recipe file and all the subrecipes and
tiddlers that it references, and then resumes with the next command line option in sequence. The following options are available:
--recipe <filepath> | Loads a specfied .recipe file |
--load <filepath> | Load additional tiddlers from 2.x.x TiddlyWiki files (.html), .tiddler, .tid, .json or other files |
--savewiki <dirpath> | Saves all the loaded tiddlers as a single file TiddlyWiki called index.html and an RSS feed called index.xml in a new directory of the specified name |
--savetiddler <title> <filename> [<type>] | Save an individual tiddler as a specified MIME type, defaults to text/html |
--savetiddlers <outdir> | Saves all the loaded tiddlers as .tid files in the specified directory |
--savehtml <outdir> | Saves all the loaded tiddlers as static, unstyled .html files in the specified directory |
--servewiki <port> | Serve the cooked TiddlyWiki over HTTP at / |
--servetiddlers <port> | Serve individual tiddlers over HTTP at /tiddlertitle |
--wikitest <dir> [save] | Run wikification tests against the tiddlers in the given directory. Include the save flag to save the test result files as the new targets |
--dumpstore | Dump the TiddlyWiki store in JSON format |
--dumprecipe | Dump the current recipe in JSON format |
--verbose | verbose output, useful for debugging |
Examples
This example loads the tiddlers from a
TiddlyWiki HTML file and makes them available over HTTP:
node tiddlywiki.js --load mywiki.html --servewiki 127.0.0.1:8000
This example cooks a
TiddlyWiki from a recipe:
node tiddlywiki.js --recipe tiddlywiki.com/index.recipe --savewiki tmp/
This example ginsus a
TiddlyWiki into its constituent tiddlers:
node tiddlywiki.js --load mywiki.html --savetiddlers tmp/tiddlers
- Notes
--servewiki and
--servertiddlers are for different purposes and should not be used together. The former is for
TiddlyWiki core developers who want to be able to edit the
TiddlyWiki source files in a text editor and view the results in the browser by clicking refresh; it is slow because it reloads all the
TiddlyWiki JavaScript files each time the page is loaded. The latter is for experimenting with the new wikification engine.
--wikitest looks for
*.tid files in the specified folder. It then wikifies the tiddlers to both "text/plain" and "text/html" format and checks the results against the content of the
*.html and
*.txt files in the same directory.
Testing
test.sh contains a simple test script that cooks the main tiddlywiki.com recipe and compares it with the results of the old build process (ie, running cook.rb and then opening the file in a browser and performing a 'save changes' operation). It also runs a series of wikifications tests that work off the data in
test/wikitests/.
Architecture
Overview
The heart of
TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated MIME type, the engine can produce a rendering of the tiddler in a new MIME type. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents.
The most important transformations are from
text/x-tiddlywiki wikitext into
text/html or
text/plain but the engine is used throughout the system for other transformations, such as converting images for display in HTML, sanitising fragments of
JavaScript, and processing CSS.
The key feature of wikitext is the ability to include one tiddler within another (usually referred to as
transclusion). For example, one could have a tiddler called
Disclaimer that contains the boilerplate of a legal disclaimer, and then include it within lots of different tiddlers with the macro call
<<tiddler Disclaimer>>. This simple feature brings great power in terms of encapsulating and reusing content, and evolving a clean, usable implementation architecture to support it efficiently is a key objective of the
TiddlyWiki5 design.
It turns out that the transclusion capability combined with the selective refreshing mechanism provides a good foundation for building
TiddlyWiki's user interface itself. Consider, for example, the
StoryMacro in its simplest form:
<<story story:MyStoryTiddler>>
+
Notes
--servewiki and --servertiddlers are for different purposes and should not be used together. The former is for TiddlyWiki core developers who want to be able to edit the TiddlyWiki source files in a text editor and view the results in the browser by clicking refresh; it is slow because it reloads all the TiddlyWiki JavaScript files each time the page is loaded. The latter is for experimenting with the new wikification engine.
--wikitest looks for *.tid files in the specified folder. It then wikifies the tiddlers to both "text/plain" and "text/html" format and checks the results against the content of the *.html and *.txt files in the same directory.
Overview
The heart of
TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated MIME type, the engine can produce a rendering of the tiddler in a new MIME type. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents.
The most important transformations are from
text/x-tiddlywiki wikitext into
text/html or
text/plain but the engine is used throughout the system for other transformations, such as converting images for display in HTML, sanitising fragments of
JavaScript, and processing CSS.
The key feature of wikitext is the ability to include one tiddler within another (usually referred to as
transclusion). For example, one could have a tiddler called
Disclaimer that contains the boilerplate of a legal disclaimer, and then include it within lots of different tiddlers with the macro call
<<tiddler Disclaimer>>. This simple feature brings great power in terms of encapsulating and reusing content, and evolving a clean, usable implementation architecture to support it efficiently is a key objective of the
TiddlyWiki5 design.
It turns out that the transclusion capability combined with the selective refreshing mechanism provides a good foundation for building
TiddlyWiki's user interface itself. Consider, for example, the
StoryMacro in its simplest form:
<<story story:MyStoryTiddler>>
The story macro looks for a list of tiddler titles in the tiddler
MyStoryTiddler, and displays them in sequence. The subtle part is that subsequently, if
MyStoryTiddler changes, the
<<story>> macro is selectively re-rendered. So, to navigate to a new tiddler, code merely needs to add the name of the tiddler and a line break to the top of
MyStoryTiddler:
var storyTiddler = store.getTiddler("MyStoryTiddler");
store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + "\n" + storyTiddler.text}));
The mechanisms that allow all of this to work are fairly intricate. The sections below progressively build the key architectural concepts of
TiddlyWiki5 in a way that should provide a good basis for exploring the code directly.
Tiddlers
Tiddlers are an immutable dictionary of name:value pairs called fields.
The only field that is required is the
title field, but useful tiddlers also have a
text field, and some or all of the standard fields
modified,
modifier,
created,
creator,
tags and
type.
Hardcoded in the system is the knowledge that the
tags field is a string array, and that the
modified and
created fields are
JavaScript Date objects. All other fields are strings.
The
type field identifies the representation of the tiddler text with a MIME type.
WikiStore
Groups of uniquely titled tiddlers are contained in
WikiStore objects.
The
WikiStore also manages the plugin modules used for macros, and operations like serializing, deserializing, parsing and rendering tiddlers.
Each
WikiStore is connected to another shadow store that is used to provide default content. Under usual circumstances, when an attempt is made to retrieve a tiddler that doesn't exist in the store, the search continues into its shadow store (and so on, if the shadow store itself has a shadow store).
WikiStore Events
Clients can register event handlers with the
WikiStore object. Event handlers can be registered to be triggered for modifications to any tiddler in the store, or with a filter to only be invoked when a particular tiddler or set of tiddlers changes.
Whenever a change is made to a tiddler, the wikistore registers a
nexttick handler (if it hasn't already done so). The
nexttick handler looks back at all the tiddler changes, and dispatches any matching event handlers.
Parsing and Rendering
TiddlyWiki parses the content of tiddlers to build an internal tree representation that is used for several purposes:
- Rendering a tiddler to other formats (e.g. converting wikitext to HTML)
- Detecting outgoing links from a tiddler, and from them...
- ...computing incoming links to a tiddler
- Detecting tiddlers that are orphans with no incoming links
- Detecting tiddlers that are referred to but missing
The parse tree is built when needed, and then cached by the
WikiStore until the tiddler changes.
TiddlyWiki5 uses multiple parsers:
- Wikitext (
text/x-tiddlywiki) in js/WikiTextParser.js - JavaScript (
text/javascript) in js/JavaScriptParser.js - Images (
image/png and image/jpg) in js/ImageParser.js - JSON (
application/json) in js/JSONParser.js
Additional parsers are planned:
- CSS (
text/css) - Recipe (
text/x-tiddlywiki-recipe)
One global instance of each parser is instantiated in
js/App.js and registered with the main
WikiStore object.
The parsers are all used the same way:
var parseTree = parser.parse(type,text)
The parameters to
rerender() are:
| Name | Description |
|---|
| node | A reference to the DOM node containing the rendering to be rerendered |
| changes | A hashmap of {title: "created|modified|deleted"} indicating which tiddlers have changed since the original rendering |
| tiddler | The tiddler providing the rendering context |
| store | The store to use for resolving references to other tiddlers |
| renderStep | See below |
Currently, the only macro that supports rerendering is the
<<story>> macro; all other macros are rerendered by calling the ordinary
render() method again. The reason that the
<<story>> macro goes to the trouble of having a
rerender() method is so that it can be carefully selective about not disturbing tiddlers in the DOM that aren't affected by the change. If there were, for instance, a video playing in one of the open tiddlers it would be reset to the beginning if the tiddler were rerendered.
Planned WikiText Features
It is proposed to extend the existing
TiddlyWiki WikiText syntax with the following extensions
- Addition of
**bold** character formatting - Addition of
`backtick for code` character formatting - Addition of WikiCreole-style forced line break, e.g.
force\\linebreak - Addition of WikiCreole-style headings, e.g.
==Heading - Addition of WikiCreole-style headings in tables, e.g.
|=|=table|=header| - Addition of white-listed HTML tags intermixed with wikitext
- Addition of WikiCreole-style pretty links, e.g.
[[description -> link]] - Addition of multiline macros, e.g.
<<myMacro
+
The parameters to
rerender() are:
| Name | Description |
|---|
| node | A reference to the DOM node containing the rendering to be rerendered |
| changes | A hashmap of {title: "created|modified|deleted"} indicating which tiddlers have changed since the original rendering |
| tiddler | The tiddler providing the rendering context |
| store | The store to use for resolving references to other tiddlers |
| renderStep | See below |
Currently, the only macro that supports rerendering is the
<<story>> macro; all other macros are rerendered by calling the ordinary
render() method again. The reason that the
<<story>> macro goes to the trouble of having a
rerender() method is so that it can be carefully selective about not disturbing tiddlers in the DOM that aren't affected by the change. If there were, for instance, a video playing in one of the open tiddlers it would be reset to the beginning if the tiddler were rerendered.