Markdown Workflow

tl;dr

A document workflow using mostly Markdown files, iCloud to sync between devices and a cron scheduled git commits.

Background

This is an updated version of my personal document workflow. Originally I used Subversion to sync between computers, sort of a poor man’s self-hosted-Dropbox.

Considering what it was, it worked. There were some draw backs, like no (easy) access on mobile devices and Subversion was a bit of a pain with conflicts.

Git, iCloud, cron, iA Writer

I migrated my workflow to a Git server (GitLab specifically) and checked out the Git project into the iCloud directory, this synced the content between Apple devices.

My editor of choice on the MacOS desktop is BBEdit and still preferred for scripts and technical editing. However, for documentation and notes I have switched to iA Writer, due to its better Markdown support, iOS & MacOS versions and iCloud files support (some editors use databases to store data). Using Markdown and iCloud files means I am not locked into iA Writer as an editor.

I wanted to automatically check any changes into Git. After some testing, it appears that iCloud and Git play nicely together (at least as far as a single user editing mostly Markdown files goes).

Ideally, a MacOS machine would always be available to sync with iCloud and then commit to the Git server. But for now I have a cron job running on my laptop and commits / pushes will succeed when it is connected to the internet.

Setup and Configure

The following is a description of how to setup and configure Git, iCloud, cron and iA Writer.

Tested with the following versions:

  • MacOS Mohave 10.12
  • iOS 12.3
  • GitLab version 11.11.0
  • Git version 2.20.1
  • iA Writer 5.2.7

1. Enable iCloud Drive on your various devices and create a test readme.md file on a MacOS device. Confirm that the file appears on other devices, either in the Finder iCloud folder or in the Files app on iOS.

2. Create a Git project on a server (like GitLab or Github). On MacOS, checkout the project in the iCloud Drive directory.

iA Writer uses a specific directory in iCloud to store files. The Git project needs to be checked out in ~/Library/Mobile Documents/27N4MQEA55~pro~writer/Documents.

Run the following on MacOS:

Replace HOSTNAME:USERNAME/PROJECT_NAME.git with your Git project details.

3. Create a script that will be called by cron to commit changes:

Replace PROJECT_NAME with your Git project name.

Make the script executable:

By putting the script in the Applications directory, it can be called anywhere by the user, including from cron.

4. Change to your home directory and test the script:

5. Setup the crontab to run every minute:

Running every minute could be considered / is aggressive, but the overhead is pretty minor.
This redirects the output of the script to a log on the desktop, this file will need to be periodically reviewed and contents deleted.

Conclusion and Commentary

This is a work in progress, part of an experiment to see if I can be productive on iOS and make my documents more widely available. Your mileage may vary, but I would like feedback to hear others success or approaches.

Tagged geek, howto, iOS, macOS | Posted on Friday, June 14th, 2019 | Comments Off on Markdown Workflow

Comments are closed.