TiddlyWiki5/editions/tw5.com/tiddlers/concepts/TiddlyWikiFolders.tid

created: 201308252142
creator: JeremyRuston
modified: 201308300920
modifier: JeremyRuston
tags: dev
title: TiddlyWikiFolders

As well as traditional single file wikis, TiddlyWiki5 [[under node.js|TiddlyWiki5 Node Edition]] 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|PluginMechanism]] 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
* ''doNotSave'' - an array of tiddler titles that should not be saved by the FileSystemAdaptorPlugin
* ''includeWikis'' - an array of relative paths to external wiki folders to be included in the wiki

For example:

```
{
  "plugins": [
    "tiddlywiki/tiddlyweb",
    "tiddlywiki/filesystem"
  ],
  "doNotSave": [
    "$:/StoryList",
    "$:/HistoryList",
    "$:/status/IsLoggedIn",
    "$:/status/UserName"
  ],
  "includeWikis": [
    "../tw5.com"
  ]
}
```

!! 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