1. General notes

OPML is an open standard for transferring outline-type data between applications.  Scrivener can import OPML, allowing Tinderbox data to be exported to Scrivener.

Format limitations: OPML is a plain text format. Text formatting, i.e. bold, underline, font face/colour, highlighting can't transfer via OPML, nor may Tinderbox links between notes.

This tutorial was made using Tinderbox v6.0.2 and Scrivener v2.3. The built-in templates referred to here are those shipping in Tinderbox v6. Note:

  • Scrivener has supported OPML drag-drop** import since v.1.x (?) and certainly in v2.0+.
  • As at Scrivener v2.3, OPML import can be achieved only via drag-drop into the Binder pane.
  • The latter can be modified by adding OPML as a Plain Text Import Type (as explain during this tutorial). This was due to made a default preference setting in v2.3 ,but was omitted in error. It should be the case in any post v2.3 release.

Set up Tinderbox as suits your style - there is no one 'correct' way. As both apps offer some choice in to how the export import occurs, the tutorial will show a basic method and then discuss some variations.

Even if you write/work in other views, for Tinderbox export, it is suggested you use Outline view as it gives the clearest map of what you may expect in output terms.

At the Scrivener end, the Tinderbox note title ($Name) becomes a Binder note name, and the note's text ($Text) the text of the Binder note - unless the latter is modified by Scrivener import Preferences (more on this below). Tinderbox $Checked data is imported but it is unclear whether this is used by Scrivener.

2. Tinderbox set-up: add the necessary export templates

2.1 Add the necessary export templates

2.1 Add the necessary export templates

This action only needs doing once (per TBX document) - skip this step if you have already added these templates.

In Tinderbox, open the File menu, Built-in Templates, and then Scrivener from the sub-menu.

2.2 What gets added to your Tinderbox document

2.2 What gets added to your Tinderbox document

Two nested templates are added, 'Scrivener' and 'Scrivener item'. If a root-level 'templates' container doesn't exist, Tinderbox will add one. As the templates use a built-in prototype 'HTML Template', the latter - and its container - are also added if necessary. In most mature documents, the templates and prototype will likely be added into the existing relevant containers.

3. Scrivener set-up: some non-default Preferences - 1

3. Scrivener set-up: some non-default Preferences - 1

Here, 'opml' has been added to the default list. From Scrivener v2.4 it should already be part of the default list.

Until/unless you make this change OPML can only be imported by drag/drop onto the Binder. Once 'opml' has been added here, the Scrivener File menu, Import, Files can used to select and import OPML files.

However, for the rest of this tutorial the status quo (i.e. drag-drop only) will be assumed.

4. Choose your export container

4. Choose your export container

Arrange your Tinderbox document's content so that:

  • all the data to export is within/descended from a single container
  • the container note does not contain data needed in the export

The export container may be anywhere in the document - above it is shown at root level but that is not a requirement.

The export process will export all descendant notes from this container. If it is not possible to arrange the desired notes into a single hierarchy containing only the to-be-exported notes, you may need to export the data as several discrete OPML files.

5. Set the export container's template

5. Set the export container's template

With the same container still selected, open the HTML Inspector and from the Template pop-up select 'Scrivener'. The other 'Scrivener item' template is used automatically as part of the OPML export - you do not need to configure it.

6. Exporting a single page from Tinderbox

As at v6.0.2, Tinderbox 6 still lacks a single-note export button (the Export button on v5's HTML Inspector). File-Export to HTML exports the whole document. For now a work-around is needed, involving use of TextEdit.

6.1 Get the Code

6.1 Get the Code

Select the OPML export container and switch the text pane of the window to 'HTML'. Press keys Cmd+A and everything will be selected - in bluse as shown. Then pres keys Cmd+C to copy the selection. Your OPML code is now on the Mac's clipboard.

6.2 Make a new plain text document in TextEdit

6.2 Make a new plain text document in TextEdit

Open the TextEdit app (it is free and installed on all Macs) and open a new document if one is not created automatically.

  1. If the document window shows a ruler and toolbar (see top picture above), use the Format menu, Make Plain Text.
  2. The result should look like this, with no ruler or toolbar.

6.3 Paste the OPML code

6.3 Paste the OPML code

Paste the OPML code on the clipboard into the TextEdit document.

6.4 Save the file with the correct '.opml' extension

6.4 Save the file with the correct '.opml' extension

Important: save the text document making sure to replace any default extension (usually '.txt') with '.opml'.

The file and TextEdit may now be closed.

7. Locate the exported OPML file

7. Locate the exported OPML file

Switch to Finder to locate your exported file, which you will now drag into Scrivener's Binder.

Important: Do not use Scrivener's File -> Import menu. You must use drag drop of an OPML file from a Finder window.

Scrivener's manual describes the process thus (pages 493-4):

  • When OPML files are dropped into the binder, Scrivener will attempt to con- vert these outlines into Scrivener outlines. This can be useful if you do your initial brainstorming in a dedicated outliner application. Some of these applications support attached notes to each outliner header. If notes exist, Scrivener can be instructed to apply these notes either to the Synopsis alone, the main text, or the document notes for that heading in the outline. Note that in the case of the last two options, the synopsis will still be set automatically to the first few hundred characters of the note.
  • If you want dropped OPML structures to be generated inside of a special folder, rather than directly into your existing Binder structure, enable the “Create folder to hold imported OPML items” option.

The last option is described further below.

8. Drop OPML file in Scrivener's Binder - 1

8. Drop OPML file in Scrivener's Binder - 1

Drop your file onto your Scrivener document's Binder (the left column of the Scrivener app window).  If the Binder is not shown, use the Binder button on Scrivener document's toolbar to display it. Dropping the OPML file onto any other part of the document or onto the app's Dock icon will result in incomplete or corrupted input.

8.1 Find the Binder

8.1 Find the Binder

Drop your file onto your Scrivener document's Binder (the left column of the Scrivener app window).  If the Binder is not shown, use the Binder button on Scrivener document's toolbar to display it. Dropping the OPML file onto any other part of the document or onto the app's Dock icon will result in incomplete or corrupted input.

8.2 Confirm Import

8.2 Confirm Import

Drop your file onto your Scrivener document's Binder. The first time you do this, you will see a warning. Just click Import. As already explained we're only importing plain text so the warning doesn't apply here.

8.3 Choose insertion point in the Binder

8.3 Choose insertion point in the Binder

Scrivener will indicate where insertion will occur.  If the dropp occurs with no blue indication showing, the new data will be inserted into the Binder after the Trash and at root level.

9. Data arrives in Scrivener (default Preferences)

Exactly where the dropped data arrives depends on where you drop the data. If you drop over/between existing content, Scrivener shows a blue cursor indicating whether the drop will occur inside or between items.  Worst case, the dropped item(s) can always be moved again by dragging within the Binder.

If you look at the picture for Step 4 above (Choose your export container), you will see you exported 2 notes with text ($Text), one of which had a child note with no text. As can be seen, the note title ($Name) and text ($Text) are transferred.

Notice that the children of the Tinderbox export container are added directly as Binder items. If you prefer they all get added within a single Binder item, change you Tinderbox layout so that the export container contains a single child container holding all the export content. This technique is explained further on in this tutorial.

10. Setting Scrivener OPML Preferences

10. Setting Scrivener OPML Preferences

OPML settings are stored in Scrivener -> Preferences, Import/Export pane, Import Options tab.

The pop-up settings are:

  • Synopsis
  • Main Text (with Synopsis)  --> default setting
  • Notes (with Synopsis)

This tutorial only uses the default setting, i.e. for Main Text. Regardless, within the Binder the results are the same, the above simply affects into what part of the new Binder item(s) any Tinderbox data is placed.

The Create folder to hold imported OPML items box (default: un-ticked) is useful if you'd like to add all imported items to a new root folder in the Binder. The next shows the result of repeating the earlier process with this option ticked.

11. Data arrives in Scrivener (revised Preferences)

With the altered Preferences, the exported container from Tinderbox becomes a new folder in the Binder (using the Tinderbox container's name and not the OPML file name) as its name. Note however, that the Tinderbox $Text of the exported container is not used for the Binder

12. Exporting the whole Tinderbox document

12. Exporting the whole Tinderbox document

It may be that your Tinderbox document is, apart from back-of-house stuff like templates, all data for Scrivener. In that case, put all the content inside one export container at root level, as detailed earlier. Now select each other root-level container, e.g. 'Prototypes', etc., and open its HTML view. Un-tick the Export and Export children boxes. These ensure the container and anything in it won't export as part of a whole-document export.

Note that the Scrivener template contains code that sets the file extension of any exported note(s) to '.opml'. If you later wish to export those same notes as HTML you will need to check each affected note's Extension box and change it as needs be.

When done, you can simply export the whole file: File menu, Export as HTML…

If you have an export container for Scrivener data nested inside other Tinderbox content you don't wish exported, only un-tick the 'children' box and leave the 'Export children' box ticked. Tinderbox will export a Finder folder for each ancestor container of your OPML container but not files for those notes.

It is also perfectly possible to mix OPML export with the default HTML (or other template-derived format) export. In such a case all files would export their normal HTML files. As the OPML export involves a cascade where one note simply reads and includes the content of others, you can even have a note inside the 'opml' content area still generate an HTML file. In such a case the only file not to generate HTML would be the OPML export folder as no note/container can generate more than one export file.

13. Exporting multiple OPML segments for Scrivener

13. Exporting multiple OPML segments for Scrivener

The above image shows a document where there are three discrete sections of Tinderbox data to export, resulting in three separate OPML files. As before, either container can be placed anywhere in the document. For simplicity here, everything is at root level but in a mature document the layout may be more complex. Badges have been applied to indicate which containers export. Building on idea discussed above, there is no reason why the non-Scrivener data might not be exporting to some other format. Set up the document as you needs dictate - Tinderbox is very flexible.

In this next example, the process is done using Scrivener default preferences (as described above).

14. Making data arrive in Scrivener in a single set of Notes - 1

14. Making data arrive in Scrivener in a single set of Notes - 1

As discussed above, by placing everything inside the export container within a single child container, you can create a 'folder' for you imported date in Scrivener - see the next step. A second OPML note is exported in the last case as it is for a different Scrivener file/project.

15. Making data arrive in Scrivener in a single set of Notes - 2

The data here as as at the beginning but now arrives in Scrivener with it all contained inside a single Binder item. It's down to individual style whether this is an help or just more work.

16. Making data arrive in Scrivener in a single set of Notes - 3

Here the same exercise as the last step is combined with the Scrivener preference to add new data within a new Binder folder.

17. Location of imported notes in Scrivener when using File -> Import

If OPML is enabled for import via the main menu, the insertion point seems to be decided thus - based on experiment:-

  • Nothing selected in Binder, items are added as children of 'Research'.
  • Root level folder selected, items are added as children of selected folder'.
  • Non-root-level note/folder selected, items are added as siblings of the selected item.

Drag-drop probably gives finer control over placement of imported items.

18. Which method should I use?

Again, set up Tinderbox as suits your style. One OPML file, several files - there in no one correct way. Different users will have different needs. You might for instance have separate OPML exports for discrete projects. Even if both projects live in the same document in Tinderbox and Scrivener you might still want to be able to transfer data about Project A separately from Project B.

If you want to discuss OPML use, try the Tinderbox user-to-user forums or the Scrivener user-to-user forums.

If you have followed all the instructions and are still having problems, please email support for either Tinderbox or Scrivener.