This year will mark the 10th anniversary of my blog for technical writers, Usable Help. Since day one, I've written, built, and managed the site using Tinderbox. It's rather remarkable that I'm still using the same tool a decade later, and almost astonishing that I'm using the same Tinderbox file (document), considering that I started with Tinderbox 1.0 on Mac OS 9. Tinderbox has continued to grow and evolve, and Mac OS has been radically transformed, but here I am with the same file I created so long ago.

Oh, sure, there have been tweaks and changes over the years. But one thing I've never changed is the way the HTML templates work. (I've updated their design a couple of times, of course.) Because my file was built on very early technology, it had some vestigial requirements, such as a reliance on absolute filesystem paths. I've been meaning to fix this, but frankly since it has "just worked" for so long, it was just a minor annoyance and never became a showstopper. But this year, I'm working a little bit differently and relying more on "the cloud." When I moved my ancient Tinderbox file, exporting broke, and this time I decided to fix it.

It's possible that I'm the last of the dedicated Tinderbox users to adopt the new way of storing templates. (Internal to the document, instead of externally in the filesystem.) Thanks to Eastgate's detailed release notes I was aware that internal templates were supported, but I had no idea how to convert over to using them. I scoured the Tinderbox forum and eventually put together the info I needed. Here's a brief summary of the process.

1. Copy the contents of each HTML template file into the body of a new Tinderbox note. I created a new container to hold all of the templates.

2. When you create each note, be sure to check the Template box so that Tinderbox will let you choose it later. For clarity, I decided to name each note with the filename of the external template it was replacing. This comes in handy for the next step.

3. With all of template notes created, the next step is to assign them for use during export. This is the trickiest and most time consuming part of the conversion. For each note that is exported, you'll need to change its HTMLExportTemplate setting. The easiest way to do this is to select the note, choose View > New HTML View. Then, use the Template popup menu to select the internal template note.

Unfortunately, if you've already moved your Tinderbox document to its new location (and thus broken all of the template links), the Template popup menu doesn't give you a hint about which template the note was previously using. To find out, choose Note > Get Info. In the info window, choose HTML from the section pop-up, then look at the value of the HTMLExportTemplate key. Notice in the screenshot that it's pointing to an absolute filepath.

When you've successfully set the new internal template, the key will look like: /html templates/UHpagtemplate.html

(That's your note container, and the name of the template note.)

4. Now, if you're like me, you just realized that changing every note in your file could take hours, if not days. Take heart, just use an Agent or Stamp to reset groups of notes quickly. Seriously, it won't take long at all if you use this method.

5. In the last step, you converted all of your existing notes. Now you need to reset the template for new notes. To do that, make sure all of your prototypes are set to use the new templates too.

That's it, your file is converted. Just be sure to look at every exported file to see if it's using the template you expect. You might have missed a nested template or two. No problem, just go back and create template notes for them, too.

I hope this speeds your conversion process along. Don't be intimidated, it's a bit of work, but well worth it. Here's to the next 10 years of Tinderbox!