GitHub and Markdown Editing

Here at MacStories, we like to write in Markdown. We appreciate the portability of plain text and how it enables us to try different text editors for iOS and macOS. Markdown and plain text are also easily scriptable, which saves us time when editing stories. Unlike most tech publications, we never collaborate on articles using Word or Google Docs because I don’t want to deal with rich text or HTML code. I like plain text and John Gruber’s invention so much, we even rebuilt MacStories to accept native Markdown text for every post.

Over time, as the MacStories team expanded and multiple writers had to provide feedback on drafts, my stance on not using collaborative rich text services was becoming a hurdle for everyone. For a while, if we wanted to check out a story someone was working on, we had to exchange files, create duplicates, and then compare differences between two text files with a diff tool on the Mac before sending the annotated version back. It was less than ideal.

The system we’ve been using over the past year relies on GitHub and has native support for Markdown and iOS. This is how we’ve been collaborating on stories – including my iOS 10 review – throughout 2016 for both MacStories and Club MacStories, and I couldn’t be happier with it.

GitHub is mostly known as a code hosting platform that enables programmers to collaborate on code and keep track of changes in shared projects called repositories. At a fundamental level, however, GitHub deals with text and compares differences between versions of the same text file. The same principles that allow programmers to host their code on GitHub can be used for collaborative Markdown writing, which is what we’ve done through several GitHub repositories.

Each MacStories writer has their own private GitHub repository where they can save drafts of articles currently being worked on. Other members are invited to the repository so they can read each other’s stories and provide feedback. We have a general Club MacStories repository that John and I use to assemble issues of our newsletter every week, and I also have a personal repository where I save drafts I would like others to read in advance.

Most programmers interact with GitHub from a command line interface (CLI) on desktop computers, which isn’t exactly user-friendly; much of the GitHub terminology is already quite obscure, and using the service from a terminal only adds to that complexity. Fortunately, there are great GitHub clients for iOS with a proper GUI to manage repositories and commits, making the GitHub experience on iOS visually appealing and integrated with iOS apps.

My favorite GitHub client for iOS is Working Copy by Anders Borum. Working Copy is a power-user GitHub client with Markdown support, app integrations, automation features, and ongoing support from its developer. Working Copy is one of the apps I’ve used the most this year and it played an important role in convincing me GitHub was the right service for us.

Working Copy lets you commit (save) files from other iOS apps with a share extension. This allows us to save Markdown documents from any text editor, screenshots from an email client or the Photos app¹², and so forth. As long as a file can be shared with extensions, we can commit it to our repositories with Working Copy.

Both Markdown files and images can be committed to a repository with the Working Copy extension.

This even works for overwriting an existing document with a new version: if I have an updated draft of a document I’ve already saved in Working Copy, I just need to share it to the app again, tap the existing file, and commit it to add a new version.

Overwriting a text file with a new commit from Ulysses.

The most useful features of Working Copy are revealed in the app. For every file, Working Copy keeps a list of commits (versions) from GitHub and allows you to view titles and comments for each version. Then, the best part: Working Copy supports GitHub’s diff highlights for individual words in addition to entire paragraphs, which is exactly the kind of tool we needed for collaboration. Not only can Working Copy highlight in red/green the paragraphs that changed from one version of a file to another – it can also highlight individual word changes with a darker shade.

Diff highlights in Working Copy.

Working Copy’s diff support has been a boon for how we edit Markdown and collaborate on articles. We can keep track of every edit and comment in a centralized location without creating duplicates. Working Copy makes it easy to follow the evolution of a document through multiple commits; every writer can chime in with their own suggestions and Working Copy will handle file merging and conflict resolution thanks to GitHub. Version control and diffs are integrated in the same app, and everyone is always looking at the same (and most recent) copy of a file. Thanks to Split View on the iPad, I can keep iMessage or Slack open on one side, put Working Copy on the other, and discuss edits and comments with someone else.

Multiple commits from different writers.

Working Copy supports Markdown syntax highlight and it ships with a basic text editor, but I prefer to read and edit articles in other apps. There are a few options available and they’re all made possible by Working Copy’s integration with iOS frameworks.

Working Copy can be used as a document provider to import files from repositories into external apps. Furthermore, files provided by Working Copy can be opened and edited in another app and the changes will be reflected directly in Working Copy; the app essentially gives access to its sandbox scoped to an individual file.

iA Writer is one of the few text editors I know that supports this “open and edit” mode: by tapping File > Open in iA Writer, I can select Working Copy, pick a file, and iA Writer will open it without creating a duplicate.

Opening a Working Copy document in iA Writer via the document picker.

In this case, iA Writer is accessing a file directly in Working Copy. I can read, edit, and preview the document in iA Writer and every change I make will be saved back into the file stored in Working Copy. With this system, I can replace Working Copy’s barebones text editor with iA Writer’s richer selection of editing tools and beautiful interface. This is my favorite way to read and edit longform pieces from other writers, and it’s all based on a solid GitHub workflow for iOS.

I can even manage entire repositories as bookmarked folders outside of Working Copy. This is one of the most impressive implementations of document providers I’ve seen to date. Textastic, the popular code editor for iOS, can open repositories from Working Copy and save them as bookmarked locations in its sidebar.

This file, displayed in Textastic, is stored in Working Copy.

Think of these folders as aliases of a document provider’s sub-directory that are automatically updated alongside the original storage. I can open a Working Copy repository in Textastic, create directories, move files around, and even edit text documents with Textastic’s own editor instead of Working Copy’s.

Changes made in Textastic (left) are reflected in Working Copy’s repository.

As with open mode in iA Writer, any change I make in Textastic is saved back into Working Copy thanks to the iOS document provider API. I don’t have to create duplicates or copy files around with extensions. Every week, I archive old GitHub documents from Textastic on iOS, committing changes in Working Copy with GitHub notifications that are delivered to multiple Slack channels at once – no Mac involved.

I wouldn’t be able to switch to any other collaborative Markdown environment now. Working Copy and GitHub have enabled us to be faster and more consistent at proofing each other’s stories with a fantastic set of integrations on iOS. As a side benefit, relying on GitHub for collaborative editing has resulted in a third layer of backups for my drafts and it’s making me consider GitHub as an internal wiki tool to create nicely formatted Markdown guides for the MacStories team.

There’s also an argument to be made about document providers and filesystem preconceptions on iOS. I bet most iPad users have no idea that document providers can be so flexible these days – in fact, I believe a lot of iOS app developers don’t even bother to add deeper support for document providers. But as Working Copy, Textastic, and iA Writer show, it’s possible to work with the same version of a file between multiple iOS apps now – with a streamlined workflow that is comparable to a Mac. I wish more app developers and Apple itself would consider this.