This is a stripped-down version of a single section of Grok TiddlyWiki, optimized for fast loading and readability by search engines. Some features are missing.

For the full Grok TiddlyWiki experience, please visit the wiki version of this page.

Images and Attachments

18th August 2021 at 12:23pm

So far, we've written an awful lot of formatted text. What about including images or other files in the wiki?

This is, perhaps unexpectedly, one of the more troublesome aspects of TiddlyWiki, which is why we've left it until now. Let's talk about how we do it and what concerns we'll have to think about.

Importing files

This part is slick. Want a file to be part of your TiddlyWiki? Just drag and drop it out of your computer's file manager onto the TiddlyWiki window. A banner will appear at the top of the screen that says “Drop here.” When you drop the file, a special tiddler called $:/Import will appear. Click Import, and a new tiddler is created containing the content. $:/Import will show a link to the newly added tiddler.

This works for text, images, PDFs, and even binary files (though this last option is usually a bad idea, as TiddlyWiki can lock up if you try to open the tiddler for a large binary file, and you won't be able to read it anyway). You can import multiple files at once by dragging multiple files; you'll have the chance to review and uncheck any that you don't want before you import.

You can also copy content between TiddlyWikis this way. For instance, if you wanted a copy of the Classifying Tags section in your wiki, you could simply grab that link and drag and drop it right onto your wiki window (this doesn't consistently work, however, if you don't have both wikis open in the same web browser – you may have to try another browser in some cases).

If it's easier than dragging and dropping, you can also click the Import button on the Tools tab of the sidebar to select a file to import. In particular, when using TiddlyDesktop with certain operating systems and browsers, it may be tricky to get drag-and-drop to work, but the Import button will almost always work fine.

Go ahead and import a file or two into your wiki, including at least one image so we can take a look at that below.

Putting images in your tiddlers

Once you have an image in your wiki, you probably want to know how to include it in a tiddler. Let's create a new tiddler called ImageTest for this purpose.

The easiest way to include it is to simply transclude it. So if the image tiddler is called image.png, use {{image.png}}.

For more control over the image, you can use a special link syntax, [img [image.png]] (notice the space before the second [ – this is not important yet, but is required when including attributes, as described in the next sentence). In between the img and the opening square bracket, you can include width=200 and/or height=200 attributes to size the image, replacing 200 with however many pixels you want to use for the image. It's also possible to use a macro or field transclusion to set the size, e.g.:

[img width={{MyFavoriteImageWidth}} [image.png]]

Putting PDFs in your tiddlers

Another common type of file to embed in your wiki is a PDF. You can't set the size a PDF displays at, but you can transclude a PDF tiddler, like {{mydocument.pdf}}, and a mini-embedded PDF viewer will appear at that point in the tiddler. Be aware this can slow down the loading of the tiddler since your browser has to load the entire PDF before it can finish displaying the tiddler, so be careful not to put it somewhere that might get loaded or re-loaded frequently, like on your wiki's front page or in the sidebar.

Directly adding images to your tiddlers

Above we discussed how importing images works when you import the image first and then create a tiddler that displays it. But often you'll be editing a tiddler and only then realize you need to import an image. In this case, you can drag and drop the image directly into the editor or paste it from the clipboard. In either case, a small popup will appear (you may need to scroll down to see it in some cases) offering to import the image. When you accept, it will both import the image and insert [img [image.png]] into the tiddler you're editing, where image.png is the name of the imported image tiddler.

Aside from this automatic insertion of appropriate wikitext markup, directly adding an image to a tiddler works exactly like importing it on its own and then referencing it from within a tiddler later.

The problem with TiddlyWiki attachments

Here's the essential problem with all this: in single-file TiddlyWikis, anything you attach to your wiki gets embedded in the file. That's no big deal if you only add a few small images or documents to your wiki, but if you start adding tens or dozens of large images, that file will balloon in size. And that's a big problem, because every time TiddlyWiki saves, it makes a new copy of the file for backup purposes. If your wiki is 100 MB, and you save your wiki just 20 times, you're now using 2 GB of space on your hard drive. Plus, it takes a long time to write a 100 MB file to your hard drive or load it into the browser, so performance will start to slow down.

You can reduce the number of backups saved by various means, but that only hides the problem for longer; eventually your wiki is still going to get really big.

(For the curious, text is so much smaller than images that serious difficulties are unlikely. You would have to write over 16 million average-length words of English, or 32,000 densely filled pages, to reach 100 MB of text. If you write 3 pages every day, it will still take you 30 years to write that much.)

Possible solutions

Using Node.js

If you're technical enough to know a little bit about running a web server, or just a lot about JavaScript or Node.js, you can use a folder wiki instead of a single-file wiki, which eliminates the file-size problem because the attachments are stored as separate files and don't have to be rewritten unless they're changed. If you don't have any particular reason to prefer single-file TiddlyWiki, this is likely your best option.

Take a look at the Options for Saving and Hosting Your Wiki appendix for details.

If you're editing the wiki over a network (i.e., not from the computer on which you're running the server), this method might still be slow if you have a lot of images, since all of the images will still be sent to your browser when you open the wiki. To avoid this, you can configure the server to lazy-load the images.

Linking to external content

One way to avoid the issue is to link to content stored elsewhere instead of putting it in your wiki at all. For instance, you can display an image stored on the web using the img syntax:

[img []]

Similarly, you could link to a PDF instead of transcluding it.

You can also link to files on your computer by placing them in a folder next to your TiddlyWiki. Say that you're using TiddlyDesktop, and you have a single-file TiddlyWiki, C:\Users\Soren\Documents\TiddlyWiki\tw.html. You could create a folder called C:\Users\Soren\Documents\TiddlyWiki\attachments. Then, when you want to have a file available for linking from TiddlyWiki, put it in this folder and display an image or link to a PDF like this:

[img [attachments/myimage.png]]
[[See my PDF|attachments/mydocument.pdf]]

Often, you might be fine storing the content external to your wiki, but you'd really like to be able to treat it as a normal tiddler – for instance, so you can transclude a PDF into another tiddler, or filter your images by certain criteria. You can improve on the approach above using a special field called _canonical_uri on a tiddler. (Notice that this is spelled uri, not url – the difference between a URI and a URL is technical and irrelevant for our purposes, but getting the field name wrong will have very relevant results!)

Here's how it works. Start by creating the folder and files mentioned in that section. Then, in TiddlyWiki, create a new tiddler and give it the name and fields that you would like. Instead of filling in the text field, however, create a field called _canonical_uri and paste in the path, like attachments/mydocument.pdf. (You can also provide a URL to content on the web, if you like.) When you add the field, a notice will appear that you can't edit the content in TiddlyWiki because it's stored outside the wiki.

It's important you get the MIME type right (that's the little box labeled Type right underneath the content). If you don't, your content won't show up when you save the tiddler. If TiddlyWiki doesn't fill something appropriate in, you can pick from the drop-down for image or text types, or type application/pdf for a PDF.

When you save the tiddler, you should see the content appear. At this point, it will behave just like any other tiddler, except that you can't edit the content from within TW and it will stop working if the content is moved.


Exercise: (M) [Ex:ContactInformationPicture]

Edit the ContactInformationTemplate so that it tries to include a picture for each contact. If the tiddler name is, for example, JaneDoe, and there is a tiddler called JaneDoe/Picture, Jane's picture, at most 300 pixels wide, should appear at the top of the tiddler. No error should be displayed if such a picture doesn't exist (hint: a filter operator called is[tiddler] will come in handy).

Add an image for one of your contacts and confirm that everything displays as expected for contacts that have a picture and for contacts that do not.

go to answer

Exercise: (m) [Ex:CanonicalUri]

Select a contact you didn't add an image for above. Place an image for this contact in a folder called images next to your example TiddlyWiki, and use the _canonical_uri field on a new tiddler to reference this contact's image. Check to be sure the image is displayed on the contact tiddler as expected.


Takeaways are not available in the static version of Grok TiddlyWiki. Visit the wiki version of this page to study takeaways.

↑ 5: More Organizational Tools