External images in TiddlyWiki are tiddlers that point to the URI of an image, rather than embedding the full image data. They can perform better than embedded images, particularly with large numbers or sizes of images. However, using them breaks the single file pattern of TiddlyWiki.

External images are used in the browser. They can be created by the Node.js configuration when it builds a TiddlyWiki, or they can be created manually within the browser.

What is an External Image

An external image is an ordinary image tiddler that has a _canonical_uri field containing the URI of the image. The URI can be absolute or relative to the HTML document. If the canonical URI is provided then the text field of the tiddler is ignored and so should be omitted.

Manually Creating External Images

To manually create an external image just create the tiddler with the appropriate image content type, and add a _canonical_uri field with a URI pointing to the actual image location.

IMPORTANT: Double-check your spelling. _canonical_uri is spelled URI, not URL.

Creating external images under Node.js

The following steps are used to create a static HTML file version of a wiki accompanied by an images folder containing the referenced external images:

1. Create image tiddlers in your TiddlyWikiFolders in the usual way
2. Save the images as separate files (by convention, in a subfolder named /images)
3. Externalise the image tiddlers by giving them a _canonical_uri field
4. Save the main HTML file

Note the image files must be saved before they are externalised. Externalising them destroys the text field within the in-memory copy of the wiki store, meaning that attempts to save them will fail.

External Image Configuration

For an example create an externalimages build target in a tiddlywiki.info file:

"build": {
	"externalimages": [
		--save [is[image]] images
		--setfield [is[image]] _canonical_uri $:/core/templates/canonical-uri-external-image text/plain
		--setfield [is[image]] text "" text/plain
		--render $:/core/save/all externalimages.html text/plain
	]
}

Externalising Image Tiddlers

The following --save command (see SaveCommand) can be used to save the images of a wiki into an images subfolder:

--save [is[image]] images

Two --setfield commands are used: the first sets the _canonical_uri field to a URI derived from the title of the tiddler, and the second clears the text field.

--setfield [is[image]] _canonical_uri $:/core/templates/canonical-uri-external-image text/plain
--setfield [is[image]] text "" text/plain

The template tiddler $:/core/templates/canonical-uri-external-image contains:

<!--

This template is used to assign the ''_canonical_uri'' field to external images.

Change the `./images/` part to a different base URI. The URI can be relative or absolute.

-->
./images/<$view field="title" format="doubleurlencoded"/>

Note that these operations modify the tiddlers in the wiki store and so may affect the operation of subsequent commands.

Node.js Command to Build External Images

The following command will create external images in the myWiki/output folder.

tiddlywiki myWiki --build externalimages

On Windows the following command will create external images that are part of the tw5.com edition. The files will be created in the output directory.

tiddlywiki .\editions\tw5.com --build index

Using External Images

You can't edit an external image directly in the browser except by changing the URI field to point to a different image.