mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-12-28 02:50:27 +00:00
Docs updates
This commit is contained in:
Jeremy Ruston
parent
ed87061897
commit
19d8216b71
@ -1,4 +1,4 @@
|
||||
<h1>Welcome to <span data-tw-macro='link'><a href='TiddlyWiki5' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span></h1><div data-tw-macro='tiddler'>Welcome to <span data-tw-macro='link'><a href='TiddlyWiki5' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span>, an interactive wiki written in <span data-tw-macro='link'><a href='JavaScript' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span> to run in the browser or under node.js. It is a reboot of <span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> (<span data-tw-macro='link'><a href='http://www.tiddlywiki.com/' class='tw-tiddlylink tw-tiddlylink-external'>http://www.tiddlywiki.com/</a></span>), the now venerable, reusable non-linear personal web notebook first released in 2004.<br /><br /><span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> 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). <span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> provides a rich, useful and enjoyable interactive interface for manipulating tiddlers.<br /><br /><span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> has earned an enduring place as a tool that people <span data-tw-macro='link'><a href='Raves' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>love using</a></span> for its rich, interactive interface to <span data-tw-macro='link'><a href='TiddlyWikiConcepts' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>manipulate complex data</a></span> 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 <span data-tw-macro='link'><a href='OpenSourceLicense' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>open source</a></span>, it has bought unprecedented freedom to people to keep their precious information under their own control. <span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> was originally created by <span data-tw-macro='link'><a href='JeremyRuston' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JeremyRuston</a></span> and is now a thriving <span data-tw-macro='link'><a href='OpenSourceLicense' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>open source</a></span> project with a busy <span data-tw-macro='link'><a href='Community' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>Community</a></span> of independent developers.<br /></div><br /><h1>Usage</h1><div data-tw-macro='tiddler'><span data-tw-macro='link'><a href='TiddlyWiki5' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span> can be used on the command line to perform an extensive set of operations based on <span data-tw-macro='link'><a href='RecipeFiles' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>RecipeFiles</a></span>, <span data-tw-macro='link'><a href='TiddlerFiles' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>TiddlerFiles</a></span> and <span data-tw-macro='link'><a href='TiddlyWikiFiles' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWikiFiles</a></span>.<br /><br />Usage:<br /><code>
|
||||
<h1>Welcome to <span data-tw-macro='link'><a href='TiddlyWiki5' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span></h1><div data-tw-macro='tiddler'>Welcome to <span data-tw-macro='link'><a href='TiddlyWiki5' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span>, an interactive wiki written in <span data-tw-macro='link'><a href='JavaScript' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span> to run in the browser or under node.js. It is a reboot of <span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> (<span data-tw-macro='link'><a href='http://www.tiddlywiki.com/' class='tw-tiddlylink tw-tiddlylink-external'>http://www.tiddlywiki.com/</a></span>), the now venerable, reusable non-linear personal web notebook first released in 2004.<br /><br /><span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> 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.<br /><br /><span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> has earned an enduring place as a tool that people <span data-tw-macro='link'><a href='Raves' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>love using</a></span> for its rich, interactive interface to <span data-tw-macro='link'><a href='TiddlyWikiConcepts' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>manipulate complex data</a></span> 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 <span data-tw-macro='link'><a href='OpenSourceLicense' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>open source</a></span>, it has bought unprecedented freedom to people to keep their precious information under their own control. <span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> was originally created by <span data-tw-macro='link'><a href='JeremyRuston' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JeremyRuston</a></span> and is now a thriving <span data-tw-macro='link'><a href='OpenSourceLicense' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>open source</a></span> project with a busy <span data-tw-macro='link'><a href='Community' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>Community</a></span> of independent developers.<br /></div><br /><h1>Usage</h1><div data-tw-macro='tiddler'><span data-tw-macro='link'><a href='TiddlyWiki5' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span> can be used on the command line to perform an extensive set of operations based on <span data-tw-macro='link'><a href='RecipeFiles' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>RecipeFiles</a></span>, <span data-tw-macro='link'><a href='TiddlerFiles' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>TiddlerFiles</a></span> and <span data-tw-macro='link'><a href='TiddlyWikiFiles' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWikiFiles</a></span>.<br /><br />Usage:<br /><code>
|
||||
node tiddlywiki.js <options>
|
||||
</code><br />The command line options are processed sequentially from left to right. Processing pauses during long operations, like loading a <span data-tw-macro='link'><a href='RecipeFiles' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>recipe file</a></span> and all the subrecipes and <span data-tw-macro='link'><a href='TiddlerFiles' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>tiddlers</a></span> that it references. The following options are available:<br /><table class="twtable"><tbody><tr class="evenRow"><td align="left"><code>--recipe <filepath></code></td><td align="left">Loads a specfied <code>.recipe</code> file</td></tr><tr class="oddRow"><td align="left"><code>--load <filepath></code></td><td align="left">Load additional tiddlers from 2.x.x <span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> files (<code>.html</code>), <code>.tiddler</code>, <code>.tid</code>, <code>.json</code> or other files</td></tr><tr class="evenRow"><td align="left"><code>--savewiki <dirpath></code></td><td align="left">Saves all the loaded tiddlers as a single file <span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> called <code>index.html</code> and an RSS feed called <code>index.xml</code> in a new directory of the specified name</td></tr><tr class="oddRow"><td align="left"><code>--savetiddler <title> <filename> [<type>]</code></td><td align="left">Save an individual tiddler as a specified MIME type, defaults to <code>text/html</code></td></tr><tr class="evenRow"><td align="left"><code>--savetiddlers <outdir></code></td><td align="left">Saves all the loaded tiddlers as <code>.tid</code> files in the specified directory</td></tr><tr class="oddRow"><td align="left"><code>--servewiki <port></code></td><td align="left">Serve the cooked <span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> over HTTP at <code>/</code></td></tr><tr class="evenRow"><td align="left"><code>--servetiddlers <port></code></td><td align="left">Serve individual tiddlers over HTTP at <code>/tiddlertitle</code></td></tr><tr class="oddRow"><td align="left"><code>--wikitest <dir></code></td><td align="left">Run wikification tests against the tiddlers in the given directory</td></tr><tr class="evenRow"><td align="left"><code>--dumpstore</code></td><td align="left">Dump the <span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> store in JSON format</td></tr><tr class="oddRow"><td align="left"><code>--dumprecipe</code></td><td align="left">Dump the current recipe in JSON format</td></tr><tr class="evenRow"><td align="left"><code>--verbose</code></td><td align="left">verbose output, useful for debugging</td></tr></tbody></table><h2> Examples</h2>This example loads the tiddlers from a <span data-tw-macro='link'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> HTML file and makes them available over HTTP:<br /><code>
|
||||
node tiddlywiki.js --load mywiki.html --servewiki 127.0.0.1:8000
|
||||
|
||||
@ -3,6 +3,6 @@ modifier: JeremyRuston
|
||||
|
||||
Welcome to TiddlyWiki5, an interactive wiki written in JavaScript to run in the browser or under node.js. It is a reboot of TiddlyWiki (http://www.tiddlywiki.com/), the now venerable, reusable non-linear personal web notebook first released in 2004.
|
||||
|
||||
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). TiddlyWiki provides a rich, useful and enjoyable interactive interface for manipulating tiddlers.
|
||||
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 place as a tool that people [[love using|Raves]] for its rich, interactive interface to [[manipulate complex data|TiddlyWikiConcepts]] 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|OpenSourceLicense]], 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|OpenSourceLicense]] project with a busy [[Community]] of independent developers.
|
||||
|
||||
@ -1,41 +1,46 @@
|
||||
title: TiddlerFiles
|
||||
modifier: JeremyRuston
|
||||
|
||||
Tiddlers can be stored in text files in several different formats. Files containing single tiddlers can also have an auxiliary {{{.meta}}} file formatted as a sequence of name:value pairs:
|
||||
{{{
|
||||
Tiddlers can be stored in text files in several different formats. Files containing single tiddlers can also have an auxiliary `.meta` file formatted as a sequence of name:value pairs:
|
||||
`
|
||||
title: TheTitle
|
||||
modifier: someone
|
||||
}}}
|
||||
`
|
||||
!! ~TiddlyWeb-style .tid files
|
||||
|
||||
These files consist of a sequence of lines containing name:value pairs, a blank line and then the text of the tiddler. For example:
|
||||
{{{
|
||||
`
|
||||
title: MyTiddler
|
||||
modifier: Jeremy
|
||||
|
||||
This is the text of my tiddler.
|
||||
}}}
|
||||
!! TiddlyWiki {{{<DIV>}}} .tiddler files
|
||||
`
|
||||
//The MIME type `application/x-tiddler` is used internally for these files//
|
||||
!! TiddlyWiki `<DIV>` .tiddler files
|
||||
|
||||
Modern {{{*.tiddler}}} files look like this:
|
||||
{{{
|
||||
Modern `*.tiddler` files look like this:
|
||||
`
|
||||
<div title="AnotherExampleStyleSheet" modifier="blaine" created="201102111106" modified="201102111310" tags="examples" creator="psd">
|
||||
<pre>Note that there is an embedded <pre> tag, and line feeds are not escaped.
|
||||
|
||||
And, weirdly, there is no HTML encoding of the body.</pre>
|
||||
</div>
|
||||
}}}
|
||||
These {{{*.tiddler}}} files are therefore not quite the same as the tiddlers found inside a TiddlyWiki HTML file, where the body is HTML encoded in the expected way.
|
||||
`
|
||||
These `*.tiddler` files are therefore not quite the same as the tiddlers found inside a TiddlyWiki HTML file, where the body is HTML encoded in the expected way.
|
||||
|
||||
Older {{{*.tiddler}}} files more closely matched the store format used by TiddlyWiki at the time:
|
||||
{{{
|
||||
Older `*.tiddler` files more closely matched the store format used by TiddlyWiki at the time:
|
||||
`
|
||||
<div tiddler="AnotherExampleStyleSheet" modifier="JeremyRuston" modified="200508181432" created="200508181432" tags="examples">This is an old-school .tiddler file, without an embedded <pre> tag.\nNote how the body is "HTML encoded" and new lines are escaped to \\n</div>
|
||||
}}}
|
||||
`
|
||||
//The MIME type `application/x-tiddler-html-div` is used internally for these files//
|
||||
!! ~TiddlyWeb-style JSON files
|
||||
|
||||
These files are a straightforward array of hashmaps of name:value fields. Currently only these known fields are processed: {{{title}}}, {{{text}}}, {{{created}}}, {{{creator}}}, {{{modified}}}, {{{modifier}}}, {{{type}}} and {{{tags}}}.
|
||||
These files are a straightforward array of hashmaps of name:value fields. Currently only these known fields are processed: `title`, `text`, `created`, `creator`, `modified`, `modifier`, `type` and `tags`.
|
||||
|
||||
|
||||
//The MIME type `application/json` is used internally for these files//
|
||||
!! TiddlyWiki HTML files
|
||||
|
||||
TiddlyWiki HTML files contain a collection of tiddlers encoded in {{{<DIV>}}} format.
|
||||
TiddlyWiki HTML files contain a collection of tiddlers encoded in `<DIV>` format.
|
||||
|
||||
//The MIME type `application/x-tiddlywiki` is used internally for these files//
|
||||
|
||||
@ -3,26 +3,10 @@ modifier: JeremyRuston
|
||||
|
||||
!! 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 use a special wikitext notation that concisely represents text formatting and hypertext features.
|
||||
|
||||
|
||||
|
||||
<<tiddler [[High Level Architecture.svg]]>>
|
||||
|
||||
!! Content Types
|
||||
|
||||
TiddlyWiki uses MIME types to indicate how the text of tiddlers should be interpreted. It uses standard MIME types such as {{{text/plain}}} and {{{text/html}}}, as well as these non-standard types for TiddlyWiki-specific formats:
|
||||
|
||||
* {{{text/x-tiddlywiki}}}: TiddlyWiki-format wiki text
|
||||
* {{{application/x-tiddlywiki}}}: A TiddlyWiki HTML file containing tiddlers
|
||||
* {{{application/x-tiddler}}}: A tiddler in TiddlyWeb-style tiddler file format
|
||||
* {{{application/x-tiddler-html-div}}}: A tiddler in TiddlyWiki {{{<div>}}} format
|
||||
In some situations //parameterised MIME types// are used to allow parameters to be specified for the conversion. For example, a tiddler can be rendered to an image of a particular size:
|
||||
{{{
|
||||
image/png({width:500})
|
||||
}}}
|
||||
!! Tiddlers
|
||||
|
||||
Tiddlers are a dictionary of name:value pairs called fields.
|
||||
@ -31,9 +15,9 @@ The only field that is required is the {{{title}}} field, but useful tiddlers al
|
||||
|
||||
Values can be a string, an array of strings, or a JavaScript {{{Date}}} object. Hardcoded in the system is the knowledge that the `tags` field is a string array, and that the `modified` and `created` fields are dates. All other fields are strings.
|
||||
|
||||
The {{{type}}} field identifies the representation of the tiddler text with a raw, unparameterised, MIME type.
|
||||
The {{{type}}} field identifies the representation of the tiddler text with a MIME type.
|
||||
|
||||
!! WikiStore
|
||||
!! ~WikiStore
|
||||
|
||||
Groups of uniquely titled tiddlers are contained in WikiStore objects.
|
||||
|
||||
@ -41,11 +25,11 @@ The WikiStore also manages the plugin modules used for macros, and operations li
|
||||
|
||||
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
|
||||
!! ~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 matching event handlers.
|
||||
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 matching event handlers.
|
||||
|
||||
!! Parsing
|
||||
|
||||
@ -56,7 +40,7 @@ TiddlyWiki parses the content of tiddlers to build an internal tree representati
|
||||
* 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 text changes.
|
||||
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}}})
|
||||
@ -65,16 +49,6 @@ TiddlyWiki5 uses multiple parsers:
|
||||
* JSON ({{{application/json}}})
|
||||
* Recipe ({{{text/x-tiddlywiki-recipe}}})
|
||||
|
||||
The parsers support several useful conversions:
|
||||
* Converting wikitext to HTML
|
||||
* Converting Less-style CSS to real CSS, using tiddler references for variable names
|
||||
* Whitelisting JavaScript for safe execution of untrusted code
|
||||
|
||||
In the future the architecture might also support:
|
||||
* Converting JavaScript procedural images to PNGs, using a synthetic graphics context mocking the canvas
|
||||
* Converting images from one size or format to another
|
||||
* Minifying JavaScript
|
||||
|
||||
!! 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.
|
||||
@ -107,14 +81,9 @@ function() {
|
||||
|
||||
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 compiled. 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).
|
||||
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).
|
||||
|
||||
The render function is invoked with `this` pointing to a tiddler object. Parameters to the render function include:
|
||||
* ''getTiddler(title)'' - a function to retrieve a specified tiddler
|
||||
* ''renderTiddler(title,type,params)'' - a function to render a tiddler to a specified type
|
||||
* ''forEachTiddler(sortField,excludeTag,callback)'' - a function to enumerate all tiddlers
|
||||
|
||||
Evaluated macro parameters would be parsed and checked for safeness, and then included in the compiled code. For example,
|
||||
Evaluated macro parameters are parsed and can bechecked for safeness, and then included in the compiled code. For example,
|
||||
{{{
|
||||
Hello <<echo {{2+2}}>>
|
||||
}}}
|
||||
|
||||
8
tiddlywiki5/tiddlers/TiddlyWikiInternals.tid
Normal file
8
tiddlywiki5/tiddlers/TiddlyWikiInternals.tid
Normal file
@ -0,0 +1,8 @@
|
||||
title: TiddlyWikiInternals
|
||||
|
||||
This diagram gives a birds eye view of the JavaScript files making up TiddlyWiki5:
|
||||
|
||||
<<tiddler [[High Level Architecture.svg]]>>
|
||||
|
||||
See TiddlyWikiArchitecture for an overview of the architecture of the system.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user