This page is part of a static HTML representation of the TiddlyWiki at http://tiddlywiki.com/

TiddlyWikiFolders

6 days ago

As well as traditional single file wikis, TiddlyWiki on Node.js supports wikis that are stored as a folder of individual tiddler files.

Wiki folder files and folders

Wiki folders can contain the following files and folders:

  • tiddlywiki.info - JSON file containing metadata for the wiki
  • \tiddlers - folder containing tiddler files comprising the wiki
  • \plugins - folder containing plugin folders to be included in the wiki

Only the tiddlywiki.info file is required, the tiddlers and plugins folders are optional. Any files and folders not listed above are ignored.

Content of tiddlywiki.info file

The tiddlywiki.info file in a wiki folder contains a JSON object comprising the following fields:

  • plugins - an array of plugin names to be included in the wiki
  • themes - an array of theme names to be included in the wiki
  • languages - an array of language names to be included in the wiki
  • includeWikis - an array of relative paths to external wiki folders to be included in the wiki
  • build - a hashmap of named build targets, each defined by an array of command tokens (see BuildCommand)
  • config - an optional hashmap of configuration options (see below)

Note that the build targets of included wikis are merged if a target of that name isn't defined in the current tiddlywiki.info file.

Configuration options include:

  • default-tiddler-location - a string path to the default location for the filesystem adaptor to save new tiddlers (resolved relative to the wiki folder)
  • retain-original-tiddler-path - If true, the server will generate a tiddler $:/config/OriginalTiddlerPaths containing the original file paths of each tiddler in the wiki

For example:

{
	"plugins": [
		"tiddlywiki/tiddlyweb",
		"tiddlywiki/filesystem"
	],
	"includeWikis": [
		"../tw5.com"
	],
	"build": {
		"index": [
			"--rendertiddler","$:/core/save/all","index.html","text/plain"],
		"favicon": [
			"--savetiddler","$:/favicon.ico","favicon.ico",
			"--savetiddler","$:/green_favicon.ico","static/favicon.ico"]
	},
	"config": {
		"retain-original-tiddler-path": true	
	}
}

Content of tiddlers folder

All the TiddlerFiles in the tiddlers folder are read into the wiki at startup. Sub-folders are scanned recursively for TiddlerFiles.

Sub-folders within the tiddlers folder can also be given a tiddlywiki.files JSON file that overrides the default processing for that folder. The file format is illustrated with this example from the D3 plugin:

{
	"tiddlers": [
		{
			"file": "d3.min.js",
			"fields": {
				"type": "application/javascript",
				"title": "$:/plugins/tiddlywiki/d3/d3.js",
				"module-type": "library"
			},
			"prefix": "var d3;if($tw.browser){\n",
			"suffix": "}\nexports.d3 = d3;\n"
		},
		{
			"file": "cloud/d3.layout.cloud.js",
			"fields": {
				"type": "application/javascript",
				"title": "$:/plugins/tiddlywiki/d3/d3.layout.cloud.js",
				"module-type": "library"
			}
		}
	]
}

The JSON data consists of an object with a tiddlers property that contains an array of information about each tiddler to be loaded into the wiki. That information consists of:

  • file: the relative or absolute path to the file to include
  • fields: an object containing fields that override any provided in the tiddler file
  • prefix & suffix: (optional) specify strings to be prefixed and suffixed to the tiddler file text content