Writeas/WriteFreely iOS Publishing Workflow

Editorial Git - Wood
Editorial Git - Wood

Demonstrating the particulars of a version-tracked Markdown publishing process - including the full extent of parallel research, documentation, and web development - optimized for and entirely contained within iPhone (for the insane.)

[[Notes: Writeas/WriteFreely iOS Publishing Workflow]]

When Extratone was running on WordPress, I found myself writing about it all the time, partially because I was learning how broken the web had become (largely thanks to WordPress,) but mostly because of all the drama surrounding the endeavor. There’s a lot to say about bad software, so writing about it is easy - I understand this truth, intimately - but The Psalms’ number one mandate is to celebrate uniquely clever, undercovered solutions, and by golly, one has been staring both you and I in the face for years, now, without mention on this blog. This year’s dive into iOS has inadvertently lead to many unexpected avenues of exploration, but the one that has underpinned them all has been using my iPhone 12 Pro Max as (essentially) my primary machine for all of it: research, notes, (astonishingly) working in public via Git, composition, publishing, and spreading it all around. Write.as - the SaaS implementation of WriteFreely - is not only capable of supporting this workflow - in my extensive use, I have discovered a path for which it is particularly optimized, I think. As I have committed to stop taking the Write.as suite for granted and become a more actively productive member of its community, I’d say it is the perfect time (for once) to let loose and zoom all the way in.


Excess mode

The above apps are all that’s needed if your end goal is just publishing and editing to Write.as or your own WriteFreely server, but if you want to go as all in as I have - or, notably, if an iPhone/iPad is the only computer you have access to, for whatever reason - you’ll probably be astonished (as I was) at how well you can accomplish just about everything involved in development on your goddamned cellular phone, these days: editing CSS themes, configuring Javascript additions, parsing JSON analytics data exports, extensive performance testing, scraping/archiving, fileserver management, and on and on…

There is a limit, but it feels completely absurd to define: you can’t actually host a WriteFreely installation on your phone. That is to say - you can’t really use your cell phone as a fucking server… At the moment, anyway. Considering you can run the Write.as command line client in a Linux shell and interact with the service via the Write.as API… on your phone… Who is to say, really, if running a persistent Linux server in the background will be possible on iPhone in the near future?1

All that said, here are some apps enabling mobile web development:

Drafts and Git on iOS
Drafts and Git on iOS

Before I go on, I must once again make a big effort to accredit the very same Federico Viticci: I began this guide thinking his original Markdown + Working Copy x GitHub iPad Pro publishing workflow dated back to November 2018, but I clearly need to pay more mind to hyperlinks because it actually [originated sometime in 2016]((https://www.macstories.net/stories/one-year-of-ipad-pro/6/#content), which is… An entirely distinct kettle of fish.

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.

It was very recently that I observed in my notes for “Editorial Git” that The Psalms might have been the longest-running implementation of Git in the “real world” writing process as opposed to the the mostly-demonstrative discourse from a microera around 2018-2019 when Markdown and Git were considered as the future of academic publishing. As far as I can tell, the conversation was largely prompted (or substantially revived, at least) by WashU professor Ed Hagen in an essay/blog post entitled “Should scientific publishing move to Github and friends?,” which gathers a variety of references to projects exploring parallel avenues and comprehensively proposes a theoretical workflow. Since the more recent of the aforelinked Federico posts describes his use of the very same services (Working Copy and Github,) is freely available, impeccably well-considered, and beautiful to read, I’m going to proceed as if I have nothing original to contribute to that conversation (because I don’t.)

I’d ask that you proceed with the knowledge that this guide is far from absolute - you can and should pick and choose different components to form your own workflow - and that it is definitely not exclusive to Write.as/WriteFreely, considering our end output is markdown-formatted text. I have chosen to frame it around the .as suite because it (debatably) saved my life and I am therefore quite personally invested in the growth of its userbase and the health of its community. On that vein, I’ve recently committed to starting the WriteFreely Community Discord Server and published a new version of this blog’s theme which I hope will prove useful to newcomers interested in customizing their Write.as/WriteFreely blogs.

I also want to make it clear that this guide was written as a exploration of what is technically possible on iOS/iPhone at the moment, not what I’d consider actually advisable. While I myself have been playing around across the spectrum of tools listed here on my 12 Pro Max - including drafting all of this guide, itself, as well as the vast majority of my iPhone × Music overview - I can’t say I expect to continue using my cellular phone in this way except for any special away-from-desktop circumstances.

WriteFreely for iOS
WriteFreely for iOS


The most logical layout of this guide, I think, is by order of the tasks you’re most likely to spend the most time engaged upon first, with the essential consideration of how likely you might be to actually whittle away on said task using your iPhone. Composition, then - that is, pounding out the actual copy - is where we’ll begin. The original design for WriteFreely (including its iOS app) intended for users to simply compose directly within its interface. From my observations of and conversations with other Write.as/WriteFreely users, the vast majority of content published to date on the platform was, indeed, composed directly to its own editor. Those of you who find this entirely sufficient might choose to stop right here! You will undoubtedly find a far less distraction-stuffed, generally more peaceful writing experience.

For the rest of us, WriteFreely for iOS still serves as the ideal method of interacting with our Write.as blogs. Technically, our only requirement, then, is that our final publish-ready text be in Markdown format (along with a handful of Write.as-specific considerations, which we’ll cover shortly.) To actually compose the text, one’s options are vast. There’s a special place in my heart for Bear and developers, Shiny Frog, who are notably in the process of developing an entirely new editor for Bear from the ground up. I am currently using agiletortoise’s ever-venerable and exceptional Drafts, which is quite possibly the most extendable text manipulation software available on any platform. Both of these are optionally Markdown-native and feature-packed, but one needn’t necessarily go their Big, Premium Writing Solution way. Sam Oakley’s Pretext is an elegantly simple Markdown editor that works directly within iOS native Files app as is Marco Albera’s Typewriter. (Being spoiled for choice in terms of clever iOS text editors is a precious situation which we should do our best not to take for granted.) For those intending to integrate Git into their workflow, this ability handily removes a few barriers.

The Non-Markdown-Native Options
The Non-Markdown-Native Options

Trust me, I know intimately just how weighty personal preference can sit against logic/time/sound advice when it comes to text editing/word processing software. Though I would all but insist you give Markdown the olé college try and then some, if you’re simply too attached to another format - Apple Notes, Notion, or even Microsoft Word, for instance - WriteFreely and I can accommodate you. (Frankly, though, as a WriteFreely/Write.as user, forgoing Markdown is sortof missing the point…) The latter is going to be the most problematic, by far, necessitating (in my opinion) pandoc to form any sort of coherent workflow. An academic named W. Caleb McDaniel detailed his pandoc-on-iOS process way back in 2013, though the apps/services listed are all astonishingly still available.

WriteFreely-Specific Considerations in the Body

When I first started playing around with a free Write.as blog, years ago, perhaps the first “quirk” of the CMS to trip me up was its complete separation from the suite’s image-hosting counterpart, Snap.as. The fact that one had to upload to Snap.as, actually copy the embed code and paste it in the intended Write.as post - without any sort of pre-publication preview of how it’d look in the body - all seemed very incomplete to me. As the new Write.as editor begins to implement directly uploading, today, however, I have been begging for this old method to remain untouched because it is actually absolutely ingenious. When I need to add an embedded image to the current Drafts Draft I’m composing in now, for instance, I can upload it straight to Snap.as, copy the Markdown embed code (here’s the full embed code for the image embedded above, for example: ![The Non-Markdown-Native Options](https://i.snap.as/QtNWXN6f.png)), and paste it right here, locally, just as it will be in the final draft. When I use Drafts’ preview function, it loads the image directly from Snap.as - from the very same place your browser loaded it when you navigated to the finished Post. This method reduces waste and makes my text ridiculously portable right from the get-go.

My Snap.as image addition workflow on iPhone is made especially smooth by a single-action Siri Shortcut entitled “Snap.as” which I’ve placed on one of my homescreens and customized with the Snap.as logo. Using Google Chrome - which I’ve kept on my device exclusively for this purpose - the Shortcut simply opens the Snap.as homepage (the upload interface for logged-in users.) From there, I can upload any number of images under 12.5 mb and add them to one of my loosely-organized Galleries. I then navigate to the gallery holding the new image, add a caption, and copy the embed code. Once I have that code stored in my clipboard manager of choice (we’ll talk more about those eventually,) I am completely done with that image! Those of you with WordPress experience will find this magical, I promise.

Embeds on Write.as have been in a state of flux since Matt first announced Embedly integration earlier this year. The intention behind this change was to eliminate the need to mess around with html/iframe code and allow one to embed a piece of content from a specified list of sources by simply including its raw, unaccompanied URL in the text. As of this moment, the sources I regularly use are all functioning superbly: Twitter, YouTube, SoundCloud, Bandcamp, and Imgur. Notably, one must use full YouTube links (youtube.com/watch?v=qVvSZv9g3oQ) for videos to embed. The “Expand URL” Shortcut found in the default Siri Shortcuts gallery can be used to convert the youtu.be shortlinks outputted by the YouTube for iOS app into these full URLs.

I have found tremendous success in embedding simple HTML5 audio players using <audio> pointed directly toward .mp3 files hosted on GitHub.

<audio controls>
  <source src="https://google.com/chingy.mp3">

  1. I decided not to explore whether or not the jailbreak community has addressed this. 2021-06-23  ↩