Edit Mac Scrivener 3 With iOS Ulysses, Part 3: Setting Up Sync #amwriting

Scrivener and Ulysses CAN get along

Articles in this series:

Part 3: Setting Up Sync


In Part 1 of this series, I talked about changing your Scrivener habits in order to edit with Ulysses, eventually. In Part 2, I talked about changing your existing project so that it compiles with the Scrivener “Convert MultiMarkdown to Rich Text” (MMD→Rich Text) compile option ON, and so that it syncs as smoothly as possible with Ulysses.

If you’re new to my articles on how to edit Scrivener projects with Ulysses, please review “Is this workflow for you?” in Part 1. I strongly recommend you make the changes to your existing Scrivener project that I suggested in Part 2 before proceeding.

If you need a review of Markdown, and of MultiMarkdown tables, you can find them here:

Notes on iCloud Drive, Dropbox, iOS, and Ulysses

The good news is that this process is completely independent of whether you choose iCloud Drive or Dropbox for your sync location. Use whichever you like; I won’t distinguish between them in the rest of this article. However, as of this writing, there are only two other cloud services that I know will work: Working Copy or Secure ShellFish. Ulysses may add another, but hasn’t done so yet.1 You don’t need to have Dropbox installed on your iOS device or devices, however, so that if you’re using a free Dropbox account, your iOS devices won’t count against your three-device limit.

Preparing Your Laptop or Desktop Computer

Dropbox Prep: You must have Dropbox installed on your Mac, so that you have a Dropbox folder available on your hard drive or SSD.

iCloud Drive Prep: None needed, really, other than turning iCloud Drive on in your System Preferences.

Create a Sync Folder for Your Project

We’re going to use Scrivener’s “External Folder Sync” feature to set up sync with Ulysses. The initial setup must be done on the Mac, and mostly from your Scrivener project. External folder sync is a project-based feature, so you’ll need to set up sync separately for each project you want to edit with Ulysses.

If you’ve never used External Folder Sync before, please review Section 14.3, “Synchronised Folders”, in the Scrivener Manual.

  1. In Finder, somewhere inside your chosen cloud service’s folder, create a new folder with the name of your project (hereinafter referred to as “MyProject_Sync”.) I’m not going to tell you how to organise your cloud service’s folder—create inside the cloud folder wherever it makes sense to you.
  2. From this point onward, we’ll be working in Scrivener with the project you want to sync open. First, let’s set up our export options to work with Ulysses. Use the menu item Scrivener→Preferences… and move to the “Sharing” panel. In the “Sync” tab, turn on the option “Convert text inside (()) and {{}} to inline notes when using plain text.” Turn this on, because it will let us use Scrivener’s inline annotations and footnotes as we discussed in Part 1 and in Part 2. The panel should look like this:
    Scrivener Preferences dialog shows turning double parens and double braces ON for External Folder sync
  3. In Scrivener, choose the menu item File→Sync→With External Folder… . You’ll see this dialog:
    Option-by-option illustration of how to set up Scrivener External Folder sync for Ulysses
    Let’s take each option and see how best to use it with Ulysses.

    1. “Sync files in this project with external folder:” – Click the “Choose…” button here, and you’ll get the standard Mac Open File dialog. Navigate to the folder MyProject_Sync you created in step 1 above, and with that folder selected, click the “Open” button. You should see the path to your folder appear in the text box.
    2. “Sync the contents of the Draft folder” – This is your work-in-progress. Turn this ON.
    3. “Sync all other text documents in the project” – This would be all your notes that are in text documents, your front matter, and your back matter. If you’d like to be able to review these files in Ulysses, turn this ON, otherwise leave it OFF.
    4. “Sync only documents in collection:” – This is how you limit what gets synced. If, for example, you want your notes in Ulysses but don’t want your front and back matter, set up a collection (See Section 10.2, “Using Collections”, in the Scrivener manual) that contains all your Draft documents and only the Notes documents that you want to be able to see in Ulysses.2 Choose that collection from the dropdown menu and turn this option ON. Otherwise, leave it OFF and everything gets synced. You can always change this later if you change your mind.3
    5. “Prefix file names with numbers” – this is up to you. If you turn this on, there will be a number (representing Scrivener Binder order) at the front of each file name when you look at it in Ulysses. By then setting Ulysses to sort by file name, you can see all your documents in their Scrivener Binder order. I find this very useful indeed, and always keep this option on, but decide for yourself. You can always change your mind on this.
    6. “Take snapshots of affected documents before updating” – I strongly suggest leaving this ON. This Scrivener option is what will let you quickly recover from any accidental formatting loss from Ulysses. Once a week, I use the Documents→Snapshots→Show Snapshots Manager dialog to clean up automatic snapshots I no longer need. Learn more in the Scrivener manual, section 15.8, “Using Snapshots.”
    7. “Check external folder on project open and automatically sync on close” – I recommend leaving this ON. This is where the automation happens on the Scrivener side of things. You’ll need to remember to close your project when you switch to Ulysses for the day, or whenever. If this just isn’t going to happen for you, there’s a setting for that – in Scrivener→Preferences, “General” panel, “Automatic Quit” in the sidebar. Choose an auto quit interval that’s not so short that it will annoy you but not so long that you’ll be typing away in Ulysses before it happens.
    8. “Import new non-Draft items into” – This needs a bit of explanation. (If you’re not syncing your notes and such, this won’t apply to you.) Any new document you create in Ulysses that you put into the Draft folder in Ulysses will show up at the bottom of the Draft (or Manuscript) folder in Scrivener, and you’ll need to sort it into your project structure. But if you do sync notes, this lets you choose which folder any new note you make will appear in Scrivener. The Research folder is a good option.4
    9. “Format for external Draft files” and “Format for other external files” – Ulysses can’t read Scrivener “.rtf” files any more than Scrivener can read Ulysses’ native format (“.ulyz”). The format that both can read and write is “Plain Text” with extension “md”. Set this up here.
    10. “Automatically convert plain text paragraph spacing” – Turn this OFF.5
  4. Re-check your settings, then click the “Sync” button. Scrivener will write out Markdown files for all the documents you included in sync. They’ll appear in two new folders, “Draft” and “Notes”, that Scrivener creates inside the folder you created in Step 3.1 above. If you’ve decided to sync a lot of files, this may take a while the first time.
  5. Close your Scrivener project! We’re moving to Ulysses at last!
Connect iOS Ulysses to Your Sync Folder

For each iOS device you’d like to use with your new Scrivener sync folder, you’ll need to set up Ulysses to use Ulysses’ own External Folder feature. (It’s unfortunate that it uses a similar name to the Scrivener feature, because it’s really quite different.) If you’ve never used Ulysses’ External Folder capability before, I suggest you review its tutorial on the Ulysses website.

  1. Tap the gear icon in your Ulysses library panel.
  2. In the Settings popover, tap the Library item.
  3. Connect Ulysses to the sync folder:
    • If you’re using iCloud Drive or some other non-Dropbox cloud service:
      • Tap on the “Add from Other Location…” item. You’ll be taken to the Apple Files app interface.
      • Navigate to the folder you created in Step 3.1 above. You’ll see the new Draft and Notes folders inside, but be sure the top level folder “MyProject_Sync is selected.
      • Tap “Done” in the upper-right corner. You’ll be taken to the folder settings panel.
    • If you’re using Dropbox:
      • Tap the “Add from Dropbox…” item.
      • If you haven’t connected Dropbox to Ulysses before, sign in to the Dropbox account that you saved your sync folder to.
      • Navigate to the folder you created in Step 3.1 above.
      • Tap the “MyProject_Sync” item at the bottom of the panel. You’ll be taken to the folder settings panel.
  4. In the folder settings panel:
    • Change the icon if you like.
    • Sort by title if you like (to take advantage of your Binder order numbers.)
    • Set “Read and Write Markdown Files” to ON.
    • Set the “Default File Extension” to “.md” to match what you told Scrivener.
    • Turn “Create Reference Links” on if you like (I don’t, but it’s a matter of personal preference. Review CommonMark if you don’t remember the difference.)
    • Turn “Always use Fenced Code Blocks” ON. This will make using code blocks to mark off styled text in Scrivener much easier.

Repeat the above for every iOS device you want to use to edit your Scrivener projects, and for each Scrivener project you want to edit.

There you are! When you want to work on iOS Ulysses, close your project on your Mac, or use the menu item File→Sync→With External Folder Now. (You can put this in Scrivener’s toolbar if you like.) When you want to incorporate your changes from Ulysses, open the project on your Mac or again use File→Sync→With External Folder Now.

A Warning About Document Titles/File Names

Are you letting Scrivener automatically name some of your files? Scrivener External Folder Sync produces long, long filenames in that case, like this: “068 I opened the sitting room drapes and settled myself into my own armchair. I... [85].md

That final “[85]” is Scrivener’s internal file ID and without it, your changes won’t get synced back to your original file. Instead, you’ll find a new document with your changes.

The problem is that Ulysses can’t handle such a long filename, and will truncate it to something like: “068 I opened the sitting room drapes and settled myself into my own ar.md” It loses Scrivener’s file ID (“[85]”) and thus confuses Scrivener on the return trip.

My workaround is to edit the filename myself, to “068 [85]” (in the first line in the Ulysses sheet) before editing anything else in the file. Scrivener is perfectly happy with that, and my changes are synced normally. Another solution would be to name all your files yourself in Scrivener with somewhat shorter names.

If you accidentally have a file ID truncated, all is not lost. You’ll find the “new” document at the bottom of the Draft folder in your Binder. You’ll be able to tell that it’s not connected to the original when you’re doing your “return from sync” check because you won’t see any snapshots in the Inspector for it. Take a deep breath, and find the original in its place in the Binder. Now, you’ll do manually what External Folder sync would have done:

  1. Make a snapshot of your original (“Real_File” in this example), naming the snapshot whatever you like. (“Lost_ID” for this example.)
  2. Open the new version from Ulysses (“Duped_File” in this example), select all its text, and copy to the clipboard.
  3. Return to Real_File, select all its text, and paste in the text from Duped_File.
  4. Compare the text you just pasted to the Lost_ID snapshot, restoring formatting if you need to.
  5. Move Duped_File to the Trash, and then delete it from the Trash (so you won’t get confused in future). You don’t need it any more; you’ve incorporated your changes into the original and have a snapshot of that original before changes.
Best Practices
  • Avoid using Scrivener features for things that Markdown and Multimarkdown plus MMD→Rich Text compile can do. Lists, tables, images, external links, italics, and bold text are best done with Markdown features rather than with Scrivener.
  • Remember to mark paragraphs containing Scrivener styled text, Scrivener internal links, or Scrivener-inserted graphics when you add them in Scrivener.
  • Avoid editing paragraphs containing Scrivener styled text, Scrivener internal links, or Scrivener inserted graphics with Ulysses.
  • If you can’t remember to close your projects so that Scrivener writes out changes (or use the File→Sync→With External Folder Now command), use the Scrivener→Preferences→General “Automatic Quit” option.
  • When you return to Scrivener after editing with Ulysses and External Folder Sync gets run, you’ll be shown an Updated Documents list in the Binder area. I suggest checking each document against its most recent snapshot in the Inspector, to spot any formatting, image, or link loss and correct it quickly before you forget! (Read more in the Scrivener manual about using snapshots in section 15.8.) This seldom takes long and is good insurance.
  • To keep project size and backup time lower, once a week use Documents→Snapshot→Show Snapshot Manager in Scrivener, after you’ve checked your most recent Ulysses updates. Delete older “Pre-Sync External File Version” and “Pre-External File Sync Overwrite” snapshots. Your own caution and experience will be your best guide as to how to balance project size, sync speed, and safety.
  • Be aware of your Ulysses filename length. If a filename ends in “…” before the ID number in brackets, edit the filename in Ulysses to contain only the ID in brackets and the front Binder order number (if you’re using it). This will prevent the file from getting disconnected from its Scrivener original.

  1. You could as easily be using Scrivener for Windows, and this workflow would still work on the iOS side. I’m not addressing this for two reasons: First, I don’t have a Windows device so I can’t address Windows-specific Scrivener procedures. Second, using Ulysses on iOS has its own limitations (not unlike iOS Scrivener.) There are certain preferences that can only be changed in Mac Ulysses—and Ulysses does not have a Windows version, nor is it likely to in future. All my directions will assume that you are using Mac Scrivener. 
  2. I use a saved search for this. I added a keyword, “SYNC”, to the files I’d like to have in Ulysses, searched for that keyword in Project Search, then at the very bottom of the project search context menu, saved the search as a collection. I don’t have to adjust the collection, just add the keyword to each new file as it comes back to Scrivener. There are many other ways to set up project searches that may work well for you. Read more detail in the Scrivener manual, section 10.2.4 “Saved Search Result Collections” and section 11.1, “Project Search.” 
  3. Perhaps this is a good place to talk about Scrivener folders. You might be tempted to eliminate your folders from the files you’ll be syncing – there’s no text in them, right?

    Well, not necessarily. I often put notes into my folders – they’re just specially tagged text files in Scrivener, after all. Some people put things like chapter introductions or epigrams into them. More than that, though, they’re “markers” – even though they don’t show up as indented in Ulysses, I can use them to show me where I am in my document structure. This is one of those things that’s up to you. Me, though, I sync all mine, even if they’re empty. 

  4. If you’d like to have new Draft files show up in an “Inbox” folder instead of at the bottom of the Draft folder, you can do that. Set up a new top-level folder in Scrivener called “Inbox”, outside the Draft folder. Point this setting to that folder. Then, when you create a new Draft “sheet” in Ulysses, move it in Ulysses to the Notes folder (or create it there in the first place.) On return sync, Scrivener will take those new files, put them in the Inbox folder you’ve set up (along with any new Notes files), and from there you can sort them back into your project structure where they belong, be they draft or notes.

    If you use this option, do use a regular collection to limit your sync rather than a saved search. Scrivener will automatically add new files to the collection. 

  5. This would convert single enter characters to double enters on outgoing sync, and reduce double enters to single on incoming sync. You’ve already done this because Scrivener MMD→Rich Text compile requires it. Turning this on will mess up your documents’ appearance in Ulysses and make it harder to edit in Ulysses and have the results compile in Scrivener. OFF. 
gaelle kermen

écrire en liberté


Digital Artist

Blissful Scribbles

Musings through the journey of writing my first novel

The Cat's Write

Milly Schmidt

A writer & her adolescent muse

writing, writers, & worlds (of my own making)

Bestselling Author

of Faith, Fantasy, and the Fantastical

Can Anybody Hear Me?

Uncovered Myself One Pound at a Time; Discovering Myself One Day at a Time

Kanundra's Blog

Writing and life. Life and writing.

%d bloggers like this: