A Tinderbox Scrapbook for Source Code: exporting in Wordpress markdown

A few weeks ago, I was lamenting the fate of blog posts and using Tinderbox to create a less transient Mac troubleshooting reference. Having spent quite a lot of the time since then working in Swift in Apple’s Xcode development environment, I now want to use Tinderbox to go the other way.

Even when you write code every day, it’s hard to remember all the neat tricks and solutions which you come across or devise. I started to collect these on pages in this blog, but they have since fallen a bit by the wayside. I have a couple of code editors which help you keep code snippets, but they aren’t designed to export them to this blog. The best and most versatile tool for this type of task is Tinderbox.

The plan is simple and natural: each code snippet, ranging from one-liners up to complete functions, is kept in a separate note, with as little or as much supporting text as is needed. Those notes are kept in topic-based containers, such as one for strings, another for alerts, and so on.

When I’m writing code and cannot remember, say, how to eliminate duplicates from an array, I look in the appropriate container, or use the Find command if I’m unsure where it will be. I open the note, select the code, copy, and paste into my source in Xcode.

scrapbook01

Although it might be nice to be better integrated with Xcode, this works fine, and Xcode quickly formats and displays the added code.

When I want to refresh an article in this blog with new and updated code snippets, I use Tinderbox’s export to HTML feature to generate WordPress ‘markdown’ to drop into MarsEdit, my preferred offline editor, or even straight into the WordPress online editor in HTML mode.

scrapbook02

scrapbook03

In Tinderbox, I need to create a couple of prototypes for my code snippets and their containers, and to customise the HTML export template to generate WordPress ‘markdown’. With a new Tinderbox document, I start by by adding the built-in templates for HTML, in the File menu. This creates two new containers, for Prototypes and Templates, and populates them with the notes needed for plain HTML export, which I need to edit.

scrapbook04

My own prototypes are very simple at this stage: Snippet for notes containing code snippets, and Section for the containers in which to place those notes. The only key attribute is $MapBodyTextSize. That is set to 1 for Snippet, so that the body text isn’t shown on the tiles in the Map view, and 0 for Section, so that body text is shown on the containers.

scrapbook05

The three prototypes have similar markup settings: in the Markup tab, all the boxes are left empty, as WordPress doesn’t use paragraph markup.

scrapbook06

In the Style tab, I have replaced the normal HTML markup with that needed for these pages: this is a compromise, as code markup will be widely used, but underline requires a spanned style. I thought about using Strike through for code, but that would deface the code seen in notes. I can live without Bold, but not without Italics.

scrapbook07

The Snippet prototype is then set to use the HTML Item template.

scrapbook08

The Section prototype uses the HTML Page template. As with Snippet, it is set to not Export Children, which would result in each note generating its own HTML output file. With the prototypes set like this, export will generate one output file for each of the containers, which is exactly what I want for WordPress articles.

scrapbook09

The HTML page template is stripped of most of its output code to leave just this, which writes out the title marked up in bold, and text, and the children formatted according to the HTML item template.

scrapbook10

The HTML item template within that is also greatly simplified, and just exports the note text, followed by that of any children.

Now is the time to add a couple of notes inside a container, and tune the templates and settings to generate the precise output and appearance that I want.

scrapbook11

Here is a bunch of code snippets concerning strings, inside a Section container named String. Edited in the Text view, non-code is left in plain unstyled text, and code is set in bold.

scrapbook12

When viewed as HTML for export, the code is correctly enclosed in code markup. I also check other markup features, including italics, underline, and lists. In this case, the Preview setting is of little or no use because of the lack of paragraph markup.

scrapbook13

I then move up to the container, and check that its HTML view conforms to the whole page markup which I want.

Once I’m happy that the HTML views are looking good, I perform a test export, using the Export / as HTML command in the File menu. That should generate one HTML file for each container, in which are the marked up contents of each of the notes within that container. If that isn’t the case, I adjust the export templates and settings for the prototypes, until they’re perfect.

There is one remaining issue: the order in which the notes are exported into each output page. In this design, this is the order in which the notes are added to my Tinderbox document. If their order is of importance, then an alternative approach, such as including the contents of notes in their container text, might be a better solution.

Here is the Tinderbox file: swiftscrapbook1

Although this does open fine in Storyspace, as that app doesn’t have the export features of Tinderbox, it will only show you the content.

Postscript: Mark Anderson has kindly pointed out that it is worth bearing in mind that default text behaviour in notes is to use smart quotes, which can of course mutilate source code irritatingly. This behaviour can be turned off for prototypes which will contain code using the Inspector: switch it to the Text Inspector, then click the Text tab. Ensure that the bottom checkbox at the foot of that is unchecked, that above is checked, and you won’t be annoyed by spelling checks either.