Open-in-Place and File Bookmarks

In recent years, Apple has begun offering third-party apps new tools to overcome one of the longstanding limitations of iOS file management: the inability for apps to access and edit files created by other apps. To achieve this, Apple tackled iOS’ sandboxed model on two fronts using the open-in-place and file bookmark APIs, two different but related technologies that enable apps to open and modify files or directories stored outside their own sandboxes.

Open-in-place and bookmarks are technically different, and they’re based on security and privacy principles (such as security-scoped URLs) that I won’t cover in this article. Instead, I’m going to focus on what these features mean for the actual user experience and how they’ve helped me build a superior writing workflow where multiple apps can collaborate with each other on the same documents.

Open-in-place and bookmarks have two aspects in common: they cannot be initiated programmatically by apps without the user’s explicit consent, and they depend on the Files picker to select the document or directory you want to open in another app. Put simply, as of iOS 12, the only way for an app to load an external file or bookmark to an external directory is to manually select it first. There’s no concept of full disk access on iOS (yet?) and these permissions are granted on a per-item and per-app basis; on iOS, you cannot do what you could do on macOS by telling the system to “give this app full, persistent access to all my files and folders”. Each iOS app can visually represent open-in-place and bookmarks differently, but they always have to go through the process of letting the user pick files or folders from a Files view first. Furthermore, while open-in-place is optimized for opening one document at a time, editing it, and saving it back to the original location, bookmarks are ideal for persistent access to entire directories of documents that can stick across app relaunches and device reboots.

I began researching open-in-place as a way to simplify editing of Markdown documents when we started using GitHub repositories (accessed via Working Copy on iOS) to collaborate on article drafts. The beauty of open-in-place is that, in addition to iCloud Drive, it can also be implemented by third-party file providers, which can confirm to the system that their documents support being opened in-place by other apps. Working Copy began offering a file provider extension with iOS 11, and it also supported open-in-place, so I started wondering if I could edit Markdown drafts from GitHub (accessed by Working Copy) with an external text editor (Working Copy’s own editor isn’t optimized for prose), but without having to copy and re-export text files each time.

As it turns out, that was a perfect use case for the open-in-place functionality, which is designed to let apps open and edit original files without importing a copy in their own containers. At first, I came across Pretext, a plain text editor by Sam Oakley that uses the document browser to store text files in iCloud Drive or edit text files created by other apps and stored in iCloud Drive or third-party file providers. What makes Pretext unique is how it does away with a custom library altogether and fully embraces the document browser and open-in-place to make it as easy as possible to edit any text file available on my iPad.

Pretext’s dark-themed document browser showing text files from iA Writer’s folder.

Pretext requires effectively no setup: as a front-end for Files and Markdown documents, the app is immediately ready to go without having to configure custom Dropbox sync or another self-contained library. As we noted in our original coverage on MacStories, Pretext can be used as a sort of TextEdit for iOS that can open and edit any text document available in the iPad’s filesystem.

A document from iA Writer (left) opened in Pretext via the document browser and open-in-place (right).

When I discovered Pretext, all I had to do to start editing Markdown files from Working Copy was navigate to the Working Copy location in the document browser, select the Club MacStories repo, and tap on a text file. Because Working Copy supports open-in-place, Pretext can open any file directly without importing it to its iCloud Drive folder. After making changes to a file from Pretext, edits are automatically saved back to the original document in the Working Copy file provider, where I can commit them (i.e. save them) to the repository from the document browser itself.

Accessing the Working Copy file provider from Pretext’s document browser.

Browsing the contents of a Working Copy repo within Pretext.

Thanks to open-in-place, Pretext can edit documents from Working Copy directly.

The Working Copy file provider can mark documents with uncommitted changes, and it also makes its Commit feature available system-wide in every instance of the document browser.

I can commit and push files to GitHub using the Working Copy file provider extension while in Pretext’s document browser.

Pretext is, in many ways, the perfect demo to showcase the advantages of the Files document browser and open-in-place to achieve a seamless, reliable editing workflow that was unthinkable until a few years ago on iOS. To this day, Ryan uses Pretext in combination with Working Copy’s file provider to make edits to all my drafts and commit them to our shared GitHub repository.

After using Pretext for several months, and following my explorations of different text editors in 2017 and 2018, I settled on the text editing and collaboration workflow that I’m still using today, which revolves around iA Writer, iCloud Drive, and Working Copy – all powered by Files and open-in-place. In fact, integration with iCloud Drive and other apps through open-in-place is among the reasons why I’m sticking with iA Writer as my favorite Markdown text editor everywhere.³

iA Writer does not support the document browser; instead, it syncs documents via iCloud Drive and uses a dedicated document library UI to let you browse folders, hashtags, smart folders, and other locations that wouldn’t be supported by the document browser. The sidebar used by iA Writer to manage your library is the kind of custom, more advanced interface I was referring to when I explained why the document browser is not necessarily a good fit for every app.

iA Writer.

In its sidebar, iA Writer features an ‘Open’ button that summons the Files picker to open any compatible text file from any file provider in-place, without importing the original to create a duplicate. The Files picker comes up modally as a new window on iPad and allows you to browse any directory or third-party file provider to open text files that iA Writer can edit.

Opening files from other apps in-place with iA Writer.

Once you open a text file in iA Writer, it’s loaded in a ‘From Other Apps’ screen that lists all the other documents you’ve opened in-place in iA Writer. You can make edits to an open document in the editor (which are saved back to the original file in its location by the open-in-place framework) and then swipe to close it. The “closing” action is labeled ‘Remove’ in iA Writer, and it’s different from deletion: iA Writer cannot delete files from their original location (such as another app’s iCloud Drive folder) but merely terminate its access to documents opened in-place. As long as they’re open in iA Writer, external files will be displayed in the app’s library, but if you want to re-open a file you previously removed, you’ll have to manually pick it from the Files window again.

A list of files from Working Copy opened in-place with iA Writer.

iA Writer’s support for external files and open-in-place is what I now use whenever I need to edit a Markdown document that was not originally created inside iA Writer. There are several advantages to this approach that I’ve learned to appreciate over the past year: I never end up with multiple copies of the same file scattered across different iCloud Drive folders; I can quickly open files on-demand, make changes, and save them back without ever seeing a share sheet or ‘Export’ menu; and, perhaps most importantly, I use one text editor with a consistent set of editing tools that I’m familiar with. If you’re a macOS user, all of this will probably sound unremarkable to you; as a longtime iPad user who’s been through the various iterations of Open In, iTunes file sharing (oh God no), and the share sheet, this a major change from the old ways of iOS file management, and one that I hope more developers will continue to implement in their apps.

iA Writer can go beyond open-in-place for individual files, which is where things get really interesting from a file management perspective and where the concept of file bookmarks comes into play.

In addition to single files, third-party apps in iOS 12 can have persistent access to entire folders from an external location and open the files contained in them. Each app names this feature differently, but it’s always based on the bookmarks API, which creates a private, secure URL for an app to load and list the contents of another folder stored somewhere else in the Files app. iA Writer refers to this functionality as external locations, Working Copy calls it synced directories, and Scriptable labels it bookmarks, but in every case it’s based on the same Files technology. And I’m not exaggerating when I say that, more than open-in-place, this has been the most important improvement to my file management workflow in recent years.

Despite the naming and implementation differences across apps, bookmarks for external folders always start the same way: a Files picker opens and you have to manually select the folder – not the file – you want to grant an app persistent access to. In iA Writer, this can be done by tapping ‘Edit’ in the sidebar then ‘Add Location’, while Working Copy features a ‘Setup synced directory’ button as part of the main menu of the ‘Repositories’ sidebar.

Adding an external library location in iA Writer.

Setting up a bookmark to a folder in Working Copy.

Once a bookmark to a folder is created, the app that stores the bookmark gets access to all the files contained in the original folder and can edit them in-place without creating duplicates in its own storage. These are different APIs than open-in-place and are based on different frameworks, but in practice bookmarks are sort of like “open-in-place for folders”, with the added benefit that bookmarks are permanent (they keep working even if an app quits or your device restarts) until they’re manually deleted by the user.

Folder bookmarks enable a two-way communication between apps that has allowed me to fundamentally rethink how different apps on my iPad can collaborate on the same set of documents.

The first step for me was making specific repos from Working Copy available as library folders in iA Writer. These are the repos that I share with individual members of the MacStories team and which contain Markdown drafts for articles that will eventually appear on the website. My goal was to minimize the back and forth typically involved with copying files, editing them, and re-exporting them, but I also wanted to have a faster system for viewing and editing multiple documents from the same repo at once, which would have been cumbersome to do via traditional open-in-place with one file at a time. Thanks to external locations in iA Writer, I was able to pick multiple repos from Working Copy’s file provider and bookmark them in the app’s sidebar.

Multiple locations from the Working Copy file provider opened in iA Writer as persistent bookmarks.

The same Working Copy repo being viewed in Working Copy (left) and in iA Writer as a bookmarked folder.

Now, whenever I want to check out the articles John is working on or the drafts we’re preparing for the next issue of our newsletter, I can simply open different folders in iA Writer and edit them. Because bookmarks support two-way sync, changes made from iA Writer show up as uncommitted edits in Working Copy when I later open the app; similarly, when I fetch the remote contents of a repository from Working Copy, the latest changes are merged in the repo and they automatically update the contents of the folder bookmarked in iA Writer. Essentially, the same folder is living in two places: Working Copy manages communication with GitHub and keeps track of changes; iA Writer is the text editor that I use to preview and edit documents from that folder.

This system has considerably sped up how I manage text files where multiple authors collaborate remotely using git, and it’s all possible thanks to the underlying Files framework of iOS. But there’s more I’ve done to ensure that my drafts are also available for other MacStories writers to read and edit.

In Working Copy, you can set up external app folders as synced directories. This means you can effectively transform any iCloud Drive/file provider folder into a local repository managed by Working Copy. Here’s what I did: I picked the entire iA Writer folder stored in iCloud Drive and bookmarked it in Working Copy, where it became a local ‘iA Writer’ repo that I could use to commit changes, revert edits, and compare versions of text files using Working Copy’s built-in diff tool. Again, this is the whole iCloud Drive folder that iA Writer uses to store its documents library, only it appears as a persistent location in Working Copy.

The entire iA Writer iCloud Drive library as a local repo in Working Copy.

Next, I set up a remote connection for the bookmarked folder by giving it the URL of my private GitHub repository. Doing this tells Working Copy that a local directory has to be synced with an online repository so that there’s a common set of files between Working Copy and GitHub.

In Working Copy, I have one folder (‘iA Writer’) which is synced with an online repo (‘Ticci Drafts’):

iA Writer’s iCloud Drive library mirrored to GitHub (right) thanks to Working Copy (left).

Here’s why this setup is amazing: I can keep working in iA Writer as usual and my edits show up as unsaved changes in the iA Writer folder bookmarked in Working Copy. Every few hours, when I commit the changes in Working Copy and push them to GitHub, they’re also mirrored to my private repo, which Ryan and John can access to read the articles I’ve been working on. So instead of editing and exporting a new version of a document from iA Writer to override an existing one in my repo each time, I can just keep editing in iA Writer and remember to push my edits every couple of hours.

However, the opposite kind of sync can also take place: if Ryan has edited one of my files in the Ticci Drafts repo in GitHub, pulling remote changes in Working Copy will also merge Ryan’s edits back to the synced iA Writer folder, and therefore the iA Writer app itself. It’s almost as if Ryan or John can “collaborate” with my iA Writer installation, while in reality we’re using Working Copy and the Files framework as middlemen to handle reconciliation of changes.⁴

All of this may sound convoluted, and I realize that it’s quite the departure from what you may be used to seeing in iOS file management, but trust me: I set this up months ago and I’ve forgotten about it – the folder bookmark system is that reliable on iOS these days. This setup has lived through multiple iOS updates, system restarts, and app updates, and everything is still working as well as it did the first day. Sometimes I even forget that iA Writer’s document library is not a built-in integration of Working Copy. Thanks to this configuration of iA Writer and Working Copy, I’ve gained three total layers of backups for my documents (iCloud Drive, local repo, online repo) and, more importantly, I’ve streamlined my Markdown collaboration workflow without giving up the text editor I like.

I also want to highlight two other apps that have done an admirable job in implementing bookmarks for external folders: Textastic and Scriptable. As far as I know, Textastic was the first popular app to support open-in-place back when it first became available, and it later added support for opening entire folders too, which was advertised as an ideal companion for Working Copy for those who like to keep their code snippets organized with git.

Textastic supports both open-in-place for individual files as well as folder bookmarks.

Textastic is among the best code editors available on iPad, and what I particularly like about its implementation of open-in-place and bookmarks is how you can pick either files or folders from the same picker. Textastic does not have separate screens for external files and folders like iA Writer, which makes it easier to get started in adding external content to the app’s sidebar. In a very nice touch, Working Copy folders opened in Textastic carry the app’s icon, while iCloud Drive folders show the complete file path of the folder underneath their name. I don’t use Textastic in my daily workflow anymore, but it’s what I used to work with before iA Writer added integration with external folders.

Developer Simon Støvring went in a different direction with Scriptable, as I will highlight in one of the next chapters. Scriptable, a JavaScript IDE for iOS, can integrate with a plethora of native iOS frameworks including Files. In Scriptable’s settings, you can create bookmarks to external files or folders from any compatible file provider, which will give the app persistent access to that content once set up. What’s the point of doing this in a JavaScript IDE? Easy: with bookmarks, Scriptable is able to programmatically read from and write to folders other than its own iCloud Drive container – which is something that not even Apple’s Shortcuts app can do right now.

Bookmarks to files or folders can be set up in Scriptable’s settings.

You can see the full filesystem path to a bookmark using Scriptable.

As I’ll describe later, I’ve been taking advantage of bookmarks in Scriptable (which are, of course, created with a Files picker) for a variety of tasks including tagging PDF receipts in my Finance folder of iCloud Drive and saving screenshots into a sub-folder of iA Writer’s iCloud Drive container, which is how images for this story were organized. Scriptable’s adoption of bookmarks shows why Apple may want to consider a similar strategy for Files automation in the future, and it’s one of the ideas I’ve spent a lot of time optimizing this year.

Open-in-place and bookmarks for external folders have been two of the most impactful changes to my iPad workflow over the past year. The ability to open files and edit them without creating duplicates – whether they’re individual files or collections of documents in a folder – is a major leap forward for iOS file management, and one that I wish Apple would advertise more and implement in their apps as well.

While my system based on iCloud Drive, iA Writer, and Working Copy works well, the fact that I had to spend months researching this setup and wait for developers to support all the necessary APIs isn’t an ideal scenario. Adoption of open-in-place should be enforced at a system level for all third-party file providers, and Apple itself should do a better job at supporting open-in-place and bookmarks for external folders in their apps. Robust integration with these advanced Files APIs should be widespread and well-known among users and developers; instead, it’s currently limited to a handful of apps whose developers have done a lot of work to make it happen. I’m not sure how Apple could foster adoption of these features; perhaps assisting large companies such as Dropbox, Adobe, and Microsoft to ensure their apps and file providers have excellent support for modern iOS file management could be a good first step.

That being said, despite the little-known nature of open-in-place and bookmarks, it’s undeniable that iPad file management can be dramatically different from the limited system of the old days of iCloud Drive and duplicate documents. I had to change the apps I use and rethink parts of my workflow, which put me in an odd transition phase at the beginning, but I’m glad I embarked on this journey because I ended up with a vastly more flexible and powerful setup in the end. My wish is for all of this to become easier for all developers and users in the future so that we can stop thinking of iPad file management as a limited, one-document-at-a-time system, because it can be so much more.