mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-12-25 01:20:30 +00:00
A self-contained JavaScript wiki for the browser, Node.js, AWS Lambda etc.
e8a93fa56b
To handle external links correctly, and URI encode internal links |
||
---|---|---|
docs | ||
js | ||
node_modules | ||
parsers | ||
test | ||
tiddlywiki5 | ||
.gitignore | ||
copyright.txt | ||
readme.md | ||
test.sh | ||
tiddlywiki.js | ||
tw5.sh | ||
upload.sh |
Welcome to TiddlyWiki5
Welcome to TiddlyWiki5, a reboot of the venerable, reusable non-linear personal web notebook first released in 2004. It is a complete interactive wiki that can run from a single HTML file or as a powerful
node.js
application.TiddlyWiki is based on the idea of making information more useful by modelling it in the smallest meaningful semantic units, referred to as "tiddlers". Structure comes from links, tags, and stories (sequences of tiddlers). Tiddlers use a wikitext notation that concisely represents a wide range of text formatting and hypertext features.
TiddlyWiki has earned an enduring role as a tool that people love using for its rich, interactive interface to manipulate complex data with structure that doesn't easily fit into conventional tools like spreadsheets or wordprocessors. Because people can use it without needing any complicated server infrastructure, and because it is open source, it has bought unprecedented freedom to people to keep their precious information under their own control. TiddlyWiki was originally created by JeremyRuston and is now a thriving open source project with a busy Community of independent developers.
TiddlyWiki5 is currently in early beta, which is to say that it is useful but incomplete. You can get involved in the development on GitHub and the discussions on Google Groups:
https://github.com/Jermolene/TiddlyWiki5
http://groups.google.com/group/TiddlyWikiDev
Usage
TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on RecipeFiles, TiddlerFiles and TiddlyWikiFiles.
Usage:
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. The following options are available:
This example cooks a TiddlyWiki from a recipe:
This example ginsus a TiddlyWiki into its constituent tiddlers:
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. 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 |
--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:
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.
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.Tiddlers
Tiddlers are a 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
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
) - JavaScript (
text/javascript
) - CSS (
text/css
) - JSON (
application/json
) - Recipe (
text/x-tiddlywiki-recipe
)
Compiling and Rendering
When the text of a tiddler is requested in a different format than its native type, TiddlyWiki5 compiles a JavaScript function that generates the new format from the text of the tiddler.
So, a simple tiddler in
application/x-tiddlywiki
format might read:Hello WorldThe function to render it to
text/html
might look like this:function() { return "<p>Hello World</p>"; }
The function can also include calls to the store to incorporate the values of other tiddlers. Consider this tiddler, called
HelloThere
:Hello <<tiddler Who>>And this one called
Who
:WorldThe function to generate
HelloThere
in text/html
might be:function() { return ["<p>","Hello ", getTiddlerText("Who","text/html"), "</p>"].join(""); }
Now, the return value of this function can be cached until a tiddler in the dependency chain changes. The function itself can be cached until the tiddler itself changes, or a macro that it uses changes.
The dependency chain is calculated when a tiddler is parsed. Every tiddler that is directly referenced is accumulated (until the point at which it is concluded that it is simpler to mark the tiddler as being dependent on any other tiddler changing).
Evaluated macro parameters are parsed and can be checked for safeness, and then included in the compiled code. For example,
Hello <<echo {{2+2}}>>Compiles to:
function() { return ["Hello ",(function(){ return 2+2; })().toString()].join(""); }
The compilation process has several steps:
- First, the parse tree is used to generate a JavaScript tree
- The JavaScript tree is scanned to determine the tiddlers on which this one depends
- Finally, executable JavaScript text is generated by walking the JavaScript tree
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 param1: Parameter value param2: value "unnamed parameter" param4: (( A multiline parameter that can go on for as long as it likes and contain linebreaks. )) >>
This
readme
file was automatically generated by TiddlyWiki5