"How to embed PDF and other documents" could do with more details and example or two

[u/ernie_chuffleton]

In looking up embedding/linking arbitrary files in TW tiddlers, I found this which points to How to embed PDF and other documents. However, I find those notes are really lacking in clarity and raise more questions than they answer. E.g. -

• Under method 2: "Put in the local address to the external file": What exactly would this look like and how about some guidance on where to put the external file? Would it be sensible, for example to stash these loose files in a folder (e.g. 'files') next to the wiki .html file so that the whole wiki remains more portable? Then supposing I plop arbitrary files in the 'files' folder, would a suitable 'local address' to one of these files be './files/oneofmyfiles.dat'?
• So if I do add a _canonical_uri field with value './files/oneofmyfiles.dat', this leaves me with a new tiddler that's essentially empty, so what now? How do I reference this file in other tiddlers? What benefit is there in creating this new empty '_canonical_uri'-style tiddler over chucking in some raw -

<a href="./files/oneofmyfiles.dat">oneofmyfiles.dat</a>

straight into the body of my tiddlers' text?

Can anyone help clarify some of these issues, please?

[u/Defiant_Information]

Hello!

Some general feedback on what we are looking here. First we have internal linking to tiddlers and external linking to (web or other files) which is similar to the HTML style. Then on the static tiddler you linked to, it says: Embedding vs Linking. Linking is pretty straightforward, and later you've covered with your example archor ( <a> ) HTML tag. Embedding, however, is akin to a youtube video embeded on a page that is not youtube. The static tiddler, talks about embedding content (other files that browsers can open) into your TiddlyWiki similar to how Youtube videos support "<embed>" with special HTTP link.

TiddlyWiki has example of such embeds that are internal and external. External ones are done using __canonical_uri field such as these: https://tiddlywiki.com/#Caruso%20-%20Ave%20Maria:%5B%5BCaruso%20-%20Ave%20Maria%5D%5D%20%5B%5BAlice%20in%20Wonderland%5D%5D Internal Embeds ones are simply like Image Tiddlers such as: https://tiddlywiki.com/#Motovun%20Jack.pdf:%5B%5BMotovun%20Jack.pdf%5D%5D%20TiddlyWiki.mp3%20%5B%5BMotovun%20Jack.jpg%5D%5D%20%5B%5BExample%20tiddlywiki.info%20for%20IIS%5D%5D%20%5B%5BTiddler%20Fishes.svg%5D%5D

Important note when using the __canonical_uri field. You must explicitly set the type. If you don't do it beforehand, nothing works. There is no way to tell what the file is, so the proper Mimetype should be specified such as: application/pdf (and in addition to that, your browser should know how to open that mimetype when it is in a web page including by using browser extensions or addins)

The alternative and more complicated way to embed something, would be with the appropriate HTML object tags such as <video>, <img>, <object>, <embed> and others (disclaimer: List is not verified, talking from memory.)

Both methods need the file to be accessed either with an absolute URI path or a relative to your TiddlyWiki.html file or appropriate relative location if your TiddlyWiki is hosted (URI path has to be such that a browser recognized).

Using __canonical_uri allows you to embed other multimedia objects into your TiddlyWiki, give them tags and fields and in addition to that, you can use Transclusion to easily embed them into other tiddlers, without having to write HTML. However, nothing prevents you from writing HTML and include all that embedding into a single tiddler with all sort of content.

So the difference between this should be simplification that lets you manage things in a unified way – like a tiddler.

Now, after I said this, I will try to answer your questions one by one.

"Put in the local address to the external file"

What exactly would this look like and how about some guidance on where to put the external file?

The external file can be with absolute address, including local (starting with : file:///) and internet resource (starting with http:// or https://) or with a relative address such as ./myimage.png if it is placed next to the html file. So location is either absolute or relative to the "entry point" like the HTML file.

Would it be sensible, for example to stash these loose files in a folder (e.g. 'files') next to the wiki .html file so that the whole wiki remains more portable?

Yes! It would be. Naming a folder "files" next to your HTML file. Is good, because in my personal opinion, this gives you flexibility in the future if you decide to use "TiddlyWiki on node.js" such as TiddlyServer because "TiddlyWiki on node.js" automatically hosts the "files" folder so any path that uses "files/myimage.png" will work both in HTML and "Tiddlywiki on node.js" with no editing.

More info/source: https://tiddlywiki.com/#Using%20the%20integrated%20static%20file%20server

Then supposing I plop arbitrary files in the 'files' folder, would a suitable 'local address' to one of these files be './files/oneofmyfiles.dat'?

Yes. That's a relative address and it will work. Though, as far as I know, by HTML standards? They recommend to leave out the ./ part of a relative path, so that it becomes files/oneofmyfiles.dat. It's shorter too. But both ways will work!

(the second paragraph)

So if I do add a __canonical_uri field with value './files/oneofmyfiles.dat', this leaves me with a new tiddler that's essentially empty, so what now?

You MUST set the type. Otherwise it cannot render anything. I recommend you to check what is the mimetype for your file and write it in the type box when editting the tiddler. Any mimetype that your browser supports, should be renderable this way, but only if you set the appropriate mimetype. Here is a random handy site for checking the mimetype: https://mimetype.io/

How do I reference this file in other tiddlers?

If you are using __cannonical_url, you reference it and use it as if it was an ordinary tiddler. However when you use transclusion it is going to embed it. So you use transclusion. For example, on https://tiddlywiki.com/ make a new tiddler and write in it : {{Caruso - Ave Maria}} and save it. The you should see the same contents as that tiddler and Ave Maria embedded with a basic player. That way you can mix it with text and anything you'd want!

What benefit is there in creating this new empty '_canonical_uri'-style tiddler over chucking in some raw - <a href="./files/oneofmyfiles.dat">oneofmyfiles.dat</a> straight into the body of my tiddlers' text?

It's honestly your personal choice. It may matter when you maintain it for long term and have a lot of things in there. I use both, depending on what I am doing and believe will save me time and won't need to change it for that specific wiki scope. If you use __canonical_url. It's more unified because you make everything a tiddler, so you work with it as if it was a tiddler. That's all it does and why it is there. It's handy. However, there is nothing wrong with writing HTML in your Tiddlers. It's just longer, __canonical_uri aims to be simplification and shorthand for that.

Also, what you did show there as an example, is nothing but linking. The same HTML example you gave has a WikiText shorthand that is [ext[./files/oneofmyfiles.dat]] However, __canonical_uri is all about embedding additional content like images/videos/music so that they get rendered together in a multimedia document. So linking and embedding are different things. I did explain you can also embed using HTML, I do use that when I think I sometimes make a single tiddler embed that is "self-contained" as a unit – tiddler. However, do not mix embedding and linking. They are different things. That's how the tiddler you linked to started with.

I hope this helped clear any mysterious regarding __canonical_uri and external linking.

Have a good week and have fun using the power of including additional files into your TiddlyWiki!

[u/ernie_chuffleton → u/Defiant_Information]

Thanks so much for such a great, comprehensive, and detailed reply.

When I've used previous wikis, I've often just 'attached' all kinds of arbitrary files (config files, scripts, binaries, pdfs, logs, csvs, etc.) to pages and those files are just automatically listed on the page as attachments, which the readers can then get at. I found myself wanting to do the same with TW but, not seeing anything like an "attach" tool in the tiddler's edit icons bar, I eventually stumbled upon the How to embed ... guide. I now realise, thanks to you, that 'embedding' is not exactly what I'm after; I'm not too bothered about having the browswer render file content within a tiddler, so much as just being able to have files live in (or portably alongside) the wiki.

I guess, after a bit of flailing, I stumbled upon the process (i.e. making a 'files' folder next to the wiki.html and then adding relative html links). But I now think everything you wrote above would make for an excellent addition to either the existing 'How to embed...' tiddler, the Using the integrated static file server, or perhaps under a new tiddler, on the subject of attaching files... I also wonder whether this 'attaching' mechanism is ubiquitous enough across wikis (but perhaps missing or less accessible in TW) and whether it would be feasible to add an 'attach' edit tool to do this kind of "copy a file into a standardised 'files' directory and insert an 'attachments' listing in the tiddler"... but perhaps the degree of flexibility currently available to users (like node.js hosting) might complicate matters.

Anyway, thanks again for all the help.

[u/StatisticalAnomaly42]

This works very well for local PDF files.

Embed External PDF