Creating an article in HTML with Tinderbox

Outline the article's sections

The first thing to do is to create a new document, which opens up as an Outline View by default. Hit return to create your first note, and type the title "Creating an HTML5 Article with Tinderbox":

Now, if you hit Shift-Return, you'll create a child note under the first one. Type the title of your second note, "Outline your article's sections". After that, hit Return, and you can start typing the title of the next note. Your outline is now well under way:

This is basic outlining, one of the simpler features of Tinderbox and many productivity applications. Continue like this, sketching out the structure of what you plan to write. You can drag notes around to rearrange them, delete them, do whatever you like with the outline. Note that Tinderbox offers many further tools for capturing and visualizing your thoughts, but we'll stick with the Outline View for now.

Write the article's text in notes

Once you've got an outline for your article in good shape, it's time to start writing the text of the article itself. Really, you can bounce back and forth between outlining and writing prose—Tinderbox doesn't impose a process—but this is a good time to introduce the latter.

In Tinderbox, notes have many attributes. So far, you've seen the Name attribute used as the titles of outline nodes. Well, notes can also contain body text. To see what I mean, click on a note to select it—say the root note of your outline—and hit the spacebar. Here's what the body text looks like for the root node of this tutorial:

You can click on any note in the outline and call up a text editor with the spacebar. By using this editor, you can work on writing the actual content of your article.

Creating an "Internals" note to contain utilities

First, in order to keep things clean, you're going to create a new note to contain the export machinery you'll soon need.

Select the root note of your article. But, rather than just hitting return to create a new outline item, hit Cmd-K to summon the full Create Note dialog window:

In this dialog, you can control quite a number of different attributes and options. But, ignore most of them for now. Just type the name "Internals" and, for good measure, check the "Separator" box. This will create a new note like the following:

Checking "Separator" served both to sneak in a new example of a Tinderbox feature, as well as to make this special new container stand apart from the article content. I prefer doing this to help make a clear distinction between the content I'm working on and the notes I accumulate to help process that content.

Also, notice I got a little ahead of things in the screenshot above: Two additional notes should be added as children to "Internals", respectively named "Prototypes" and "Templates". These will serve as containers for further resources created throughout the tutorial.

Creating the *article prototype

Next, to further explore prototypes, create a child note named "*article" under the Prototypes note in Internals. Why the name *article? No technical reason, really; name it whatever you like. I prefer to use peculiar names for notes that have special purposes—not unlike using the separator style for the Internals container.

Now, either right-click and select Rename from the context menu, or hit Enter. (That's Enter, mind you, not Return. On my MacBook Pro, this is Fn-Return.) This will summon up the note details dialog, not unlike the one used to create the Internals note earlier:

In this dialog, check the box next to "Can be a prototype" and click Ok. This note is now a prototype.

Next, to use the new prototype, select the root note of your article and summon the note dialog with either the right-click menu or the Enter key:

Notice the drop down selection for Prototype. In this list, you should see the name of your new prototype *article—select it and hit Ok. Now, your root article note is an instance of the prototype *article.

Creating the *section prototype

The next prototype to create should be named "*section". This one will be used for all the sections and sub-sections in your article. Create it in the same way you created *article—that is: create the note, summon the note details dialog, ensure "Can be a prototype" is checked.

After you've created a *section prototype, give it a badge. I used "arrow right" in my document:

I've also given a "folder" badge to some other container notes: These are purely ornamental, helping keep track visually of the purposes that various notes serve. Now, select your article's root note, select View > Expand All to reveal all sections. Select all of these sections, by clicking the first and then clicking the last in the list while holding shift. The selection should look like this:

Once you've got sections selected, it's time for another interesting tool in the Tinderbox, called Quickstamp. Either hit Cmd-1 or pick Window > Inspector from the menu. You'll see a dialog like this one:

With this dialog, you can quickly assign a value for a given attribute onto many notes at once. Select the "General" category from the first drop down, and then "Prototype" from the second. Type "*section" into the Value field, and click Apply.

Almost instantly, you should see the badge from your *section prototype appear on all the sections you've selected in your outline:

As the spread of the decorative badge demonstrates, the prototype inheritance mechanism has propagated the badge change to all notes using *section as a prototype. This will come in handy beyond badges before the tutorial is done.

Using an OnAdd rule to auto-create *section notes

There's one more way to apply a prototype that's worth showing here. You've applied a prototype to a single note, and then used Quickstamp to apply a prototype to many notes. But, those are manual processes—wouldn't it be nice if you could get a prototype automatically applied to certain notes when you create them?

As it turns out, this something the "OnAdd Action" field in the note details dialog can do. Open up the details for the *article prototype, and type in the following OnAdd Action field:

if ($Prototype=="") { $Prototype="*section" }

The dialog should look like this before you hit Ok:

Repeat this process with the *section prototype.

What should happen in your document now is that whenever you add a new note to your document under notes using the *article or *section prototype, that new child will be assigned to the *section prototype—unless it already has a prototype (eg. having been dragged in from elsewhere, or having been given a prototype by other means).

This is pretty powerful: It means that you can set up outline container notes that establish defaults over their contents, without requiring manual work beyond creating children.

Creating a *template prototype

HTML export can be accomplished in Tinderbox though the use of export templates. If you're a web developer, you're probably already be familiar with the concept. If not, think of templates as akin to mail merge in word processors: A single example of output applied to many instances of structured data.

Export templates in Tinderbox can be files on disk, or taken from the text of notes in your document. They're built using a set of codes that allow you to reference notes, output attribute values, and construct enough logic to satisfy most export needs.

For this tutorial, we'll use notes for templates. So, the next step is to create a prototype named "*template" under your Internals note, like so:

Ensure that both the "Can be a prototype" and "Can be a template" checkboxes are checked in the note details dialog. In my document, I also gave the *template prototype a "design" badge, so as to make them easily identifiable in outlines.

Creating the article.html template

Alongside the Prototypes note under Internals, we also created a Templates container note. Within this note, create a new one named "article.html" using *template as a prototype. Your outline should now look like this:

Edit the text of your new article.html note, pasting in the following code:

<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
        <title>^title^</title>
    </head>
    <body>
        <article>
            <h1>^title^</h1>
            ^value($Text)^
            ^children^
        </article>
    </body>
</html>

Giving a full explanation of the export codes available for use in templates is beyond the scope of this tutorial, but hopefully you can make sense of most of it. It's HTML, with a few codes sprinkled in to pull content from an article note. You can add CSS and JavaScript includes if you like, and customize the markup however you like.

One of the most interesting parts of this template, though, is the ^children^ code: This code causes the export process to recurse into directly-related children in the outline, including the output of their export templates at this spot in the parent note outline. Note that there's also a ^descendants^ code, which recurses further into all children of children, but that's not what we want here.

So, this article.html template provides the overall shell for the HTML page, including both content from the root note of the article and all its sections.

Using the article.html template

Now that you've got a template for use in exporting an article, it's time to use it. This is a natural match for the *article prototype you created earlier. To pair the two together, first select the *article prototype note and then choose View > New HTML View from the menu. You should see something like this:

Within that view dialog, there's a drop down selector for the Template field. Listed in that selector should be your new article.html template, so choose it. This will set this template as the default for any HTML export of any note using *article as its prototype. For the current document, that's just one article, but it could apply to many thanks to the prototype inheritance mechanism.

Additionally, ensure that the "Export" and "Markup text" checkboxes are checked in this dialog. This will ensure the article is exported, and that the plain text content of these notes will be automatically wrapped in HTML tags according to some rules built into Tinderbox.

Note that the "Export children" checkbox is unchecked: This is because article.html uses the ^children^ code to include exported children within the same HTML file, whereas "Export children" will cause the export process to produce separate files for all child notes. Doing both could be useful in, for example, blogs with index pages and individual entry pages displaying the same content.

You should feel free to play with these settings to get a sense for what they do—their results should appear in the HTML View as a preview whenever you click the "Update" button. You can also use the "Preview" button to open the HTML in a browser of your choice, configured for the document. (To choose a browser, try Edit > Document Preferences > HTML from the menu bar.)

Creating and using the section.html template

Just as you did for article.html, create a new note under Internals / Templates, giving it a prototype of *template. Edit its text and paste in the following code:

<section>
    <h^value($OutlineDepth)^>^title^</h^value($OutlineDepth)^>
    ^value($Text)^
    ^children^
</section>

This looks much like the article.html template, though it introduces the attribute OutlineDepth. You can consult a full list of note attributes, but this particular attribute is useful for determining the depth of a section within the outline. This allows you to programmatically produce section title elements progressing from <h1> to <h6> and beyond, depending on how deeply nested a subsection is within the article.

And as you did for *article, open a new HTML View on the *section prototype and select the section.html template to pair the two, like so:

The impact of doing this for the *section prototype is more wide-ranging than for the *article prototype: Since *section is applied to most of the notes in the outline, pairing the section.html template to *section causes that template to also be paired to every section in the article.

So, thanks to ^justChildren^ and the use of prototypes, the article.html and section.html templates will be used to recursively export the content from all notes in your article as HTML.

Preview and perform an HTML export

If you select the root note of your article and open an HTML View, you should now be able to see a preview of the full HTML page that will be exported using the templates you just created and paired with prototypes:

From the HTML View, you can also set a file name, extension, and destination folder for file output of the HTML export. Hitting the "Export" button will produce the desired file on disk.

Additionally, once these attributes have been set, they'll be used as defaults in the future. This comes in handy for use with the File > Export as HTML... menu item, which will perform HTML export on all notes without the need to open a new HTML View for each one individually. This doesn't matter as much for the present document, since there's only one article, but you can produce a collection of articles or even an entire website in this manner with just a single Tinderbox document.

Restricting which notes get exported

If you tried the File > Export as HTML menu item, you may have noticed some extra files and folders beyond the article itself appearing in your export folder. (If you haven't tried it, you might want to do so now to follow along.)

This is because all notes have an attribute HTMLDontExport with a default value of false. This means that when the Export as HTML command scans through the entire document, all notes are exported except those with an HTMLDontExport attribute set to true. This attribute can be managed by the Quickstamp dialog, is also managed by the HTML View (eg. the Export checkbox), and via the Note > Get Info menu item.

There's also an attribute called HTMLExportChildren, which corresponds to the "Export children" checkbox in an HTML View. This acts like the inverse of HTMLDontExport, only applied to all the contents of a note.

In particular, the Internals note and all of its children are not worth exporting to HTML. So, to exclude it from the process, select the note and open a new HTML View. Ensure that the "Export" and "Export children" checkboxes are unchecked.

If you try another Export as HTML command to an empty folder, you should notice that the extra files and folders not related to your article's page are no longer generated by Tinderbox.

Filtering exported text through Markdown

Throughout this tutorial, you also may have noticed that I'm using the Markdown syntax in my article text. If you tried to do the same, you may have wondered why your HTML exports didn't seem to support this formatting scheme.

As it turns out, Markdown is not built into Tinderbox. Instead, export codes offer a tool you can use during to filter text through external shell commands. As the creator of Tinderbox explains in a blog posting, this means that you can cause Tinderbox to execute Markdown.pl as a text filter during the HTML export process.

To do this, you'll first need to download the Markdown script. I did so, and copied Markdown.pl to /usr/local/bin on my Mac.

Next, edit the source of your article.html and section.html templates. Look for these lines:

 ^value($Text)^

Replace these expressions with the following template code:

 ^value(runCommand("perl /usr/local/bin/Markdown.pl",$Text))^

If you placed the Markdown.pl script in a directory other than /usr/local/bin, be sure to adjust the file path in runCommand().

Here, the runCommand() operator does the work of executing Markdown.pl with your note's text as input. The output will be included in the HTML export.

Building anchors for within-page links

For a long document like this tutorial, including anchors within the page is useful for supporting links to specific parts from other referring pages or for building a table of contents. And, the important thing about creating page anchors is that each is given a unique identifier.

By default, though, a note in Tinderbox does not have unique a identifier accessible by attribute from which to build a page anchor. However, you can create one yourself by setting up a new attribute that implements an auto-incrementing index.

<section id="section-^value($id)^">
    <h^value($OutlineDepth)^>
        <a href="#section-^value($id)^">^title^</a>
    </h^value($OutlineDepth)^>
    ^value($Text)^
    ^children^
</section>