Exporting to OPML

Disclaimer: This process involves a few geeky steps, especially in setting things up initially. However I’ll walk you through the tough parts. You should be aware up front that unless you manage to integrate the execution of Terminal scripts with some third-party launcher, you will always be required to use the command line to generate an OPML. The process of doing this is, however, quite easy, but if the thought of that seems far too intimidating to consider, I don’t want you to waste your time going through this how-to before realising it will never be as slick as a Mac program in the end.

Now, to those who are geeky enough to read a simple description of the process and translate it into motion, you may just need to be pointed in the right direction, so here is a brief description of what the rest of this how-to will describe, so you can skip all of the step-by-step stuff.

The trick to exporting an OPML file from Scrivener involves the following steps:

  1. Compiling a copy of your draft with titles, and optionally other elements which will be placed into the [b]_notes[/b] field of each outliner line, using the basic MultiMarkdown exporter.
  2. Running Fletcher’s mmd2OPML.pl script against the MMD file.
  3. Open the resulting OPML file in your favourite outliner or OPML compatible application.

[size=200]Initial Setup[/size]

This is stuff you’ll only need to do once (unless you delete the script we’ll be installing). First you need to install a little script on your computer that will read an appropriately formatted file from Scrivener, and convert it to an OPML file. To do this, right-click on this link, and select your browsers equivalent of “Save as file”. In Firefox this is “Save Link As…”, in Safari you can use “Download Linked File” and skip the naming process. If you need to name the file, make sure to call it “mmd2OPML.pl”.

Now we want to place the file where it is easy to get at in the future. If you have a spot on your computer where you routinely compile Scrivener documents, that would be a good place to put it. If you are a geek and have a PATH already set up for handy scripts… you know what to to do.

Once the file is saved and moved to the right spot, find it in Finder. Now open Terminal.app, which you can find in your Applications folder, within a sub-folder called “Utilities”.

This program has a window with a “command prompt” in it. When you type things in here and press return, it will do stuff. Let’s do that now. Type in:


Make sure there is a space after the “cd” part. Now drag the folder that contains the script you just saved. If you have this open in a Finder window, you can just drag the folder icon from the title bar into the text area of the Terminal window. Drop the folder there, and you should see some printed text added to your command. It should look something like this:

cd "/Users/yourname/Documents/Scrivener Exports"

Press the [b]Enter[/b] key, and you should get a new command prompt. Your prompt is now “located in” this folder, which means anything you run here now assumes all of that text above is in front of any filenames you type in (it means other things too, but this is all that matters for this exercise).

For our second command, type in the below:

chmod +x mmd2OPML.pl

Then press [b]Enter[/b]. If you got a message stating that the file couldn’t be found, then you might have accidentally called it something else when you downloaded it. If you can see the file in the Finder window, check the name, fix it, and try again (you can use the UpArrow in Terminal to recall the last command).

For the curious, this tells your computer that this file is a script that can be run from the command line, much like a program, but it won’t get an icon in the Dock or anything like that.

If you didn’t get any messages at all, that’s good. It worked. Your Mac can be very terse at this level. :slight_smile:

That’s it for setup. Now we need to get a file out of Scrivener.

[size=200]Exporting from Scrivener[/size]

You should already be largely familiar with the process of compiling your Draft, so I’ll just point out the details you need to set, rather than talk you through the whole process.

What you compile will be what loads in your outliner, so select whatever portion of the draft you wish to deliver to the outliner, using the content tools. For included elements, you will always want “Titles” turned, and most likely for all three types, too. If you don’t have a title for a type that otherwise exports text, you’ll get confusing results. The OPML file will stash text from one section into whatever section immediately preceded it. So if you plan on exporting any non-outliner header content, make sure the title for that type is also selected. You can put whatever you want into the content area, just be aware that it will all be plain-text. In most cases, titles and maybe synopsis are good enough for an outline.

Now set the format to “MultiMarkdown”. Don’t choose any other specialised MMD workflows, just the basic one. We aren’t actually going to be using MMD for anything, we just need the title depth information, so that the outline will be properly hierarchal, which MMD gives us.

Compile that to the same spot you saved the script, from above.

[size=200]Converting to OPML[/size]

Open up Terminal again if it isn’t already. If you closed it, you’ll need to issue the “cd” command again, following the above instructions. If you’ve left it open from setup, you are already in the right spot.

Now type in the following command in Terminal:


Again, leave a space after it, and then drag the file you just compiled out of Scrivener, and drop it in the Terminal window. You should see something like:

./mmd2OPML.pl MyNovel.txt

Press [b]Enter[/b]. Again, unless something goes wrong, you won’t get any messages. If everything looks like it went okay, check back in your Finder window. You should see a new OPML file. From the above example, it would be named “MyNovel.opml”, but the actual name will be whatever you called your compiled file.

You should be done! Try opening this in your favourite outliner program. Each item in Scrivener’s binder will be a header, arranged in a hierarchy just like the Binder. If you chose to compile extra material from each section, and your outline supports OPML notes, you should be able to click on these headers and view the material you compiled into them.

Note: This script will put a Meta-Data item at the bottom of the outline, which you can safely delete, and should delete if you intend to send the file to someone else.


If you plan on doing this often, you might wish to save your export settings from Scrivener so you don’t have to keep looking up settings every time you need an outline.

As for the script, there are ways to hook it into various third-party launcher applications, like QuickSilver, LaunchBar, and so forth. Describing how to do that for each program is out of scope for this how-to, but with a properly configured system, you won’t ever have to use the terminal at all. You can just send your compiled .txt files to this script from the launcher tool and get an OPML file immediately.